Paměť agenta

Important

Tato funkce je v beta verzi.

Agentní paměť dává agentům dlouhodobou paměť, která přetrvává napříč konverzacemi. Azure Databricks ukládá paměť do Lakebase a spravuje za vás úložiště, indexaci a sémantické vyhledávání, takže vaši agenti si mohou pamatovat uživatelské preference, minulá rozhodnutí a nashromážděný kontext bez toho, abyste databázi provozovali.

Note

Během období Preview jsou vám účtovány poplatky za podkladovou instanci Lakebase, která ukládá vaše záznamy v paměti. Za samotnou paměť agenta nejsou účtovány žádné další poplatky. Ceny se mohou v průběhu ukázky měnit.

Používejte paměť agenta, když chcete, aby vaši agenti mohli:

  • Pamatujte na uživatelské preference, fakta a rozhodnutí v různých konverzacích.
  • Personalizujte odpovědi na základě toho, co se agent naučil v předchozích sezeních.
  • Sdílejte nahromaděné znalosti napříč agenty a projekty.
  • Zlepšení přesnosti a efektivity v průběhu času

Paměť agentů funguje s agenty postavenými na jakémkoli frameworku. Pro krátkodobou historii konverzace v rámci jedné interakce použijte relace agenta.

Požadavky

  • Nainstalujte Python 3.10 nebo novější, abyste mohli používat AgentKit SDK. AgentKit SDK je Databricks Python klient pro agentní API, který používají níže uvedené příklady. REST API můžete také volat přímo z jakéhokoliv jazyka, bez nutnosti Python.

Jak funguje agentní paměť

Hierarchie paměťových zdrojů agentů: úložiště paměti obsahuje mnoho paměťových záznamů, z nichž každý je identifikován actor_id, volitelným session_id a cestou a obsahuje obsah a popis.

Paměť agenta má dvě úrovně:

  • Paměťové úložiště je kontejner v rámci pracovního prostoru pro paměti agenta. Vytvoření obchodu automaticky zajišťuje zálohující úložiště Lakebase. Obchod adresujete pomocí jeho display_name.
  • Paměťový záznam je samostatná položka obsahu v úložišti. Každý záznam má volný text content, zkratku description používanou pro vyhledávání a sadu polí, která jej organizují a rozdělují:
    • actor_id (povinné): komu paměť patří, například koncovému uživateli nebo jinému agentovi.
    • session_id (volitelné): zaznamenává, ze které relace byla paměť zachycena, pro účely dohledatelnosti a určení původu. Nechte to nenastavené pro paměť, která není vázaná na konkrétní seanci.
    • path (vyžadováno): Cesta podobná souborovému systému, která organizuje položky uvnitř aktéra, například /preferences/response-style.md.

Prvek je jednoznačně identifikován kombinací actor_id, session_id, a path.

Záznamy se dostanou do úložiště dvěma způsoby: váš agent nebo aplikace je zapíše přímo, nebo je paměťová pipeline destiluje z konverzací v úložišti relací.

Vyhledávání

Vyvolejte paměť dvěma způsoby:

  • Položky pro herce v seznamu , volitelně filtrované podle session_id nebo prefixu path . Použijte to k prohlížení nebo zobrazení indexu toho, co agent ví.
  • Vyhledejte záznamy o herci pomocí dotazu v přirozeném jazyce. Vyhledávání vrací nejrelevantnější položky seřazené podle skóre relevance v plném textu (BM25).

Začínáme

Tyto příklady nastavují paměť agenta pro agenta podpory: vytvoří úložiště paměti, uloží uživatelovu preferenci a vyvolají ji v pozdější konverzaci. Vyberte si klienta, který odpovídá vašemu projektu. Paměťové display_name úložiště musí mít 3 až 56 znaků, začínat malým písmenem, končit písmenem nebo číslem a obsahovat pouze malá písmena, čísla a pomlčky.

AgentKit SDK

AgentKit SDK je Python klient Databricks pro agentní API, distribuovaný v balíčkudatabricks-agentbricks. Autentizuje se pomocí Databricks SDK WorkspaceClient.

  1. Nainstalujte AgentKit SDK:

    pip install databricks-agentbricks

  2. Vytvořte paměťové úložiště pro svého agenta. AgentKitClient Autentizuje se svými WorkspaceClient přihlašovacími údaji:

    from databricks.sdk import WorkspaceClient
from databricks_agentkit import AgentKitClient

client = AgentKitClient(WorkspaceClient())
memory_store = client.memory_stores.create("support-agent-memory")

  3. Uložte vzpomínku poté, co agent zjistí něco trvalého o uživateli. actor_id určuje, čí je tato paměť, path ji uspořádává v rámci daného aktéra a description zlepšuje vybavení:

    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. Vzpomínky uživatele si vybavte v pozdější konverzaci pomocí vyhledávání v přirozeném jazyce:

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

REST API

Klienti volají REST API pod adresou /api/2.0/agents/memory-stores. Volejte ji přímo v jiných jazycích než v Pythonu.

  1. Vygenerujte OAuth token pomocí Databricks CLI:

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

  2. Vytvořte paměťové úložiště pro svého agenta:

    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. Uložte uživateli paměťový záznam. actor_id určuje, čí paměť to je, path ji organizuje a description zlepšuje vybavování:

    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. Vyvolejte vzpomínky uživatele pomocí vyhledávání v přirozeném jazyce:

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

Dejte svému agentovi paměťové nástroje

Aby agent mohl rozhodnout, kdy uložit a odvolat paměť, zabalte klientské operace do nástrojů a instruujte agenta, kdy je má použít, ve svém systémovém promptu. Nastavte v důvěryhodném aplikačním kódu hodnotu actor_id z ověřené identity koncového uživatele. Nikdy nenechte model vybírat, čí paměť bude číst nebo zapisovat.

Následující příklad zahrnuje AgentKit SDK memory_store z Get Start jako nástroje pro 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"),
)

Stejný vzorec funguje i s Claude Agent SDK a dalšími frameworky: zabalit vyhledávání v úložišti a přidat operace jako typ nástroje frameworku.

Pokud také spustíte paměťovou pipeline na stejném paměťovém úložišti, pipeline může přepsat, sloučit, rozdělit nebo smazat záznamy, které agent ukládá pro jakéhokoli aktéra, kterého zpracovává.

Oddělená a zabezpečená paměť

V úložišti pomocí actor_id rozlišíte, komu které vzpomínky patří. Každý seznam i každé vyhledávání jsou omezeny na jedno actor_id, takže zvolte strategii, která odpovídá tomu, co si váš agent potřebuje pamatovat:

  • Soukromá paměť pro každého uživatele: Nastavena actor_id na ověřenou identitu koncového uživatele. Každý uživatel dostane svůj vlastní oddíl a agent si vybaví pouze záznamy tohoto uživatele.
    • Příklad: Agent podpory si pamatuje komunikační preference jednoho uživatele a jeho předchozí tikety.
  • Sdílená paměť pro skupinu: Nastavte actor_id pevný klíč, který si zvolíte, například ID týmu, projektu nebo organizace. Všichni čtou a píší stejné vzpomínky.
    • Příklad: Týmový agent si pamatuje sdílený slovník firemních termínů a interních konvencí.
  • Rozdělení paměti podle něčeho jiného: Vytvořte actor_id z vlastních hodnot, například z ID tenanta nebo user:project kompozitu.
    • Příklad: Aplikace s více tenanty nastaví actor_id na {tenant}:{user}, aby uživatelé každého zákazníka zůstali navzájem izolovaní.

Nastavte actor_id v aplikačním kódu v kontextu důvěryhodného volajícího: ověřenou identitu koncového uživatele pro paměť pro jednotlivé uživatele nebo důvěryhodný klíč týmu nebo projektu pro sdílenou paměť. Nikdy nenechte modelku to zvolit. Pokud vaše strategie závisí na identitě koncového uživatele, odmítejte požadavky, které ji neobsahují, namísto použití sdílené actor_id jako záložní možnosti.

Warning

actor_id odděluje vzpomínky, ale není to kontrola přístupu. Paměťová úložiště jsou omezena na pracovní prostor, takže jakýkoli principal, který se dostane do úložiště, může číst a zapisovat každý záznam napříč všemi aktéry. Obchod, ne herec, je bezpečnostní hranicí. Pro přísnou izolaci mezi nájemci a uživateli vytvořte samostatné paměťové úložiště pro každou hranici.

Aby jiný principál, například zástupce vašeho agenta, mohl použít úložiště, udělte mu přístup pomocí operacememory_store.grant_permission(principal_id) grant-permission (v AgentKit SDK).

Limitations

  • Paměť agenta poskytuje pouze dlouhodobou paměť. Historii krátkodobých konverzací naleznete v části relace agentů.
  • Vyhledávání je fulltextová operace (BM25) řazená podle relevance, která vrací nejvýše N výsledků, maximálně však 100 položek. Nepodporuje stránkování ani vyhledávání podle podobnosti vektorů.
  • Kontrola přístupu je vynucována na úrovni obchodu. Řízení přístupu pro jednotlivé záznamy a jednotlivé aktéry není dostupné.
  • Obchod display_name je po vytvoření neměnný. Aktualizovat lze pouze description.

Další kroky

  • Poslední aktualizace v