Hantering av agentminne

Hanterat agentminne ger dina agenter långtidsminne i konversationer. Azure Databricks kör infrastrukturen och isolerar varje omfångsminne, så du behöver inte hantera lagring eller partitionering själv.

Med hanterat minne kan dina agenter:

• Kom ihåg användarinställningar, tidigare beslut och ackumulerad kontext i konversationer.
• Säkra den kunskapen med styrning i Unity Catalog.
• Dela minne mellan agenter och projekt.
• Förbättra deras noggrannhet och effektivitet över tid.

Kravspecifikation

• En Databricks-arbetsyta med Unity Catalog aktiverad.
• Behörigheten CREATE MEMORY STORE för det överordnade schemat att skapa minneslager.

Så här fungerar hanterat minne

Hanterat minne har två nivåer:

• Ett minnesarkiv är ett skyddsbart objekt i Unity Catalog som fungerar som en behållare för minnesposter. Ett minneslager ärver samma styrning, åtkomstkontroll och ursprung som andra Unity Catalog-tillgångar.
• En minnespost är ett enskilt innehåll som lagras i ett minnesarkiv. Varje post identifieras av ett omfång och en sökväg. Omfånget avgör vems minnen en post tillhör och sökvägen organiserar poster inom ett omfång, ungefär som en filsökväg (till exempel /memories/preferences.md).

Scope

Scope är hur du gör ett minne privat för en användare eller delat mellan en grupp. Din applikation sätter ett scope vid varje läs- och skrivsekvens, och en sökning returnerar endast poster med motsvarande scope. Välj den strategi som matchar vad din mäklare behöver komma ihåg:

• Privat minne för varje användare: Ställ in omfattningen till den verifierade slutanvändaridentiteten. Varje användare får sin egen partition och ser bara sina egna poster. Värdet user_client löser slutanvändarens ID åt dig.
  • Exempel: En supportagent minns en användares kommunikationspreferenser och tidigare ärenden.
• Delat minne för en grupp: Sätt omfattningen till en fast nyckel du väljer, till exempel en organisation, ett team eller ett projekt-ID. Varje användare läser och skriver samma minnen.
  • Exempel: En teamagent minns en gemensam ordlista över företagets termer och interna policyer.
• Minne uppdelat efter något annat: Bygg omfånget utifrån dina egna värden, till exempel ett klient-ID eller ett user_id:project sammansatt värde.
  • Exempel: En multi-tenant-app håller varje kunds minne separat, eller så isoleras en enskild användares minne per projekt.

En enskild agent kan kombinera strategier i ett samtal. Till exempel kan den läsa en användares privata minne och ett delat teamminne i samma begäran.

Ange omfattningen i din applikationskod utifrån en betrodd anroparkontext som begäran inte kan manipulera: den verifierade slutanvändaridentiteten från OBO-tokenen för minne per användare, eller en betrodd tenant-, team- eller projektnyckel för delat minne. Låt aldrig modellen välja det. Om din scope-strategi beror på en slutanvändaridentitet, avvisa förfrågningar som inte har en sådan istället för att falla tillbaka på ett delat scope. Färdighetenmanaged-memory guidar dig genom denna uppsättning.

Scope separerar minnen, men ger inte tillgång till butiken. Den som anropar behöver fortfarande behörigheten READ MEMORY STORE eller WRITE MEMORY STORE för att öppna den. Se Minnesåtkomstkontroll.

Vad agenten sparar och minns

Managed memory tillhandahåller minneslagringen och API:erna för läsning och skrivning av poster. Din applikation styr vad agenten sparar, när den hämtar minnet och hur den använder resultaten.

Definiera detta beteende i agentens systemprompt: instruera agenten om vilken varaktig information som ska sparas och när den ska hämtas. managed-memory-kompetensen och mallarna lagrar denna systemprompt i en konstant med namnet MEMORY_INSTRUCTIONS. Scope konfigureras separat i betrodd applikationskod och väljs aldrig av modellen.

Anpassa formuleringen till din omfattningsstrategi. Följande är ett exempel på strategin per användare:

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.

Kom igång med managed memory skills

Det enklaste sättet att lägga till hanterat minne i en agent är managed-memory Claude Code-färdigheten. Funktionen sköter hela konfigurationen åt dig och fungerar med både OpenAI Agents SDK och LangGraph.

Få kunskapen i ditt projekt på ett av två sätt:

Börja från en mall

Funktionen ingår i Databricks appmallar. Skapa en ny agent utifrån en av agentmallarna och hitta färdigheten under .claude/skills/managed-memory/.

1. Klona malllagringsplatsen:

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

2. Bläddra i app-templates, välj en agentmall som du vill börja från. Om du till exempel vill använda OpenAI Agents SDK-mallen:

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

   Note

   För "avancerade" appmallar måste du, efter distributionen, bevilja appens tjänsthuvudnamn behörigheter för Lakebase Postgres, annars returnerar sessionsinitieringen felet 502.

3. När färdigheten finns i ditt projekt beskriver du vad du vill, och din kodassistent tar hand om resten:

   Tip

   Add Databricks managed long-term memory to my agent.
   

Lägga till kunskapen i ett befintligt projekt

Om du redan har ett agentprojekt, lägg till färdigheten i projektet.

1. Skapa kompetenskatalogen om den inte finns:

   mkdir -p .claude/skills/managed-memory
   

2. Ladda ned SKILL.md-filen från managed-memory skillkatalogen och spara den i .claude/skills/managed-memory/.

3. När färdigheten finns i ditt projekt beskriver du vad du vill, och din kodassistent tar hand om resten:

   Tip

   Add Databricks managed long-term memory to my agent.
   

Skapa och använda ett minnesarkiv manuellt

Det här avsnittet visar hur du skapar och använder ett minneslager utan Claude Code-färdigheten managed-memory .

I följande exempel konfigureras hanterat minne för en kundsupportagent som lagrar en användares inställningar och hämtar dem i en senare konversation.

1. Generera en OAuth-token med Databricks CLI för att anropa API:erna:

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

2. Skapa ett minneslager för att lagra agentens minnen:

   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. Skriv en minnespost när agenten har lärt sig något om en användare. scope tilldelar posten till en enskild användare. Använd contents-fältet för den fullständiga minnestexten och description för en kort sammanfattning som förbättrar hämtningen:

   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. Sök efter minnesposter för användaren i en senare konversation för att hämta det som agenten har lärt sig:

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

För det fullständiga REST-API:et, inklusive slutpunkter, begärandefält och svarsfält, se referensen för Memory API.

Lägg till minne till en agent genom konversationer

REST-arbetsflödet ovan anropar minneslagret och posterings-API:erna direkt. När du skapar en agent på en Azure Databricks modell som betjänar slutpunkten ansluter du ett minnesarkiv till en konversation med den OpenAI-kompatibla klienten i databricks-openai SDK i stället.

En konversation är ett OpenAI-kompatibelt konversationstillstånd – den löpande historiken över meddelanden och verktygsanrop – som stöds av ett minneslager och är knutet till ett enda scope. Återanvänd samma konversation mellan förfrågningar så att agenten minns tidigare turer.

1. Bind en befintlig minneslagring och en omfattning till en ny konversation. memory_store.name är lagringsplatsens namn i tre nivåer, och scope partitionerar konversationens tillstånd, vanligtvis per slutanvändare:

   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. Skicka konversations-ID:t till responses.create. Agenten läser och skriver konversationens tillstånd i den bundna minneslagringen inom det omfånget:

   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. Återanvänd samma konversations-ID vid senare begäranden så att agenten kommer ihåg tidigare svängar. Skapa inte en ny konversation per tur:

   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)
   

Information om konversationsslutpunkter och begärandefält finns i Konversations-API:er.

Minnesåtkomstkontroll

Minneslager är skyddsbara objekt i Unity Catalog. Följande behörigheter styr åtkomsten:

Implementera kortsiktigt minne

API:erna för minnesinmatning ger långsiktigt minne som verktyg som agenten kan använda. För att ge din agent hanterat kortsiktigt minne i en session rekommenderar Databricks att du binder ditt minneslager till en konversation. Du kan även:

• Behåll agentramverkets sessionsminne, till exempel OpenAI-parametern session= eller en LangGraph-kontrollpunkt.
• Använd självhanterat agentminne för konversationshistorikarkivet.

Säkerhetsrekommendationer

Azure Databricks tillhandahåller det styrda lagret, kryptering, isoleringsmekanismer och revisionslogg. Som apputvecklare rekommenderar Databricks följande:

• Använd omfångsstandarden per användare (user_client) om du inte har en avsiktlig anledning att partitioneras på ett annat sätt (till exempel per projekt eller per kontominne).
• Bevilja minst behörighet: endast agentens tjänsthuvudnamn behöver WRITE MEMORY STORE. Bevilja READ MEMORY STORE med knapp marginal och undvik breda bidrag till mänskliga användare eller stora grupper.
• Skydda autentiseringsuppgifterna för apptjänstens huvudnamn: det är nyckeln till butikens dataplan. Behandla den som alla högvärdesautentiseringsuppgifter för tjänsten – använd kortlivade token, undvik att logga den och lägg till SSRF-skydd i din app.

Limitations

• Minnesposter ger endast långtidsminne. Skillnaden mellan kortsiktigt och långsiktigt minne finns i Kortsiktigt och långsiktigt minne.
• Minneslager och poster skapas och hanteras endast via REST API:et för Unity Catalog. det finns ingen Python SDK för dessa API:er. Om du vill använda ett minnesarkiv från en agent ansluter du det till en konversation med den OpenAI-kompatibla klienten. Se Lägg till minne i en agent med hjälp av konversationer.

Nästa steg

• Minnes-API-referens