Verwalteter Speicher für Agenten

Important

Dieses Feature befindet sich in der Betaversion. Arbeitsbereichsadministratoren können den Zugriff auf dieses Feature über die Vorschauseite steuern. Siehe Manage Azure Databricks Previews.

Verwalteter Speicher für Agenten ermöglicht Ihren KI-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

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 im Bereich zurück, den Sie abfragen.

  • 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. Der Bereichswert user_client ruft automatisch die ID des Endbenutzers ab.
  • 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.

Warning

Bereich ist die Isolationsgrenze zwischen Benutzern. Konfigurieren Sie den Geltungsbereich in vertrauenswürdigem Code, und lassen Sie niemals zu, dass das Modell ihn festlegt. Der App-Dienstprinzipal kann alle Bereiche lesen.

Erste Schritte mit verwalteten Speicherfähigkeiten

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:

Privileg Gilt für: Beschreibung
CREATE MEMORY STORE Übergeordnetes Schema Erstellen Sie neue Speicherspeicher unter einem Schema.
READ MEMORY STORE Speicherbereich Lesen Sie die Metadaten eines Speichers und deren Einträge.
WRITE MEMORY STORE Speicherbereich Erstellen, Aktualisieren und Löschen von Speichereinträgen in einem Speicher.
MANAGE Speicherbereich Aktualisieren oder löschen Sie den Datenspeicher selbst. Erteilen von Berechtigungen für andere Benutzer.
USE SCHEMA Übergeordnetes Schema Speicher in einem Schema auflisten.

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 minimal erforderlichen Berechtigungen: Nur der Dienstprinzipal Ihres Agents 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 des Dienstprinzipals der App: Sie sind der Schlüssel zur Datenebene des Speichers. 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

  • Last updated on