Verwalteter Speicher für Agenten

Important

Dieses Feature befindet sich in der Betaversion.

Verwalteter Agentenspeicher bietet Ihren Agenten einen dauerhaften Langzeitspeicher, der über mehrere Gespräche hinweg erhalten bleibt. Azure Databricks speichert den Speicher in Lakebase und verwaltet Speicher, Indexierung und semantische Suche für Sie, sodass Ihre Agenten Benutzerpräferenzen, bisherige Entscheidungen und den angesammelten Kontext abrufen können, ohne dass Sie eine Datenbank betreiben müssen.

Note

Während der Vorschau werden Sie für die zugrundeliegende Lakebase-Instanz abgerechnet, die Ihre Speichereinträge speichert. Für den Managed-Agent-Speicher selbst fallen keine zusätzlichen Kosten an. Die Preise können sich im Verlauf der Vorschau ändern.

Nutze Managed Memory, wenn du möchtest, dass deine Agenten:

Erinnern Sie sich an Nutzerpräferenzen, Fakten und Entscheidungen über verschiedene Gespräche hinweg.
Personalisiere die Antworten basierend auf dem, was ein Agent in früheren Sitzungen gelernt hat.
Teilen Sie gesammeltes Wissen zwischen Agenten und Projekten.
Verbessern Sie die Genauigkeit und Effizienz im Laufe der Zeit.

Managed Memory funktioniert mit Agenten, die auf jedem Framework basieren. Für eine kurzfristige Gesprächshistorie innerhalb einer einzigen Interaktion verwenden Sie verwaltete Agentensitzungen.

Anforderungen

Installiere Python 3.10 oder höher, um das AgentKit SDK zu verwenden. Das AgentKit SDK ist der Databricks-Python-Client für Agenten-APIs, den die untenstehenden Beispiele verwenden. Du kannst die REST-API auch direkt aus jeder Sprache aufrufen, ohne dass du Python brauchst.

Funktionsweise des verwalteten Speichers

Managed Agent Speicherressourcenhierarchie: Ein Speicherspeicher enthält viele Speichereinträge, die jeweils durch actor_id, optionale session_id und Pfad identifiziert werden und Inhalte sowie eine Beschreibung enthalten.

Verwalteter Speicher verfügt über zwei Ebenen:

Ein Erinnerungsspeicher ist der auf einen Workspace beschränkte Container für die Erinnerungen eines Agenten. Beim Erstellen eines Stores wird der zugrunde liegende Lakebase-Speicher automatisch bereitgestellt. Sie adressieren ein Store mit seinem display_name.
Ein Speichereintrag ist ein einzelnes Inhaltselement in einem Speicher. Jeder Eintrag enthält einen freien Text, contenteine Kurzform description für den Abruf und eine Reihe von Feldern, die ihn organisieren und aufteilen:
- actor_id (erforderlich): Wem der Speicher gehört, zum Beispiel einem Endnutzer oder einem anderen Agenten.
- session_id (optional): Gibt an, aus welcher Sitzung der Speicher erfasst wurde, zur Nachverfolgbarkeit und zum Herkunftsnachweis. Lass es für den Speicher uneingestellt, der nicht an eine bestimmte Sitzung gebunden ist.
- path (erforderlich): Ein Dateisystem-ähnlicher Pfad, der Einträge innerhalb eines Aktors organisiert, wie zum Beispiel /preferences/response-style.md.

Ein Eintrag wird eindeutig durch die Kombination von actor_id, session_id, und pathidentifiziert.

Abrufen

Speicher werden auf zwei Arten abgerufen:

Liste Einträge für einen Akteur, optional nach session_id oder einem path Präfix gefiltert. Nutzen Sie dies, um zu durchstöbern oder ein Verzeichnis dessen zu erstellen, was ein Makler weiß.
Durchsuchen Sie Einträge zu einem Akteur mithilfe einer natürlichsprachlichen Abfrage. Die Suche gibt die relevantesten Einträge zurück, geordnet nach einem Volltext-Relevanzscore (BM25).

Get started

Diese Beispiele richten verwalteten Speicher für einen Support-Agenten ein: Er erstellt einen Speicher, speichert die Präferenz eines Nutzers und ruft diese in einem späteren Gespräch ab. Wählen Sie den Kunden, der zu Ihrem Projekt passt. Ein Speicher display_name muss 3 bis 56 Zeichen umfassen, mit einem kleinen Buchstabe beginnen, mit einem Buchstaben oder einer Zahl enden und nur Kleinbuchstaben, Zahlen und Bindestriche enthalten.

AgentKit SDK

Das AgentKit SDK ist der Databricks-Python-Client für Agenten-APIs, der im Paket databricks-agentbricks verteilt wird. Die Authentifizierung erfolgt über das WorkspaceClient des Databricks SDK.

Installieren Sie das AgentKit SDK:
```
pip install databricks-agentbricks
```

Erstelle einen Speicher für deinen Agenten. AgentKitClient authentifiziert sich mit Ihren WorkspaceClient Anmeldedaten:

from databricks.sdk import WorkspaceClient
from databricks_agentkit import AgentKitClient

client = AgentKitClient(WorkspaceClient())
memory_store = client.memory_stores.create("support-agent-memory")

Speichere eine Erinnerung, nachdem der Agent etwas Dauerhaftes über einen Nutzer erfahren hat. actor_id ist, wessen Speicher dies ist, path organisiert es innerhalb dieses Akteurs und description verbessert den Abruf:

memory_store.add(
    actor_id="user-123",
    path="/preferences/communication.md",
    content="Prefers email over phone. Timezone: PST. Enterprise subscription.",
    description="User 123 communication preferences",
)

Rufen Sie die Erinnerungen des Nutzers in einem späteren Gespräch mit einer Suche in natürlicher Sprache ab:
```
results = memory_store.search(actor_id="user-123", query="communication preferences", limit=10)
```

REST API

Die Clients rufen die REST-API unter /api/2.0/agents/memory-stores. Rufen Sie sie direkt in anderen Sprachen als Python auf.

Generiere ein OAuth-Token mit der Databricks-CLI:

databricks auth login --host ${DATABRICKS_HOST}
export DATABRICKS_TOKEN=$(databricks auth token | jq -r .access_token)

Erstelle einen Speicher für deinen Agenten:

curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"display_name": "support-agent-memory", "description": "Support agent memory"}'

Speichere einen Speichereintrag für einen Benutzer. actor_id ist, wessen Speicher dies ist, path organisiert es und description verbessert den Abruf:

curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"actor_id": "user-123", "path": "/preferences/communication.md", "content": "Prefers email over phone.", "description": "Communication preferences"}'

Rufen Sie die Erinnerungen des Nutzers mit einer Suche in natürlicher Sprache ab:

curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries:search" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"actor_id": "user-123", "query": "communication preferences"}'

Gib deinem Agenten Gedächtniswerkzeuge

Damit ein Agent selbst entscheiden kann, wann Speicher gespeichert und abgerufen werden soll, packen Sie die Client-Operationen als Werkzeuge und geben dem Agenten in seiner Systemaufforderung Anweisungen an, wann er sie verwenden soll. Legen Sie den actor_id im vertrauenswürdigen Anwendungscode anhand der verifizierten Endbenutzeridentität fest. Lass das Modell niemals entscheiden, wessen Speicher es liest oder schreibt.

Das folgende Beispiel verpackt das AgentKit-SDK memory_store aus Erste Schritte als Tools für das OpenAI Agents SDK.

from agents import Agent, function_tool

def make_memory_tools(memory_store, actor_id: str):
    @function_tool
    def search_memory(query: str) -> str:
        """Search long-term memory for relevant facts about the user."""
        results = memory_store.search(actor_id=actor_id, query=query, limit=10)
        return "\n\n".join(f"{r.memory.path}: {r.memory.content}" for r in results) or "No memory found."

    @function_tool
    def save_memory(path: str, content: str, description: str = "") -> str:
        """Save a durable, long-term memory about the user."""
        memory_store.add(actor_id=actor_id, path=path, content=content, description=description)
        return f"Saved memory at {path}"

    return [search_memory, save_memory]

agent = Agent(
    name="Support agent",
    instructions="Save durable user preferences and recall them when relevant.",
    tools=make_memory_tools(memory_store, actor_id="user-123"),
)

Dasselbe Muster funktioniert mit dem Claude Agent SDK und anderen Frameworks: Kapseln Sie die Such- und Hinzufügeoperationen des Stores als Tool-Typ des Frameworks.

Partition und sicherer Speicher

In einem Store trennt actor_id, welche Erinnerungen zu wem gehören. Jede Liste und jede Suche ist auf ein einzelnes actor_id begrenzt. Wählen Sie also die Strategie, die dazu passt, was Ihr Agent sich merken muss:

Privater Speicher für jeden Benutzer: Legen Sie actor_id auf die verifizierte Endbenutzeridentität fest. Jeder Benutzer erhält seine eigene Partition, und der Agent ruft nur die Einträge dieses Benutzers ab.
- Beispiel: Ein Support-Mitarbeiter merkt sich an die Kommunikationspräferenzen eines Nutzers und frühere Tickets.
Gemeinsamer Speicher für eine Gruppe: Setzen actor_id Sie auf einen festen Schlüssel, den Sie wählen, wie zum Beispiel eine Team-, Projekt- oder Organisations-ID. Jeder liest und schreibt dieselben Erinnerungen.
- Beispiel: Ein Teamagent merkt sich ein gemeinsames Glossar mit Unternehmensbegriffen und internen Konventionen.
Speicheraufteilung durch ein anderes Kriterium: Erstellen Sie actor_id aus eigenen Werten, wie z. B. einer Mandanten-ID oder einem user:project zusammengesetzten Wert.
- Beispiel: Eine Multi-Tenant-App setzt {tenant}:{user} auf actor_id, sodass die Benutzer der einzelnen Kunden voneinander isoliert bleiben.

Legen Sie actor_id in Ihrem Anwendungscode aus einem vertrauenswürdigen Aufruferkontext fest: die verifizierte Endnutzeridentität für benutzerspezifischen Speicher oder einen vertrauenswürdigen Team- oder Projektschlüssel für gemeinsamen Speicher. Lass niemals das Modell es selbst wählen. Wenn Ihre Strategie auf einer Endbenutzeridentität basiert, lehnen Sie Anfragen ab, die keine solche enthalten, anstatt auf eine gemeinsam genutzte Identität actor_idzurückzugreifen.

Warning

actor_id trennt Erinnerungen, aber es ist keine Zugangskontrolle. Managed Memory Stores sind auf den Workspace beschränkt, sodass jeder Prinzipal, der auf einen Speicher zugreifen kann, jeden Eintrag aller Akteure lesen und schreiben kann. Der Laden, nicht der Akteur, ist die Sicherheitsgrenze. Für eine strikte Isolation zwischen Tenants oder Benutzern erstellen Sie pro Grenze einen separaten Speicher.

Um einem anderen Prinzipal, etwa dem Serviceprinzipal Ihres Agenten, die Nutzung eines Stores zu ermöglichen, gewähren Sie ihm mit dem Vorgang „grant-permission“ des Stores (memory_store.grant_permission(principal_id) im AgentKit SDK) Zugriff.

Einschränkungen

Das verwaltete Gedächtnis bietet nur Langzeitgedächtnis. Für den kurzfristigen Konversationsverlauf siehe verwaltete Agentensitzungen.
Die Suche ist eine nach Relevanz gewichtete Volltextoperation (BM25), die eine Top-N-Ergebnismenge mit bis zu 100 Einträgen zurückgibt. Es unterstützt keine Paginierung oder Vektorähnlichkeitssuche.
Die Zugangskontrolle wird auf Ladenebene durchgesetzt. Zugriffskontrollen pro Eingang und pro Akteur sind nicht verfügbar.
Der Speicher display_name ist nach der Erstellung unveränderbar. Nur description kann aktualisiert werden.

Nächste Schritte

Feedback

War diese Seite hilfreich?

Zuletzt aktualisiert um 2026-10-06