Verwalteter Speicher für Agenten

Verwalteter Speicher für Agenten ermöglicht Ihren KI-Agenten ein Langzeitgedächtnis über mehrere Unterhaltungen hinweg. Azure Databricks betreibt die Infrastruktur und isoliert den Speicher jedes Scopes, sodass Sie Speicher oder Partitionierung nicht selbst verwalten müssen.

Mit verwaltetem Speicher können Ihre Agents:

• Denken Sie an Benutzereinstellungen, vergangene Entscheidungen und angesammelten Kontext in Unterhaltungen.
• Sichern Sie dieses Wissen mit Unity Catalog Governance.
• Teilen Sie sie über Agenten und Projekte hinweg.
• Verbessern Sie die Genauigkeit und Effizienz im Laufe der Zeit.

Anforderungen

• Ein Databricks-Arbeitsbereich mit aktiviertem Unity-Katalog.
• Die CREATE MEMORY STORE Berechtigung für das übergeordnete Schema zum Erstellen von In-Memory-Speichern.

Funktionsweise des verwalteten Speichers

Verwalteter Speicher verfügt über zwei Ebenen:

• Ein Speicher ist ein sicherbares Objekt in Unity Catalog, das als Container für Speichereinträge dient. Ein Speicher erbt die gleiche Governance, Zugriffssteuerung und Lineage wie jedes andere Unity Catalog-Objekt.
• Ein Speichereintrag ist ein einzelner Inhalt, der in einem Speicher gespeichert ist. Jeder Eintrag wird durch einen Bereich und einen Pfad identifiziert. Der Bereich bestimmt, zu welchem Speicher ein Eintrag gehört, und der Pfad organisiert Einträge innerhalb eines Bereichs, ähnlich einem Dateipfad (z. B /memories/preferences.md. ).

Geltungsbereich

Der Geltungsbereich bezeichnet, wie verwalteter Speicher die Erinnerungen eines Agenten für verschiedene Benutzer oder Gruppen getrennt hält. Jeder Speichereintrag gehört zu genau einem Bereich, und eine Suche gibt nur Einträge innerhalb des abfragebezogenen Bereichs zurück.

• Persönlicher Speicher: Verwenden Sie eine Endbenutzer-ID als Bereich, damit jeder Benutzer seinen eigenen privaten Speicher erhält, z. B. seine Einstellungen und frühere Entscheidungen. Benutzer sehen nur ihre eigenen Einträge.
• Organisationswissen: Verwenden Sie einen freigegebenen Schlüssel, z. B. eine Organisation oder Team-ID, um Wissen zu speichern, auf das jeder Benutzer des Agenten zurückgreifen kann, z. B. Unternehmensdaten, Glossare und bewährte Methoden.

Ein einzelner Agent kann beides gleichzeitig nutzen: in derselben Unterhaltung sowohl aus dem persönlichen Bereich eines Nutzers als auch aus einem gemeinsam genutzten Organisationsbereich lesen. Dies scope ist für jede Speichereingabeanforderung erforderlich.

Erste Schritte mit verwaltetem Speicher

Die einfachste Möglichkeit, einem Agenten verwalteten Speicher hinzuzufügen, ist die managed-memory Claude Code-Fähigkeit. Es übernimmt die gesamte Einrichtung für Sie. Die Fähigkeit funktioniert sowohl mit dem OpenAI Agents SDK als auch mit LangGraph.

Fügen Sie den Skill auf eine von zwei Arten Ihrem Projekt hinzu:

Mit einer Vorlage beginnen

Die Funktion ist in den Databricks-App-Vorlagen enthalten. Erstellen Sie einen neuen Agenten anhand einer der Agent-Vorlagen, und finden Sie die Fähigkeit unter .claude/skills/managed-memory/.

1. Klonen Sie das Vorlagen-Repository:

   git clone https://github.com/databricks/app-templates.git
   

2. Durchsuchen Sie die app-templates, und wählen Sie eine Agentvorlage aus, mit der Sie beginnen möchten. So verwenden Sie z. B. die OpenAI Agents SDK-Vorlage:

   cd app-templates/agent-openai-agents-sdk
   

   Note

   Bei "erweiterten" App-Vorlagen müssen Sie nach der Bereitstellung den App-Dienstprinzipal Lakebase Postgres-Berechtigungen erteilen, andernfalls gibt das Sitzungssetup einen 502 Fehler zurück.

3. Sobald sich die Fähigkeit in Ihrem Projekt befindet, beschreiben Sie, was Sie wollen, und Ihr Codierungsassistent kümmert sich um den Rest:

   Tip

   Add Databricks managed long-term memory to my agent.
   

Hinzufügen der Fähigkeit zu einem vorhandenen Projekt

Wenn Sie bereits ein Agentprojekt haben, fügen Sie dem Projekt den Skill hinzu.

1. Erstellen Sie das Kompetenzverzeichnis, wenn es nicht vorhanden ist:

   mkdir -p .claude/skills/managed-memory
   

2. Laden Sie die SKILL.md Datei aus dem managed-memory Qualifikationsverzeichnis herunter, und speichern Sie sie in .claude/skills/managed-memory/.

3. Sobald sich die Fähigkeit in Ihrem Projekt befindet, beschreiben Sie, was Sie wollen, und Ihr Codierungsassistent kümmert sich um den Rest:

   Tip

   Add Databricks managed long-term memory to my agent.
   

Erstellen und Verwenden eines Speichers

Im folgenden Beispiel wird verwalteter Speicher für einen Kundensupport-Agent eingerichtet, der die Einstellungen eines Benutzers speichert und sie in einer späteren Unterhaltung abruft.

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

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

2. Erstellen Sie einen Speicher, um die Erinnerungen Ihres Agenten zu speichern:

   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": "support_agent_memory",
       "catalog_name": "main",
       "schema_name": "default",
       "description": "Long-term memory for the customer support agent"
     }'
   

3. Schreiben Sie einen Speichereintrag, nachdem der Agent etwas über einen Benutzer gelernt hat. Die scope ordnet den Eintrag einem einzelnen Benutzer zu. Verwenden Sie das contents Feld für den vollständigen Speichertext und die description als kurze Zusammenfassung, die den Abruf verbessert:

   curl -X POST \
     "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.support_agent_memory/entries?scope=user-123" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "path": "/memories/preferences.md",
       "contents": "Prefers email communication. Timezone: PST. Has an Enterprise subscription.",
       "description": "User 123 communication preferences and account details"
     }'
   

4. Durchsuchen Sie Speichereinträge für diesen Benutzer in einer späteren Unterhaltung, um abzurufen, was der Agent gelernt hat:

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

Die vollständige REST-API, einschließlich Endpunkte, Anforderungsfelder und Antwortfelder, finden Sie in der Speicher-API-Referenz.

Einem Agenten Speicher mithilfe von Konversationen hinzufügen

Der obige REST-Workflow ruft den Speicherspeicher und die Eintrags-APIs direkt auf. Wenn Sie einen Agent auf einem Azure Databricks Modell für Endpunkte erstellen, verbinden Sie stattdessen einen Speicherspeicher mit dem openAI-kompatiblen Client im databricks-openai SDK.

Eine Unterhaltung ist ein OpenAI-kompatibler Konversationszustand – der fortlaufende Verlauf von Nachrichten und Tool-Aufrufen –, der auf einem Speicher basiert und an genau einen Geltungsbereich gebunden ist. Verwenden Sie dieselbe Konversation über mehrere Anfragen hinweg, damit sich der Agent an frühere Gesprächsverläufe erinnern kann.

1. Binden Sie einen vorhandenen Speicher und einen Gültigkeitsbereich an eine neue Konversation. memory_store.name ist der Name der drei Ebenen des Speichers und scope partitioniert den Status der Unterhaltung, in der Regel nach Endbenutzern:

   from databricks.sdk import WorkspaceClient
   from databricks_openai import DatabricksOpenAI
   
   workspace_client = WorkspaceClient()
   user_id = str(workspace_client.current_user.me().id)
   
   client = DatabricksOpenAI(workspace_client=workspace_client, use_ai_gateway=True)
   
   conversation = client.conversations.create(
       extra_body={
           "memory_store": {"name": "main.default.support_agent_memory"},
           "scope": {"kind": "user", "value": user_id},
       },
   )
   

2. Übergeben Sie die Unterhaltungs-ID an responses.create. Der Agent liest und schreibt den Zustand der Konversation im zugeordneten Speicher innerhalb dieses Gültigkeitsbereichs:

   response = client.responses.create(
       model="databricks-gpt-5-2",
       conversation=conversation.id,
       input=[{"type": "message", "role": "user", "content": "What is the average NYC taxi price?"}],
       stream=True,
   )
   
   for event in response:
       if event.type == "response.output_text.delta":
           print(event.delta, end="", flush=True)
   

3. Verwenden Sie bei späteren Anfragen dieselbe Konversations-ID, damit sich der Agent an frühere Gesprächsverläufe erinnert. Erstellen Sie keine neue Unterhaltung pro Turn:

   followup = client.responses.create(
       model="databricks-gpt-5-2",
       conversation=conversation.id,
       input=[{"type": "message", "role": "user", "content": "Restate the average taxi price you found, and how it was calculated."}],
       stream=True,
   )
   
   for event in followup:
       if event.type == "response.output_text.delta":
           print(event.delta, end="", flush=True)
   

Informationen zu den Unterhaltungsendpunkten und Anforderungsfeldern finden Sie unter Unterhaltungs-APIs.

Speicherzugriffssteuerung

Memory Stores sind in Unity Catalog absicherbare Objekte. Die folgenden Berechtigungen steuern den Zugriff:

Kurzzeitgedächtnis implementieren

Die Speichereingabe-APIs bieten nur einen langfristigen Speicher. Verwenden Sie einen der folgenden Optionen, um Ihrem Agent in einer Sitzung kurzfristigen Speicher zu geben:

• Speichern Sie den Sitzungszustand serverseitig mit einer Konversation.
• Behalten Sie den Sitzungsspeicher Ihres Agentframeworks bei, z. B. den OpenAI-Parameter session= oder einen LangGraph-Prüfpunkt.
• Verwenden Sie den selbstverwalteten Agent-Speicher.

Einschränkungen

• Speichereinträge bieten nur Langzeitspeicherung. Zum Unterschied zwischen Kurzzeit- und Langzeitgedächtnis siehe Kurzzeit- und Langzeitgedächtnis.
• Speicher und Einträge werden ausschließlich über die REST-API von Unity Catalog erstellt und verwaltet; für diese APIs gibt es kein Python-SDK. Um einen Speicher von einem Agent zu verwenden, verbinden Sie ihn mit einer Unterhaltung mit dem openAI-kompatiblen Client. Siehe Speicher mithilfe von Konversationen zu einem Agenten hinzufügen.

Nächste Schritte

• Speicher-API-Referenz