Ügynökmemória

Important

Ez a funkció bétaverzióban érhető el.

Az ügynökmemória hosszú távú memóriát ad az ügynököknek, amely a beszélgetések között is megmarad. Az Azure Databricks tárolja a memóriát a Lakebase-ben, és kezeli a tárolást, indexelést és keresést, így az ügynökök megjegyezhetik a felhasználói preferenciákat, korábbi döntéseket és felhalmozódott kontextust anélkül, hogy adatbázist kellene üzemeltetnie.

Note

Az előnézeti időszak alatt díjat számítunk fel a memóriabejegyzéseket tároló alapul szolgáló Lakebase-példány után. Magára az ügynök memóriájára nem számítunk fel további díjat. Az árak változhatnak az előzetes előzmény előrehaladtával.

Használd az ügynök memóriáját, amikor azt szeretnéd, hogy az ügynökök a következőket csinálják:

  • Emlékezz a felhasználói preferenciákra, tényekre és döntésekre külön beszélgetések során.
  • Szabd személyre a válaszokat az alapján, amit az ügynök a korábbi munkamenetekben megtanult.
  • Oszd meg a felhalmozott tudást ügynökök és projektek között.
  • Javítani kell a pontosságot és a hatékonyságot az idő függvényében.

Az ügynökmemória bármely keretrendszerre épülő ügynökökkel működik. Rövid távú beszélgetési előzményekhez egyetlen interakción belül használd a agentmunkameneteket.

Requirements

  • Telepítsd a Python 3.10-et vagy annál magasabb, hogy használd az AgentKit SDK-t. Az AgentKit SDK a Databricks Python-kliense az ügynök-API-khoz, amelyet az alábbi példák használnak. A REST API-t bármelyik nyelvről közvetlenül hívhatod, Python nélkül.
  • A memory_store.put() vagy memory_store.list(path=...) használatához telepítsd a databricks-agentbricks 0.6.0-s vagy újabb verzióját.

Hogyan működik az ügynökmemória

Ügynökmemória-erőforráshierarchia: egy memóriatároló sok memóriabejegyzést tartalmaz, amelyek mindegyikét actor_id, opcionális session_id és útvonal azonosítja, és tartalmat valamint leírást tartalmaznak.

Az ügynök memóriájának két szintje van:

  • A memóriatároló az ügynök memóriáinak munkaterületi konténerje. A tároló létrehozása automatikusan biztosítja a háttér Lakebase tárolót. Az üzletet a boltazonosítója alapján címezed, amit az üzlet létrehozásakor választasz ki.
  • A memóriabejegyzés egy önálló tartalmi elem egy tárolóban. Minden bejegyzésnek van egy szabad formátumú szövege content, egy rövidítése description a lekéréshez, valamint egy mezőhalmaz, amely rendszerezi és partizálja azt:
    • actor_id (kötelező): kié az emlék, például végfelhasználónak vagy más ügynöknek.
    • session_id (nem kötelező): az a munkamenet, amelyhez a memória tartozik. Hagyd beállítatlanul, hogy a memória érvényes a szereplő munkamenetei között.
    • path (szükséges): egy fájlrendszer-szerű út, amely egy aktoron belüli bejegyzéseket szervezi, például /preferences/response-style.md.

Egy bejegyzés egyedileg azonosítható a(z) actor_id, session_id és path kombinációja alapján. Ugyanaz az út két különböző munkamenetben, vagy egy munkamenetben és anélkül, két külön bejegyzésként szerepel.

A bejegyzések kétféleképpen jutnak be egy tárolóba: az ügynököd vagy az alkalmazás közvetlenül írja őket, vagy egy memóriacsatorna a session store-ban lévő beszélgetésekből nyeri ki őket.

Visszakeresés

Kétféleképpen szerezzük meg a memóriát:

  • Lista egy művelethez tartozó bejegyzésekről, opcionálisan a következők szerint szűrve: session_id, path előtag vagy pontos path. Ezt használhatod arra, hogy böngészd vagy megjelenítsd az ügynök által tud információk indexét.
  • Keress bejegyzéseket egy természetes nyelvű lekérdezéssel rendelkező aktorról. A keresés a relevancia pontszám szerint rangsorolt legrelevánsabb bejegyzéseket adja vissza.

Bármelyik műveletnél egy session_id szűrő csak az adott munkamenethez mentett bejegyzéseket adja vissza. Nem adja vissza a munkamenet nélkül mentett bejegyzéseket.

Első lépések

Az AgentKit SDK és a REST API példák beállítják az ügyfélszolgálati ügynök memóriáját: létrehoznak egy memóriatárolót, elmentik a felhasználó preferenciáját, és felidézik azt egy későbbi beszélgetésben. Az Agent Bricks CLI példája egy memóriatárolót köt egy olyan ügynökhöz, amelyet a CLI-vel építesz és telepítesz. Válaszd ki azt az ügyfelet, amely illik a projektedhez. A memóriatároló azonosítónak 3-56 karakterből kell állnia, kisbetűvel kell kezdődnie, betűvel vagy számmal kell végződnie, és csak kisbetűket, számokat és kötőjeleket tartalmazhat.

AgentKit SDK

A AgentKit SDK a Databricks Python-kliense az ügynök-API-khoz, amelyet a databricks-agentbricks csomagban terjesztenek. A Databricks SDK-kkal WorkspaceClientautentikál.

  1. Telepítse az AgentKit SDK-t:

    pip install databricks-agentbricks

  2. Hozz létre egy memóriatárolót az ügynöködnek. AgentKitClient az Ön WorkspaceClient bejelentkezési adataival hitelesíti magát:

    from databricks.sdk import WorkspaceClient
from databricks_agentkit import AgentKitClient

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

  3. Ments meg egy emléket, miután az ügynök megtud valami tartós információt a felhasználóról. actor_id kié ez az emlék, path rendszerezi azt azon az aktoron belül, és description javítja a visszakeresést:

    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() akkor bukik el, ALREADY_EXISTS ha már létezik bejegyzés azon az elérési úton. A bejegyzés létrehozásához vagy a meglévő frissítéséhez ugyanazokkal az argumentumokkal hívja meg a(z) memory_store.put() elemet.

  4. Emlékezzünk fel a felhasználó emlékeire egy későbbi beszélgetésben egy természetes nyelvi kereséssel:

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

REST API

A kliensek a /api/2.0/agents/memory-stores alatt hívják meg a REST API-t. Hívd közvetlenül más nyelvekre is, mint a Python.

  1. Generálj egy OAuth tokent a Databricks CLI-val:

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

  2. Hozz létre memóriatárt az ügynöködnek:

    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. Ments el egy memóriabejegyzést egy felhasználó számára. actor_id az, hogy kié ez az emlék, path rendszerezi, és description hatékonyabbá teszi a visszakeresést:

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

    Ha már létezik bejegyzés ezen az úton, a kérés ALREADY_EXISTS(HTTP 409) hibával meghiúsul. A meglévő bejegyzés frissítéséhez inkább keresd meg az útvonala alapján. A keresés minden munkamenethez visszaadja az útvonal bejegyzéseit, ezért válaszd azt, amelynek a(z) session_id értéke egyezik. A(z) name utolsó szegmense a bejegyzésazonosító:

    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"

    Ezután frissítse a bejegyzés tartalmát azonosítója alapján:

    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. Idézze fel a felhasználó emlékeit egy természetes nyelvi kereséssel:

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

Bricks Ügynök

Ha az ügynököt a Agent Bricks CLI segítségével építed, a agentbricks init egy memóriatárolót deklarál a agent.toml-ban. agentbricks deploy létrehozza a tárolóhelyet, ha még nem létezik, és hozzáférést ad a telepített ügynöknek hozzá.

Válasszon egy útvonalat:

  • Indítás üresen (a legtöbb ügynens): Telepítsd az ügynenst. agentbricks deploy létrehozza a memóriatárolót, amelyet agentbricks init deklarált. A(z) my-agent nevű ügynök telepítéséhez a következőket kell futtatni:

    agentbricks deploy my-agent

  • Kezdj a tárban már meglévő memóriákkal: Először hozd létre a tárat, adj hozzá bejegyzéseket, majd rendeld a tárat az ügynökhöz, és telepítsd.

    1. Egy my-agent-memory nevű áruház létrehozásához futtassuk a következőket. A kimenet tartalmazza az áruházazonosítót, egy generált azonosítót, amely különálló az áruház nevétől:

      agentbricks memory stores create --name my-agent-memory

    2. Bejegyzés hozzáadásához futtassa a következőket, <store-id> helyettesítve az előző lépés store ID-jével:

      agentbricks memory entries create --store <store-id> --actor-id you@example.com \
  --path /preferences/style.md --content "Prefers Python and concise answers with code examples."

    3. A tároló társításához és az ügynök telepítéséhez futtassa a következőt. agentbricks memory bind lecseréli az üzlet nevét a(z) agent.toml elemben, és a(z) agentbricks deploy megkeresi a meglévő üzletet név alapján, és azt használja új létrehozása helyett:

      agentbricks memory bind my-agent-memory
agentbricks deploy my-agent

--path a bejegyzés kulcsa a tárolón belül, nem egy fájl a gépeden. --actor-id az a felhasználó, akihez a memória tartozik. A telepített ügynök a bejelentkezett felhasználó e-mail-címét használja aktorazonosítóként, így minden bejegyzést a felhasználó e-mail-címével tölts fel, aki az ügynökkel beszél.

Az Agent Bricks CLI-ben memory bind és agentbricks deploy egy üzletre a neve alapján hivatkozik. A parancsok, amelyek egyetlen tárolóra hatnak, például memory entries create, a generált tárolóazonosítót veszik igénybe.

Adj ügynöködnek memóriaeszközöket

Ahhoz, hogy egy ügynök el tudja dönteni, mikor mentse el és mikor hívja elő a memóriát, csomagold a kliensműveleteket eszközökké, és a rendszerutasításban add meg az ügynöknek, mikor használja őket. Állítsa be a actor_id elemet a megbízható alkalmazáskódban a hitelesített végfelhasználói személyazonosság alapján. Soha ne hagyd, hogy a modell válassza el, kinek az emlékét olvassa vagy kiírja.

A következő példa az AgentKit SDK-t memory_store a Get started menüből az OpenAI Agents SDK eszközeiként csomagolja.

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() létrehozza a bejegyzést, vagy helyettesíti a már azon az elérési úton lévő bejegyzés tartalmát. Ha új sorként add hozzá a tartalmat, add meg a(z) append=True-t. put() nem atomikus, így az egyidejű írások ugyanarra az útvonalra írhatják felül egymást. list(path=...) minden munkamenetben visszaadja a bejegyzéseket pontosan ezen a pontos elérési úton, így forget_memory törli az összes olyan bejegyzést is, amelyet egy munkameneten belül ezen az elérési úton mentettek.

Ugyanez a minta működik a Claude Agent SDK-val és más keretrendszerekkel is: a tároló keresési, put, listázási és törlési műveleteit csomagoljuk be a keretrendszer eszköztípusaként.

Ha ugyanazon a memória tárolón is futtatsz memóriafolyamatot, a folyamat újraírhatja, összevonhatja, szétoszthatja vagy törölheti azokat a bejegyzéseket, amelyeket az ügynök bármely aktorhoz ment, amelyet feldolgoz.

Partíció és biztonságos memória

Egy tárolón belül a actor_id segít elkülöníteni, hogy mely emlékek kihez tartoznak. Minden lista és keresés egyetlen actor_idegységre van beosztva, ezért válaszd ki azt a stratégiát, amely megfelel annak, amit az ügynöködnek meg kell észbenhagynia:

  • Magánmemória minden felhasználó számára: Állítsuk actor_id be a hitelesített végfelhasználói azonosítóra. Minden felhasználó saját partíciót kap, és az ügynök csak az adott felhasználó bejegyzéseit hívja vissza.
    • Példa: Egy ügyfélszolgálati ügynök megjegyzi az egyik felhasználó kommunikációs beállításait és a korábbi jegyeket.
  • Megosztott memória egy csoport számára: Állíts actor_id be egy fix kulcsot, amit te választasz, például egy csapat, projekt vagy szervezeti azonosító. Mindenki ugyanazokat az emlékeket olvassa és írja.
    • Példa: Egy csapatügynök megjegyzi a közös szószótárt a vállalati kifejezésekről és a belső konvenciókról.
  • A memória felosztása egyéb szempont szerint: Hozz létre actor_id a saját értékeidből, például egy bérlőazonosítóból vagy egy user:project összetett azonosítóból.
    • Példa: Egy több-bérlős alkalmazás úgy állítja be a(z) actor_id értékét {tenant}:{user} értékre, hogy az egyes ügyfelek felhasználói el legyenek különítve egymástól.

Állítsa be a actor_id értékét az alkalmazáskódban megbízható hívói kontextusból: felhasználónkénti memóriához az ellenőrzött végfelhasználói identitást, illetve megosztott memóriához egy megbízható csapat- vagy projektkulcsot. Sose hagyd, hogy a modell válassza ki. Ha a stratégiád a végfelhasználói identitáson alapul, utasítsd el azokat a kéréseket, amelyek nem tartalmaznak ilyen, inkább visszatérj egy megosztott actor_ididentitáshoz.

Warning

actor_id elválasztja a memóriát, de nem jelent hozzáférés-szabályozást. A memóriatárolók munkaterülethez kötöttek, így bármely jogalany, amely elér egy tárolót, minden bejegyzést olvasni és írni tud az összes aktorban. A bolt, nem a színész, a biztonsági határ. A bérlők vagy felhasználók közötti szigorú elkülönítéshez hozz létre külön memóriatárolót minden határonként.

Ahhoz, hogy egy másik megbízó, például az ügynököd szolgáltatási főnöke használja, adj hozzá hozzáférést a bolt engedélyezési műveletével (memory_store.grant_permission(principal_id) az AgentKit SDK-ban). Csak az áruház alkotója vagy egy munkaterület adminisztrátora adthat hozzáférést.

Limitations

  • Az ügynökmemória csak hosszú távú memóriát biztosít. A rövid távú beszélgetési előzményekért lásd: ügynök-munkamenetek.
  • A keresés relevancia szerint rangsorolja a bejegyzéseket, kombinálva a teljes szöveges (BM25) és a szemantikai egyezést minden bejegyzés tartalma és leírása alapján. Akár 100 bejegyzést is visszaad, és nem támogatja az oldalozást.
  • A hozzáférés-ellenőrzést az üzlet szintjén érvényesítik. A bejegyzésenkénti és felhasználónkénti hozzáférés-ellenőrzés nem érhető el.
  • Az áruház hozzáférés-ellenőrzése az üzlet bejárataira vonatkozik. Bármely munkaterületi felhasználó felsorolhatja és lekérheti a memóriatárolókat, beleértve azok azonosítóit és leírásait.
  • Nem lehet megváltoztatni egy bolt azonosítóját, miután létrehoztad. Csak description frissíthető.

Következő lépések

  • Utolsó frissítés időpontja: