Agentgeheugen

Agentgeheugen geeft je agenten een langetermijngeheugen dat tussen gesprekken blijft bestaan. Azure Databricks slaat het geheugen op in Lakebase en beheert de opslag, indexering en zoekopdracht voor je, zodat je agenten gebruikersvoorkeuren, eerdere beslissingen en opgebouwde context kunnen onthouden zonder dat jij een database hoeft te beheren.

Gebruik agentgeheugen wanneer je wilt dat je agenten het volgende doen:

• Onthoud gebruikersvoorkeuren, feiten en beslissingen over afzonderlijke gesprekken.
• Personaliseer de antwoorden op basis van wat een agent in eerdere sessies heeft geleerd.
• Deel opgebouwde kennis tussen agenten en projecten.
• Verbeter de nauwkeurigheid en efficiëntie in de loop van de tijd.

Agentgeheugen werkt met agenten die op elk framework zijn gebouwd. Gebruik agent-sessies voor kortetermijngespreksgeschiedenis binnen één interactie.

Requirements

• Installeer Python 3.10 of hoger, om de AgentKit SDK te gebruiken. AgentKit SDK is de Databricks Python-client voor agent-API's die in de onderstaande voorbeelden worden gebruikt. Je kunt de REST API ook direct aanroepen vanuit elke taal, zonder Python-vereiste.
• Om memory_store.put() of memory_store.list(path=...) te gebruiken, installeer databricks-agentbricks 0.6.0 of hoger.

Hoe agentgeheugen werkt

Het geheugen van de agent kent twee niveaus:

• Een memory store is de container binnen een werkruimte voor de herinneringen van een agent. Door een store te maken, wordt de onderliggende Lakebase-opslag automatisch ingericht. Je verwijst naar een winkel met zijn winkel-ID, die je kiest wanneer je de winkel aanmaakt.
• Een geheugenvermelding is een individueel stuk inhoud in een winkel. Elke vermelding bevat een vrije tekst content, een korte description tekst die wordt gebruikt voor het ophalen, en een set velden die het organiseren en partitioneren:
  • actor_id (vereist): aan wie het geheugen toebehoort, zoals een eindgebruiker of een andere agent.
  • session_id (optioneel): de sessie waartoe het geheugen behoort. Laat dit leeg voor geheugen dat geldt voor de sessies van de acteur.
  • path (vereist): een bestandssysteem-achtig pad dat elementen binnen een actor organiseert, zoals /preferences/response-style.md.

Een entry wordt uniek geïdentificeerd door de combinatie van actor_id, session_id, en path. Hetzelfde pad onder twee verschillende sessies, of onder een sessie en zonder, bevat twee aparte vermeldingen.

Entries komen op twee manieren in een store terecht: je agent of applicatie schrijft ze direct, of een memory pipeline distilleert ze uit de gesprekken in een session store.

Ophalen

Haal geheugen op twee manieren op:

• Lijstvermeldingen voor een actor, optioneel gefilterd op session_id, een path prefix of een exact path. Gebruik dit om te bladeren of een index te renderen van wat een makelaar weet.
• Zoek naar items voor een actor met een zoekopdracht in natuurlijke taal. Zoeken geeft de meest relevante vermeldingen terug, gerangschikt op relevantiescore.

Een session_id filter op een van beide operaties geeft alleen de vermeldingen terug die met die sessie zijn opgeslagen. Het retourneert geen items die zonder sessie zijn opgeslagen.

Get started

Deze voorbeelden stellen agentgeheugen in voor een supportagent: ze creëren een geheugenopslag, slaan de voorkeur van een gebruiker op en roepen deze op in een later gesprek. Kies de klant die bij jouw project past. Een geheugenopslag-ID moet 3 tot 56 tekens zijn, beginnen met een kleine letter, eindigen met een letter of cijfer, en alleen kleine letters, cijfers en koppeltekens bevatten.

AgentKit SDK

De AgentKit SDK is de Databricks Python-client voor agent-API's, verspreid in het databricks-agentbricks pakket. Het authenticeert met de SDK van Databricks WorkspaceClient.

1. Installeer de AgentKit SDK:

   pip install databricks-agentbricks
   

2. Maak een geheugenopslag aan voor je agent. AgentKitClient Authenticeert met uw WorkspaceClient gegevens:

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

3. Sla een geheugen op nadat de agent iets duurzaams over een gebruiker heeft geleerd. actor_id is wiens geheugen dit is, path organiseert het binnen die actor, en description verbetert het ophalen:

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

   add() mislukt met fout ALREADY_EXISTS als er al een invoer op dat pad bestaat. Om de entry te maken of de bestaande bij te werken, roep je memory_store.put() met dezelfde argumenten aan.

4. Herinner de herinneringen van de gebruiker in een later gesprek met een zoekopdracht in natuurlijke taal:

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

REST API

De clients roepen de REST API aan onder /api/2.0/agents/memory-stores. Roep het rechtstreeks aan in andere talen dan Python.

1. Genereer een OAuth-token met de Databricks CLI:

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

2. Maak een geheugenopslag aan voor je agent:

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

3. Sla een geheugenvermelding op voor een gebruiker. actor_id is wiens geheugen dit is, path organiseert het en description verbetert het ophalen:

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

   Als er al een entry op dat pad bestaat, faalt het verzoek met ALREADY_EXISTS (HTTP 409). Om de bestaande vermelding bij te werken, zoek deze in plaats daarvan via het pad op. De zoekopdracht geeft de padvermeldingen voor elke sessie terug, dus kies degene waarvan de session_id overeenkomt. Het laatste segment van het name pad is de invoer-ID:

   curl -G "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
     --data-urlencode "actor_id=user-123" --data-urlencode "path=/preferences/communication.md"
   

   Werk vervolgens de inhoud van de vermelding bij aan de hand van de ID:

   curl -X PATCH "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries/<entry-id>?update_mask=content" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
     -d '{"content": "Prefers email over phone. Timezone: PST."}'
   

4. Roep de herinneringen van de gebruiker op met een zoekopdracht in natuurlijke taal:

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

Geef je agent geheugentools

Om een agent te laten bepalen wanneer geheugen wordt opgeslagen en teruggeroepen, wrappen de clientoperaties als tools en instrueren de agent wanneer ze gebruikt moeten worden in zijn systeemprompt. Stel de actor_id in in code van een vertrouwde applicatie op basis van de geverifieerde identiteit van de eindgebruiker. Laat het model nooit kiezen wiens geheugen het leest of schrijft.

Het volgende voorbeeld omvat de AgentKit SDK memory_store van Get Started als tools voor de 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, replacing any memory at the same path."""
        memory_store.put(actor_id=actor_id, path=path, content=content, description=description or None)
        return f"Saved memory at {path}"

    @function_tool
    def list_memories() -> str:
        """List the paths and descriptions of the user's long-term memories."""
        memories = memory_store.list(actor_id=actor_id)
        return "\n".join(f"{m.path}: {m.description}" if m.description else m.path for m in memories) or "No memory found."

    @function_tool
    def forget_memory(path: str) -> str:
        """Delete the long-term memory at a path, such as when the user asks you to forget it."""
        memories = list(memory_store.list(actor_id=actor_id, path=path))
        for memory in memories:
            memory.delete()
        return f"Forgot memory at {path}" if memories else f"No memory at {path}"

    return [search_memory, save_memory, list_memories, forget_memory]

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

put() maakt de entry aan, of vervangt de inhoud van de entry die al op dat pad staat. Om de inhoud in plaats daarvan als nieuwe regels toe te voegen, geef dan append=True mee. put() is niet atomair, dus gelijktijdige schrijfacties naar hetzelfde pad kunnen elkaar overschrijven. list(path=...) geeft de vermeldingen op dat exacte pad in elke sessie terug, waardoor forget_memory ook elke vermelding die op het pad onder een sessie is opgeslagen, wordt verwijderd.

Hetzelfde patroon werkt met de Claude Agent SDK en andere frameworks: verpak de zoek-, put-, list- en verwijderbewerkingen van de store als het tooltype van het framework.

Als je ook een memory pipeline draait op dezelfde memory store, kan de pijplijn de entries die je agent opslaat voor elke actor die hij verwerkt herschrijven, samenvoegen, splitsen of verwijderen.

Partitie en veilig geheugen

In een winkel kun je met actor_id onderscheid maken tussen van wie welke herinneringen zijn. Elke lijst en zoekopdracht is beperkt tot één enkel actor_id, dus kies de strategie die aansluit bij wat je makelaar moet onthouden:

• Persoonlijk geheugen voor elke gebruiker: Stel actor_id in op de geverifieerde identiteit van de eindgebruiker. Elke gebruiker krijgt zijn eigen partitie, en de agent roept alleen de invoer van die gebruiker op.
  • Voorbeeld: Een supportmedewerker onthoudt de communicatievoorkeuren en eerdere tickets van één gebruiker.
• Gedeeld geheugen voor een groep: Stel actor_id in op een vaste sleutelwaarde die je kiest, bijvoorbeeld een team-, project- of organisatie-ID. Iedereen leest en schrijft dezelfde herinneringen.
  • Voorbeeld: Een teamagent onthoudt een gedeeld woordenlijstje met bedrijfstermen en interne conventies.
• Geheugen opgedeeld op basis van iets anders: Maak actor_id op basis van je eigen waarden, zoals een tenant-ID of een user:project samengestelde waarde.
  • Voorbeeld: Een multi-tenant app stelt zo in actor_id dat {tenant}:{user} de gebruikers van elke klant van elkaar geïsoleerd blijven.

Stel actor_id in je applicatiecode in vanuit de context van de vertrouwde caller: de geverifieerde eindgebruikersidentiteit voor per-gebruiker geheugen, of een vertrouwde team- of projectsleutel voor gedeeld geheugen. Laat het model het nooit kiezen. Als je strategie afhankelijk is van een eindgebruikersidentiteit, wijs dan verzoeken af die er geen bevatten, in plaats van terug te vallen op een gedeelde actor_id.

Om een andere principal, zoals de serviceprincipal van uw agent, een store te laten gebruiken, verleen deze toegang via de grant-permission-operatie van de store (memory_store.grant_permission(principal_id) in de AgentKit SDK). Alleen de maker van de store of een workspace-beheerder kan toegang verlenen.

Limitations

• Agentgeheugen biedt alleen langetermijngeheugen. Zie voor gespreksgeschiedenis op korte termijn agentensessies.
• De zoekfunctie rangschikt vermeldingen op relevantie, waarbij volledige tekst (BM25) en semantische matching worden toegepast op de inhoud en beschrijving van elke post. Het geeft tot 100 items terug en ondersteunt geen paginering.
• Toegangscontrole wordt op winkelniveau gehandhaafd. Toegangscontrole per item en per actor is niet beschikbaar.
• Winkeltoegangscontrole geldt voor de ingangen van een winkel. Elke werkruimtegebruiker kan memory stores weergeven en ophalen, inclusief hun ID's en beschrijvingen.
• Je kunt de ID van een winkel niet veranderen nadat je deze hebt aangemaakt. Alleen description kan worden bijgewerkt.

Volgende stappen 

• Agentsessies
• Pijplijnen voor agentgeheugen
• Agent API-referentie