Geheugen van beheerde agent

Het geheugen van beheerde agents biedt uw AI-agents langetermijngeheugen in gesprekken. Azure Databricks verzorgt de infrastructuur en isoleert het geheugen van elke scope, zodat u opslag of partitionering niet zelf hoeft te beheren.

Met beheerd geheugen kunnen uw agents het volgende doen:

• Onthoud gebruikersvoorkeuren, eerdere beslissingen en geaccumuleerde context in gesprekken.
• Beveilig die kennis met Unity Catalog-governance.
• Deel deze tussen agents en projecten.
• Verbeter de nauwkeurigheid en efficiëntie in de loop van de tijd.

Requirements

• Een Databricks-werkruimte waarvoor Unity Catalog is ingeschakeld.
• De CREATE MEMORY STORE machtiging op het bovenliggende schema om geheugenopslagruimten te maken.

Hoe beheerd geheugen werkt

Beheerd geheugen heeft twee niveaus:

• Een geheugenopslag is een Unity Catalog die kan worden beveiligd als een container voor geheugenvermeldingen. Een geheugenarchief neemt dezelfde governance, toegangsbeheer en herkomst over als andere Unity Catalog-assets.
• Een geheugenvermelding is een afzonderlijk stukje inhoud dat is opgeslagen in een geheugenopslag. Elk item wordt geïdentificeerd aan de hand van een scope en een pad. De scope bepaalt bij wiens herinneringen een item hoort, en het pad ordent items binnen een scope, vergelijkbaar met een bestandspad (bijvoorbeeld /memories/preferences.md).

Scope

Bereik is hoe beheerd geheugen de geheugens van één agent gescheiden houdt voor verschillende gebruikers of groepen. Elke geheugenvermelding behoort tot precies één bereik en een zoekopdracht retourneert alleen vermeldingen binnen het bereik dat u opvraagt.

• Persoonlijk geheugen: Gebruik een eindgebruikers-id als bereik, zodat elke gebruiker zijn eigen privégeheugen krijgt, zoals hun voorkeuren en eerdere beslissingen. Gebruikers zien alleen hun eigen vermeldingen.
• Organisatiekennis: Gebruik een gedeelde sleutel, zoals een organisatie- of team-id, om kennis op te slaan waarvan elke gebruiker van de agent gebruik kan maken, zoals bedrijfsgegevens, woordenlijsten en beproefde werkwijzen.

Eén agent kan beide tegelijk gebruiken: lezen uit het persoonlijke bereik van een gebruiker en een gedeeld organisatiebereik in hetzelfde gesprek. De scope waarde is vereist voor elke aanvraag voor geheugeninvoer.

Aan de slag met beheerd geheugen

De eenvoudigste manier om beheerd geheugen toe te voegen aan een agent is de managed-memory vaardigheid Claude Code. Het verwerkt de hele installatie voor u. De vaardigheid werkt met zowel de OpenAI Agents SDK als LangGraph.

Voeg de skill op een van de volgende twee manieren toe aan uw project:

Beginnen met een sjabloon

De skill is opgenomen in de Databricks-appsjablonen. Maak een nieuwe agent op basis van een van de agentsjablonen en vind de vaardigheid onder .claude/skills/managed-memory/.

1. Kloon de opslagplaats voor sjablonen:

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

2. Blader door de app-templates, en selecteer een agentsjabloon als uitgangspunt. Als u bijvoorbeeld de SDK-sjabloon voor OpenAI Agents wilt gebruiken:

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

   Note

   Voor 'geavanceerde' app-sjablonen, na de implementatie, moet u de App Service Principal Lakebase Postgres-bevoegdheden verlenen, anders retourneert de sessie-instelling een 502 fout.

3. Zodra de vaardigheid zich in uw project bevindt, beschrijft u wat u wilt en zorgt uw coderingsassistent voor de rest:

   Tip

   Add Databricks managed long-term memory to my agent.
   

De vaardigheid toevoegen aan een bestaand project

Als u al een agentproject hebt, voeg dan de vaardigheid eraan toe.

1. Maak de map met vaardigheden als deze nog niet bestaat:

   mkdir -p .claude/skills/managed-memory
   

2. Download het SKILL.md bestand uit de managed-memory vaardigheidsmap en sla het op in .claude/skills/managed-memory/.

3. Zodra de vaardigheid zich in uw project bevindt, beschrijft u wat u wilt en zorgt uw coderingsassistent voor de rest:

   Tip

   Add Databricks managed long-term memory to my agent.
   

Een geheugenarchief maken en gebruiken

In het volgende voorbeeld wordt beheerd geheugen ingesteld voor een klantondersteuningsagent waarin de voorkeuren van een gebruiker worden opgeslagen en in een later gesprek worden opgehaald.

1. Genereer een OAuth-token met behulp van de Databricks CLI om de API's aan te roepen:

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

2. Maak een geheugenopslag om de herinneringen van uw agent op te slaan:

   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. Schrijf een geheugenvermelding nadat de agent iets over een gebruiker heeft geleerd. De scope partitioneert het item toe aan één gebruiker. Gebruik het contents veld voor de volledige geheugentekst en de description als een korte samenvatting die het ophalen verbetert:

   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. Zoek geheugenvermeldingen voor die gebruiker in een later gesprek om op te halen wat de agent heeft geleerd:

   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"
     }'
   

Zie de naslaginformatie over de geheugen-API voor de volledige REST API, inclusief eindpunten, aanvraagvelden en antwoordvelden.

Geheugen toevoegen aan een agent via gesprekken

De REST-werkstroom hierboven roept de geheugenopslag en invoer-API's rechtstreeks aan. Wanneer u een agent bouwt op een Azure Databricks model dat een eindpunt bedient, verbindt u in plaats daarvan een geheugenopslag met een gesprek met de openAI-compatibele client in de databricks-openai SDK.

Een gesprek is een OpenAI-compatibele conversatiestatus — de lopende geschiedenis van berichten en toolaanroepen — ondersteund door een geheugenopslag en gekoppeld aan één scope. Gebruik hetzelfde gesprek voor meerdere verzoeken om de agent geheugen van eerdere beurten te geven.

1. Koppel een bestaande geheugenopslag en een scope aan een nieuw gesprek. memory_store.name is de naam van de store op drie niveaus, en scope verdeelt de status van de conversatie, meestal per eindgebruiker:

   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. Geef de gespreks-id door aan responses.create. De agent leest en schrijft de status van het gesprek in de gebonden geheugenopslag binnen dat bereik:

   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. Gebruik bij latere aanvragen opnieuw dezelfde gespreks-id, zodat de agent eerdere berichten onthoudt. Maak per beurt geen nieuw gesprek:

   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)
   

Zie Gespreks-API's voor de gesprekseindpunten en aanvraagvelden.

Geheugentoegangsbeheer

Geheugenopslagplaatsen zijn beveiligbare objecten in Unity Catalog. De volgende bevoegdheden beheren de toegang:

Kortetermijngeheugen implementeren

De API's voor geheugeninvoer bieden alleen langetermijngeheugen. Gebruik een van de volgende manieren om uw agent kort geheugen in een sessie te geven:

• Bewaar de sessiestatus aan de serverzijde met een conversatie.
• Bewaar het sessiegeheugen van uw agentframework, zoals de OpenAI session=-parameter of een LangGraph-checkpointer.
• Gebruik zelfbeheerd agentgeheugen.

Limitations

• Geheugenvermeldingen bieden alleen langetermijngeheugen. Zie Korte- en langetermijngeheugen voor het verschil tussen kortetermijn- en langetermijngeheugen.
• Geheugenarchieven en vermeldingen worden alleen gemaakt en beheerd via de REST API van Unity Catalog; er is geen Python SDK voor deze API's. Als u een geheugenopslag van een agent wilt gebruiken, verbindt u deze met een gesprek met de openAI-compatibele client. Zie Geheugen toevoegen aan een agent via gesprekken.

Volgende stappen 

• Memory API-referentie