Hantering av agentminne

Managed agent-minne ger dina agenter ett hållbart, långtidsminne som består över samtal. Azure Databricks lagrar minnet i Lakebase och hanterar lagring, indexering och semantisk sökning åt dig, så att dina agenter kan komma ihåg användarpreferenser, tidigare beslut och ackumulerad kontext utan att du behöver driva en databas.

Använd hanterat minne när du vill att dina agenter ska:

• Kom ihåg användarens preferenser, fakta och beslut över separata samtal.
• Anpassa svaren baserat på vad en agent lärt sig i tidigare sessioner.
• Dela med dig av samlad kunskap mellan agenter och projekt.
• Förbättra noggrannheten och effektiviteten över tid.

Managed memory fungerar med agenter byggda på vilket ramverk som helst. För kortvarig konversationshistorik inom en enda interaktion, använd hanterade agentsessioner.

Kravspecifikation

• Installera Python 3.10 eller högre för att använda AgentKit SDK. AgentKit SDK är Databricks Python-klient för agent-API:er som exemplen nedan använder. Du kan också anropa REST API:et direkt från vilket språk som helst, utan att behöva Python.

Så här fungerar hanterat minne

Hanterat minne har två nivåer:

• En minneslagring är den arbetsytespecifika behållaren för en agents minnen. När du skapar ett lagringsutrymme etableras den underliggande Lakebase-lagringen automatiskt. Du adresserar en butik med dess display_name.
• En minnespost är en enskild innehållsenhet i en lagring. Varje post har en friformstext content, en kort text description som används för sökning och en uppsättning fält som organiserar och delar in den:
  • actor_id (Krävs): Vem minnet tillhör, såsom en slutanvändare eller en annan agent.
  • session_id (valfritt): Registrerar vilken session minnet fångades från, för spårning och proveniens. Lämna den oinställd för minne som inte är knutet till en specifik session.
  • path (krävs): en filsystemliknande sökväg som organiserar poster inom en aktör, såsom /preferences/response-style.md.

En post identifieras entydigt med kombinationen av actor_id, session_id, och path.

Hämtning

Hämta minne på två sätt:

• Lista poster för en aktör, med valfri filtrering på session_id eller ett path-prefix. Använd detta för att bläddra bland eller rendera ett index över vad en agent vet.
• Sök efter en aktör med en naturlig språkfråga. Sökningen ger de mest relevanta posterna rankade efter ett fulltextpoäng (BM25).

Get started

Dessa exempel sätter upp hanterat minne för en supportagent: de skapar ett minneslager, sparar en användares preferens och återkallar det i en senare konversation. Välj den kund som passar ditt projekt. En minneslagring display_name måste vara 3 till 56 tecken, börja med en liten bokstav, sluta med en bokstav eller siffra, och endast innehålla gemener, siffror och bindestreck.

AgentKit SDK

AgentKit SDK är Databricks Python-klient för agent-API:er, distribuerad i paketetdatabricks-agentbricks. Den autentiserar sig med Databricks SDK:s WorkspaceClient.

1. Installera AgentKit SDK:n:

   pip install databricks-agentbricks
   

2. Skapa en minneslagring för din agent. AgentKitClient autentiserar med dina WorkspaceClient meriter:

   from databricks.sdk import WorkspaceClient
   from databricks_agentkit import AgentKitClient
   
   client = AgentKitClient(WorkspaceClient())
   memory_store = client.memory_stores.create("support-agent-memory")
   

3. Spara ett minne efter att agenten fått veta något bestående om en användare. actor_id anger vems minne det är, path organiserar det hos den aktören och description förbättrar hämtningen:

   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",
   )
   

4. Återkalla användarens minnen i en senare konversation med en naturlig språksökning:

   results = memory_store.search(actor_id="user-123", query="communication preferences", limit=10)
   

REST API

Klienterna anropar REST-API:et under /api/2.0/agents/memory-stores. Anropa det direkt i språk andra än Python.

1. Generera en OAuth-token med Databricks CLI:

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

2. Skapa ett minnesminne för din agent:

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

3. Spara en minnespost för en användare. actor_id visar vems minne det är, path organiserar det och description förbättrar hämtningen:

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

4. Återkalla användarens minnen med en naturlig språksökning:

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

Ge din agent minnesverktyg

För att låta en agent bestämma när minne ska sparas och hämtas, kapsla in klientoperationerna som verktyg och instruera agenten om när de ska användas i dess systemprompt. Ställ in actor_id i betrodd applikationskod utifrån den verifierade slutanvändaridentiteten. Låt aldrig modellen välja vems minne den ska läsa från eller skriva till.

Följande exempel paketerar in AgentKit SDK memory_store från Get started som verktyg för 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"),
)

Samma mönster fungerar med Claude Agent SDK och andra ramverk: omslut butikens sök- och tilläggsoperationer som ramverkets verktygstyp.

Partition och säkert minne

I en butik är actor_id det som skiljer olika personers minnen åt. Varje lista och sökning är begränsad till en enda actor_id, så välj den strategi som stämmer överens med vad din mäklare behöver komma ihåg:

• Privat minne för varje användare: Ställ actor_id in på den verifierade slutanvändaridentiteten. Varje användare får sin egen partition, och agenten minns bara den användarens poster.
  • Exempel: En supportagent minns en användares kommunikationspreferenser och tidigare ärenden.
• Delat minne för en grupp: Sätt actor_id till en fast nyckel du väljer, såsom ett team-, projekt- eller organisations-ID. Alla läser och skriver samma minnen.
  • Exempel: En teamagent minns en gemensam ordlista med företagstermer och interna konventioner.
• Minnet delas upp utifrån något annat: Bygg actor_id utifrån dina egna värden, till exempel ett tenant-ID eller en user:project-kombination.
  • Exempel: En app med flera klienter ställer in actor_id till {tenant}:{user} så att varje kunds användare hålls åtskilda från varandra.

Ange actor_id i din applikationskod utifrån en betrodd anroparkontext: den verifierade identiteten för slutanvändaren för minne per användare, eller en betrodd team- eller projektnyckel för delat minne. Låt aldrig modellen välja det. Om din strategi bygger på en slutanvändaridentitet, avvisa förfrågningar som inte har en sådan istället för att falla tillbaka på en delad actor_id.

För att låta en annan huvudperson, som din agents tjänstehuvudansvariga, använda en butik, ge den tillgång med butikens grant-permission-operation (memory_store.grant_permission(principal_id) i AgentKit SDK).

Limitations

• Managed memory ger endast långtidsminne. För kortsiktig samtalshistorik, se hanterade agentsessioner.
• Sökning är en relevansrankad, fulltextoperation (BM25) som returnerar en topp-N-resultatuppsättning med upp till 100 poster. Den stöder inte paginering eller vektorliknande sökning.
• Åtkomstkontroll tillämpas på butiksnivå. Åtkomstkontroll per ingång och per aktör är inte tillgängliga.
• Butiken display_name är oföränderlig efter skapandet. Endast description kan uppdateras.

Nästa steg

• Hanterade agentsessioner
• Agent API-referens