Geheugen van beheerde agent

Important

Deze functie bevindt zich in de bètaversie. Werkruimtebeheerders kunnen de toegang tot deze functie beheren vanaf de pagina Previews . Zie Azure Databricks previews beheren.

Het geheugen van de beheerde agent biedt uw agents langetermijngeheugen in gesprekken. Azure Databricks voert de infrastructuur uit en isoleert de gegevens van elke scope, zodat u zelf geen opslag of partities 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 het geheugen tussen agents en projecten.
• Verbeter hun 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

Scope is hoe je een geheugen privé maakt voor één gebruiker of gedeeld binnen een groep. Je applicatie stelt bij elke read en write een scope in, en een zoekopdracht levert alleen vermeldingen met een overeenkomend bereik op. Kies de strategie die aansluit bij wat je makelaar moet onthouden:

• Privégeheugen voor elke gebruiker: Stel de scope in op de geverifieerde eindgebruikersidentiteit. Elke gebruiker krijgt zijn eigen partitie en ziet alleen zijn eigen items. De waarde user_client lost de ID van de eindgebruiker voor je op.
  • Voorbeeld: Een supportmedewerker onthoudt de communicatievoorkeuren en eerdere tickets van één gebruiker.
• Gedeeld geheugen voor een groep: Stel de scope in op een vaste sleutel die je kiest, zoals een organisatie, team of project-ID. Elke gebruiker leest en schrijft dezelfde herinneringen.
  • Voorbeeld: Een teammedewerker onthoudt een gedeeld woordenlijstje van bedrijfstermen en interne beleidsregels.
• Geheugen gesplitst door iets anders: Bouw de scope op van je eigen waarden, zoals een tenant-ID of een composite.user_id:project
  • Voorbeeld: Een multi-tenant app houdt het geheugen van elke klant gescheiden, of het geheugen van één gebruiker wordt per project geïsoleerd.

Een enkele agent kan strategieën combineren in één gesprek. Zo kan het bijvoorbeeld het privégeheugen van een gebruiker en het gedeelde teamgeheugen in hetzelfde verzoek lezen.

Stel de scope in je applicatiecode in, op basis van een vertrouwde aanroepcontext waarmee niet door het verzoek kan worden geknoeid: de geverifieerde identiteit van de eindgebruiker uit het OBO-token voor geheugen per gebruiker, of een vertrouwde tenant-, team- of projectsleutel voor gedeeld geheugen. Laat het model het nooit kiezen. Als je scope-strategie afhankelijk is van een eindgebruikersidentiteit, wijs dan verzoeken die er geen hebben af in plaats van terug te vallen op een gedeelde scope. De managed-memory vaardigheid helpt je bij deze installatie.

Scope scheidt geheugens, maar het geeft geen toegang tot de gegevensopslag. Een beller heeft nog steeds het READ MEMORY STORE of WRITE MEMORY STORE privilege nodig om het te openen. Zie Geheugentoegangscontrole.

Warning

Scope is de isolatiegrens tussen gebruikers, maar het is geen toegangscontrole. De app service principal kan elke scope lezen en beschermt daarom zijn credential dienovereenkomstig.

Wat de agent opslaat en ophaalt

Beheerd geheugen levert de geheugenopslag en de API's voor lezen en schrijven van invoeren. Je applicatie bepaalt wat de agent opslaat, wanneer het geheugen ophaalt en hoe het de resultaten gebruikt.

Definieer dit gedrag in de systeemprompt van de agent: geef de agent instructies over welke duurzame informatie hij moet opslaan en wanneer deze moet worden opgehaald. De managed-memory skill en templates bewaren deze systeemprompt in een constante met de naam MEMORY_INSTRUCTIONS. Scope wordt apart geconfigureerd in vertrouwde applicatiecode en wordt nooit door het model gekozen.

Stem de bewoording af op je bereikstrategie. Het volgende is een voorbeeld van de per-gebruiker strategie:

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.

Ga aan de slag met vaardigheden voor beheerd geheugen

De eenvoudigste manier om beheerd geheugen toe te voegen aan een agent is de managed-memory Claude Code-vaardigheid. De vaardigheid verwerkt alle instellingen voor u en 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.
   

Handmatig een geheugenopslag maken en gebruiken

In deze sectie wordt beschreven hoe u een geheugenarchief maakt en gebruikt zonder de managed-memory vaardigheid Claude Code.

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.

Controle van geheugentoegang

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

Voorrecht	Van toepassing op:	Description
CREATE MEMORY STORE	Bovengeschikt schema	Maak nieuwe geheugenarchieven onder een schema.
READ MEMORY STORE	Geheugenopslag	Lees de metagegevens en vermeldingen van een geheugenarchief.
WRITE MEMORY STORE	Geheugenopslag	Geheugenvermeldingen in een winkel maken, bijwerken en verwijderen.
MANAGE	Geheugenopslag	Werk het geheugenarchief zelf bij of verwijder deze. Machtigingen verlenen aan andere gebruikers.
USE SCHEMA	Bovengeschikt schema	Maak een lijst met geheugenopslag in een schema.

Kortetermijngeheugen implementeren

De API's voor geheugeninvoer bieden langetermijngeheugen als hulpprogramma's die uw agent kan gebruiken. Databricks raadt u aan uw geheugenopslag aan een gesprek te koppelen om uw agent beheerde kortetermijngeheugen in een sessie te geven. U kunt ook het volgende doen:

• Bewaar het sessiegeheugen van uw agentframework, zoals de OpenAI session=-parameter of een LangGraph-checkpointer.
• Gebruik zelfbeheerd agentgeheugen voor het gespreksgeschiedenisarchief.

Aanbevelingen voor beveiliging

Azure Databricks biedt de gecontroleerde opslag, de versleuteling, de isolatieprimitieven en het controlespoor. Als app-ontwikkelaar raadt Databricks het volgende aan:

• Gebruik de standaardinstelling per gebruiker (user_client) tenzij u een opzettelijke reden hebt om anders te partitioneren (bijvoorbeeld per project of per accountgeheugen).
• Ken alleen de minimaal vereiste machtigingen toe: alleen de service-principal van uw agent heeft WRITE MEMORY STORE nodig. Verleen READ MEMORY STORE beperkt, en vermijd brede toekenningen aan menselijke gebruikers of grote groepen.
• Beveilig de referentiegegevens van de service-principal van de app: dit is de sleutel tot het gegevensvlak van de opslag. Behandel deze net als elke hoogwaardige servicereferentie: gebruik kortdurende tokens, vermijd logboekregistratie en voeg SSRF-verdediging toe aan uw app.

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