Verwalteter Speicher für Agenten

Verwalteter Agentenspeicher gibt Ihren Agenten ein Langzeitgedächtnis über mehrere Unterhaltungen hinweg. Azure Databricks führt die Infrastruktur aus und isoliert die Speicher jedes Bereichs, sodass Sie nicht selbst Speicher oder Partitionierung 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.
• Freigeben von Arbeitsspeicher über Agents und Projekte hinweg.
• Verbessern Sie ihre Genauigkeit und Effizienz im Laufe der Zeit.

Anforderungen

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

Funktionsweise des verwalteten Speichers

Verwalteter Speicher verfügt über zwei Ebenen:

• Ein Speicher ist ein sicherungsfähiges Unity Catalog-Objekt, 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

Scope ist, wie man einen Speicher für einen Nutzer privat macht oder ihn in einer Gruppe teilt. Ihre Anwendung legt bei jedem Lesen und Schreiben einen Scope fest, und eine Suche liefert nur Einträge mit entsprechendem Scope. Wählen Sie die Strategie, die zu dem passt, was Ihr Makler sich merken muss:

• Privater Speicher für jeden Nutzer: Stellen Sie den Umfang auf die verifizierte Endbenutzeridentität ein. Jeder Nutzer erhält seine eigene Partition und sieht nur seine eigenen Einträge. Der Wert user_client löst die ID des Endnutzers für Sie auf.
  • Beispiel: Ein Support-Mitarbeiter merkt sich an die Kommunikationspräferenzen eines Nutzers und frühere Tickets.
• Gemeinsames Gedächtnis für eine Gruppe: Setze den Umfang auf einen festen Schlüssel, den du wählst, wie zum Beispiel eine Organisation, ein Team oder eine Projekt-ID. Jeder Nutzer liest und schreibt dieselben Erinnerungen.
  • Beispiel: Ein Teammitarbeiter merkt sich ein gemeinsames Glossar mit Unternehmensbegriffen und internen Richtlinien.
• Erinnerung geteilt durch etwas anderes: Erstellen Sie den Scope aus Ihren eigenen Werten, wie zum Beispiel einer Mandanten-ID oder einem user_id:project-Composite.
  • Beispiel: Eine Multi-Tenant-App hält den Speicher jedes Kunden getrennt, oder der Speicher eines einzelnen Benutzers ist pro Projekt isoliert.

Ein einzelner Agent kann Strategien in einem Gespräch kombinieren. Zum Beispiel kann es den privaten Speicher eines Benutzers und einen gemeinsamen Teamspeicher in derselben Anfrage lesen.

Stellen Sie den Umfang in Ihrem Anwendungscode an, basierend auf dem Kontext des vertrauenswürdigen Anrufers, den die Anfrage nicht manipulieren kann: die verifizierte Endbenutzeridentität aus dem OBO-Token für den Benutzerspeicher oder einen vertrauenswürdigen Tenant, Team- oder Projektschlüssel für den gemeinsamen Speicher. Lass niemals das Modell es selbst wählen. Wenn Ihre Scope-Strategie von einer Endbenutzeridentität abhängt, lehnen Sie Anfragen ab, für die keine Endbenutzeridentität vorliegt, anstatt auf einen gemeinsamen Berechtigungsbereich zurückzugreifen. Der managed-memorySkill führt Sie durch dieses Setup.

Scope trennt Speicher, gewährt aber keinen Zugriff auf den Speicher. Ein Aufrufer benötigt weiterhin das READ MEMORY STORE- oder WRITE MEMORY STORE-Privileg, um es zu öffnen. Siehe Speicherzugriffskontrolle.

Was der Agent speichert und abruft

Managed Memory stellt den Speicher und die APIs für das Lesen und Schreiben von Einträgen bereit. Ihre Anwendung steuert, was der Agent speichert, wann er Speicher abruft und wie er die Ergebnisse verwendet.

Definieren Sie dieses Verhalten im Systemprompt des Agenten: Geben Sie dem Agenten Anweisungen an, welche dauerhaften Informationen gespeichert werden sollen und wann sie abgerufen werden sollen. Der managed-memory-Skill und die Vorlagen speichern diesen Systemprompt in einer Konstante namens MEMORY_INSTRUCTIONS. Scope ist separat im vertrauenswürdigen Anwendungscode konfiguriert und wird nie vom Modell gewählt.

Passen Sie die Formulierung an Ihre Scope-Strategie an. Im Folgenden ist ein Beispiel für die Strategie pro Nutzer:

You have durable, cross-session memory about whoever (or whatever) this conversation is scoped to. Use it deliberately, not by reflex.

Recall whenever the answer is about the user or calls for personalized information — anything that might draw on preferences, decisions, or workflows they've shared before — and you don't already have it from this conversation; also list once before saving, to find the right existing topic. Don't tell the user you don't know their preferences without checking — list_memories first. Skip memory only when the answer truly doesn't depend on who's asking (general knowledge, math, coding) or you already have what you need. A `[has_contents]` entry has a body to get_memory; one without is fully captured by its description. Open a memory with get_memory before you state its specifics, and never assert a fact that isn't stored — if nothing relevant is stored, just answer without it. Don't re-list what you've already seen this turn.

Save only what will still matter in a future, unrelated conversation — a stable preference, fact, decision, or ongoing project the user actually stated or decided. Don't save your own suggestions or guesses, passing chatter, secrets, or anything scoped to this chat ("for now", a one-off label).
- Write each memory so it stands on its own out of context, under one broad, stable /memories/... topic per subject with the specifics inside it.
- Check the list first and update_memory an existing topic instead of minting a near-duplicate.
- For a very broad question that touches many memories, summarize from the list's descriptions; reserve get_memory for the specific entry you actually need.
- If the user's info changes or contradicts what's stored, update or replace it rather than keeping both — but don't rewrite a memory that already says the same thing.
- delete_memory what's stale.
- Briefly tell the user whenever you save, update, or delete.

Fang mit Managed Memory Skills an

Die einfachste Möglichkeit, einem Agenten verwalteten Speicher hinzuzufügen, ist die managed-memory Claude Code-Fähigkeit. Die Fähigkeit übernimmt das komplette Setup für Sie und arbeitet 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

Der Skill ist in den Databricks-App-Vorlagen enthalten. Erstellen Sie einen neuen Agent mithilfe einer der Agent-Vorlagen, und finden Sie den Skill unter .claude/skills/managed-memory/.

1. Klonen Sie das Vorlagen-Repository:

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

2. Durchsuchen Sie app-templates, und wählen Sie eine Agent-Vorlage 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 dem 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.
   

Manuelles Erstellen und Verwenden eines Speicherspeichers

In diesem Abschnitt wird gezeigt, wie Sie einen Speicher ohne die Kenntnisse von managed-memory Claude Code erstellen und verwenden.

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-Modellbereitstellungs-Endpunkt erstellen, verbinden Sie stattdessen einen Speicher mit einer Konversation 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 gebundenen Speicher innerhalb dieses Bereichs:

   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 Konversation pro Runde:

   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 einen langfristigen Speicher als Tools, die Ihr Agent verwenden kann. Um Ihrem Agenten in einer Sitzung verwalteten Kurzzeitspeicher bereitzustellen, empfiehlt Databricks, Ihren Memory-Store an eine Konversation zu binden. Sie können außerdem:

• Behalten Sie den Sitzungsspeicher Ihres Agentframeworks bei, z. B. den OpenAI-Parameter session= oder einen LangGraph-Prüfpunkt.
• Verwenden Sie selbstverwalteten Agentenspeicher als Speicher für den Konversationsverlauf.

Sicherheitsempfehlungen

Azure Databricks stellt den verwalteten Speicher sowie Verschlüsselungs- und Isolationsmechanismen und ein Auditprotokoll bereit. Als App-Entwickler empfiehlt Databricks Folgendes:

• Verwenden Sie die Standardeinstellung für den Benutzerbereich (user_client), es sei denn, Sie haben einen absichtlichen Grund, anders zu partitionieren (z. B. pro Projekt oder Speicher pro Konto).
• Gewähren Sie nur die geringstmöglichen Berechtigungen: Nur die Dienstidentität Ihres Agenten benötigt WRITE MEMORY STORE. Gewähren Sie READ MEMORY STORE nur restriktiv, und vermeiden Sie weitreichende Berechtigungen für menschliche Nutzer oder große Gruppen.
• Schützen Sie die Anmeldeinformationen der App Service-Dienstidentität: Sie sind der Schlüssel zur Datenebene des Datenspeichers. Behandeln Sie sie wie alle hochwertigen Dienstanmeldeinformationen – verwenden Sie kurzlebige Token, vermeiden Sie die Protokollierung, und fügen Sie Ihrer App SSRF-Abwehrmaßnahmen hinzu.

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. Weitere Informationen finden Sie unter Hinzufügen von Speicher zu einem Agent mithilfe von Konversationen.

Nächste Schritte

• Speicher-API-Referenz