Speicher-API-Referenz

Diese Seite ist die REST-API-Referenz für verwalteten Agent-Speicher. Sie deckt die Endpunkte, Anforderungsfelder und Antwortfelder für verwalteten Speicher ab:

• Ein Speicher ist ein Unity-Katalog sicherungsfähig, der als Container für Speichereinträge fungiert. Verwenden Sie die Speicherspeicher-APIs , um Speicher zu erstellen und zu verwalten.
• Ein Speichereintrag ist ein einzelner Inhalt, der in einem Speicher gespeichert ist. Verwenden Sie die Speichereingabe-APIs zum Lesen und Schreiben von Einträgen.
• Eine Unterhaltung ist openAI-kompatibler Unterhaltungszustand – Nachrichten und Toolanrufe – unterstützt durch einen Speicher und angeheftet an einen Bereich. Verwenden Sie die Unterhaltungs-APIs , um Unterhaltungen und deren Elemente zu erstellen und zu verwalten.

Voraussetzungen

Generieren Sie ein OAuth-Token mithilfe der Databricks CLI, um die APIs aufzurufen:

databricks auth login --host ${DATABRICKS_HOST}
databricks auth token

Speicher-APIs

Ein Speicher ist ein Unity-Katalog sicherungsfähig, der als Container für Speichereinträge fungiert. Speicher verwenden die Benennung auf drei Ebenen: catalog.schema.memory_store_name.

Erstellen eines Speichers

Erstellt einen neuen Speicherspeicher unter einem übergeordneten Schema.

• Endpunkt:POST /api/2.1/unity-catalog/memory-stores
• Erforderliche Berechtigungen: CREATE MEMORY STORE im übergeordneten Schema

curl -X POST "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "agent_memory",
    "catalog_name": "main",
    "schema_name": "default",
    "description": "Memory store for customer support agents"
  }'

Anforderungsfelder:

Abrufen eines Speichers

Ruft einen Speicher mit seinem dreiteiligen vollqualifizierten Namen ab.

• Endpunkt:GET /api/2.1/unity-catalog/memory-stores/{full_name}
• Erforderliche Berechtigungen: READ MEMORY STORE im Store

curl -X GET \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Liste von Speicherplätzen

Listet Speicher in einem Schema auf. Ergebnisse werden gefiltert, um den Aufrufer lesen zu können.

• Endpunkt:GET /api/2.1/unity-catalog/memory-stores
• Erforderliche Berechtigungen: USE SCHEMA im übergeordneten Schema

curl -X GET \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores?catalog_name=main&schema_name=default" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Abfrageparameter:

Aktualisieren eines Speichers

Aktualisiert veränderbare Felder in einem Speicher. Derzeit ist nur description änderbar.

• Endpunkt:PATCH /api/2.1/unity-catalog/memory-stores/{full_name}
• Erforderliche Berechtigungen: MANAGE im Store

curl -X PATCH \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "memory_store": {
      "description": "Updated description for the memory store"
    },
    "update_mask": "description"
  }'

Löschen eines Speichers

Löscht einen Speicher und alle zugehörigen Speichereinträge.

• Endpunkt:DELETE /api/2.1/unity-catalog/memory-stores/{full_name}
• Erforderliche Berechtigungen: MANAGE im Store

curl -X DELETE \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Antwortfelder für Speicherspeicher

Speichereingabe-APIs

Speichereinträge sind die einzelnen Inhalte, die in einem Speicher gespeichert sind. Jeder Eintrag wird durch einen Bereich und einen Pfad identifiziert: scope ist ein Partitionsschlüssel, den der Aufrufer zuweist (z. B. eine Endbenutzer-ID), und path es handelt sich um einen weichen Pfad innerhalb dieses Bereichs, der mit /memories/ diesem Bereich beginnen muss (z /memories/preferences.md. B. ). scope ist für jede Speichereingabeanforderung erforderlich.

Erstellen eines Speichereintrags

Erstellt einen neuen Speichereintrag in einem Speicher.

• Endpunkt:POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries?scope=<scope>
• Erforderliche Berechtigungen: WRITE MEMORY STORE im Store

scope ist ein Abfrageparameter; Der Anforderungstext ist der Eintrag selbst.

curl -X POST \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries?scope=user-42" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/memories/preferences.md",
    "contents": "The user prefers responses in English and uses formal tone.",
    "description": "User language and tone preferences"
  }'

Anforderungsfelder:

Abrufen eines Speichereintrags

Ruft einen einzelnen Speichereintrag nach scope und path.

• Endpunkt:GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries:get
• Erforderliche Berechtigungen: READ MEMORY STORE im Store

curl -X GET \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries:get?scope=user-42&path=/memories/preferences.md" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Auflisten von Speichereinträgen

Listet Speichereinträge in einem Bereich auf.

• Endpunkt:GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries
• Erforderliche Berechtigungen: READ MEMORY STORE im Store

curl -X GET \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries?scope=user-42" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Abfrageparameter:

Listenantworten werden weggelassen contents (nur Metadaten), und fügen Sie ein next_page_token , wenn weitere Seiten verbleiben.

Aktualisieren eines Speichereintrags

Wendet einen einzelnen Bearbeitungsvorgang auf die von und zu einem vorhandenen Eintrag contentsidentifizierten scope Einträge pathan. Geben Sie genau einen von str_replace, insert, oder replace_all. description kann bearbeitet werden: Legen Sie sie fest, um die Beschreibung des Eintrags zu ersetzen, oder lassen Sie sie aus, um die Beschreibung unverändert zu lassen.

• Endpunkt:PATCH /api/2.1/unity-catalog/memory-stores/{full_name}/entries
• Erforderliche Berechtigungen: WRITE MEMORY STORE im Store

curl -X PATCH \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user-42",
    "path": "/memories/preferences.md",
    "replace_all": { "contents": "The user prefers responses in Spanish and uses casual tone." }
  }'

Bearbeitungsvorgänge (genau eins festlegen):

Löschen eines Speichereintrags

Löscht einen Speichereintrag, der durch scope und path.

• Endpunkt:DELETE /api/2.1/unity-catalog/memory-stores/{full_name}/entries
• Erforderliche Berechtigungen: WRITE MEMORY STORE im Store

curl -X DELETE \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries?scope=user-42&path=/memories/preferences.md" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Durchsuchen von Speichereinträgen

Durchsucht Speichereinträge nach Schlüsselwort über Pfad-, Inhalts- und Beschreibungsfelder hinweg.

• Endpunkt:POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries:search
• Erforderliche Berechtigungen: READ MEMORY STORE im Store

curl -X POST \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries:search" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user-42",
    "query": "language preferences"
  }'

Anforderungsfelder: scope (erforderlich), query (erforderlich), (optional), path_prefixtop_k (optional; Standardwert ist 10, max. 50).

Antwortfelder für Speichereingaben

Unterhaltungs-APIs

Eine Unterhaltung speichert den OpenAI-kompatiblen Unterhaltungszustand – Nachrichten, Toolanrufe und andere Elemente – in einem Speicher unter einem einzigen Bereich. Bei einer Unterhaltung wird ein Agent auf serverseitiger Sitzungszustand beibehalten und neu geladen. Sie erstellen jede Unterhaltung anhand eines Speicherspeichers (dreiteiliger Name) und einer scopeUnterhaltung, und Unterhaltungsvorgänge erfordern dieselben Berechtigungen wie der zugrunde liegende Speicher.

Erstellen einer Unterhaltung

Erstellt eine Unterhaltung, die an einen Speicher und einen Bereich gebunden ist.

• Endpunkt:POST /api/2.1/unity-catalog/conversations
• Erforderliche Berechtigungen: WRITE MEMORY STORE im Store

curl -X POST "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/conversations" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "memory_store": { "name": "main.default.support_agent_memory" },
    "scope": { "kind": "user", "value": "user-123" },
    "metadata": { "source": "support-chat" }
  }'

Anforderungsfelder:

Abrufen einer Unterhaltung

Ruft eine Unterhaltung anhand ihrer ID ab.

• Endpunkt:GET /api/2.1/unity-catalog/conversations/{conversation_id}
• Erforderliche Berechtigungen: READ MEMORY STORE im Store

curl -X GET \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/conversations/${CONVERSATION_ID}" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Aktualisieren einer Unterhaltung

Aktualisiert die Unterhaltungen metadata.

• Endpunkt:POST /api/2.1/unity-catalog/conversations/{conversation_id}
• Erforderliche Berechtigungen: WRITE MEMORY STORE im Store

curl -X POST \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/conversations/${CONVERSATION_ID}" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "source": "support-chat", "resolved": "true" } }'

Löschen einer Unterhaltung

Löscht eine Unterhaltung und deren Elemente.

• Endpunkt:DELETE /api/2.1/unity-catalog/conversations/{conversation_id}
• Erforderliche Berechtigungen: WRITE MEMORY STORE im Store

curl -X DELETE \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/conversations/${CONVERSATION_ID}" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Unterhaltungsantwortfelder

Unterhaltungselement-APIs

Elemente sind die einzelnen Nachrichten und Toolaufrufe innerhalb einer Unterhaltung. Sie folgen dem OpenAI-Unterhaltungselemente-Shape und verwenden openAI-kompatible Paginierung (after, limit, has_more).