Pamięć agenta

Ważna

Ta funkcja jest dostępna w wersji beta.

Pamięć agenta daje agentowi pamięć długoterminową, która utrzymuje się między rozmowami. Azure Databricks przechowuje pamięć w Lakebase i zarządza przechowywaniem, indeksowaniem oraz wyszukiwaniem za Ciebie, dzięki czemu Twoi agenci mogą pamiętać preferencje użytkownika, wcześniejsze decyzje i zgromadzony kontekst bez konieczności korzystania z bazy danych.

Note

W okresie wersji zapoznawczej są naliczane opłaty za bazową instancję Lakebase, która przechowuje Twoje wpisy w pamięci. Nie nalicza się dodatkowych opłat za samą pamięć agenta. Ceny mogą ulec zmianie w miarę postępu zapowiedzi.

Używaj pamięci agenta, gdy chcesz, aby twoi agenci:

  • Pamiętaj o preferencjach użytkowników, faktach i decyzjach w różnych rozmowach.
  • Personalizuj odpowiedzi na podstawie tego, czego agent nauczył się podczas wcześniejszych sesji.
  • Dziel się zgromadzoną wiedzą między agentami i projektami.
  • Zwiększaj dokładność i wydajność z czasem.

Pamięć agenta działa z agentami opartymi na dowolnym frameworku. Aby zachować krótkotrwałą historię rozmów w ramach jednej interakcji, użyj sesji agenta.

Requirements

  • Zainstaluj Python 3.10 lub nowszy, aby korzystać z SDK AgentKit. AgentKit SDK to klient Databricks Python dla API agentów, którego używają poniższe przykłady. Możesz też wywołać REST API bezpośrednio z dowolnego języka, bez konieczności używania Python.
  • Aby użyć memory_store.put() lub memory_store.list(path=...), zainstaluj databricks-agentbricks wersję 0.6.0 i wyższą.

Jak działa pamięć agenta

Hierarchia zasobów pamięci agenta: magazyn pamięci zawiera wiele wpisów pamięci, z których każdy jest identyfikowany przez actor_id, opcjonalny session_id i ścieżkę oraz zawiera treść i opis.

Pamięć agenta ma dwa poziomy:

  • Magazyn pamięci to kontener w obrębie obszaru roboczego na wspomnienia agenta. Tworzenie sklepu automatycznie zapewnia pamięć Lakebase wspierającą. Do sklepu odwołujesz się za pomocą jego identyfikatora sklepu, który wybierasz podczas tworzenia sklepu.
  • Wpis pamięci to pojedynczy element w magazynie danych. Każdy wpis zawiera tekst contentw formie swobodnej , skrót description używany do wyszukiwania oraz zestaw pól organizujących i dzielących go:
    • actor_id (wymagane): do kogo należy pamięć, na przykład do użytkownika końcowego lub innego agenta.
    • session_id (opcjonalnie): sesja, do której należy pamięć. Zostaw to nieustawione dla pamięci obowiązującej we wszystkich sesjach aktora.
    • path (wymagane): ścieżka podobna do ścieżki systemu plików, która organizuje elementy wewnątrz aktora, na przykład /preferences/response-style.md.

Element jest jednoznacznie identyfikowany przez kombinację actor_id, session_id, oraz path. Ta sama ścieżka w dwóch różnych sesjach lub w ramach sesji i poza nią zawiera dwa oddzielne wpisy.

Wpisy trafiają do repozytorium na dwa sposoby: agent lub aplikacja zapisuje je bezpośrednio albo potok pamięci wyodrębnia je z rozmów w repozytorium sesji.

Odzyskiwanie

Przywołaj pamięć na dwa sposoby:

  • Wyświetl wpisy dla danego aktora, opcjonalnie filtrowane według session_id, prefiksu path lub dokładnego path. Użyj tego do przeglądania lub renderowania indeksu tego, co agent wie.
  • Wyszukaj wpisy dotyczące aktora za pomocą zapytania w języku naturalnym. Wyszukiwanie zwraca najbardziej trafne wpisy uporządkowane według oceny trafności.

Filtr session_id w dowolnej z operacji zwraca tylko wpisy zapisane w tej sesji. Nie zwraca zapisów zapisanych bez sesji.

Wprowadzenie

Przykłady AgentKit SDK i REST API konfigurują pamięć agenta dla agenta wsparcia: tworzą oni magazyn pamięci, zapisują preferencje użytkownika i przywołują je w późniejszej rozmowie. Przykład CLI Agent Bricks łączy magazyn pamięci z agentem, którego tworzysz i wdrażasz za pomocą CLI. Wybierz klienta, który pasuje do Twojego projektu. Identyfikator magazynu pamięci musi mieć od 3 do 56 znaków, zaczynać się od małej litery, kończyć na literę lub cyfrę i zawierać jedynie małe litery, cyfry i łączniki.

AgentKit SDK

AgentKit SDK to klient Databricks Python dla API agentów, dystrybuowany w databricks-agentbricks pakiecie. Uwierzytelnia się przy użyciu zestawu SDK Databricks WorkspaceClient.

  1. Zainstaluj AgentKit SDK:

    pip install databricks-agentbricks

  2. Stwórz magazyn pamięci dla swojego agenta. AgentKitClient Uwierzytelnia się za pomocą Twoich WorkspaceClient danych:

    from databricks.sdk import WorkspaceClient
from databricks_agentkit import AgentKitClient

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

  3. Zapisz wspomnienie po tym, jak agent dowiaduje się czegoś trwałego o użytkowniku. actor_id określa, czyja to pamięć, path organizuje ją u tego aktora, a description poprawia odzyskiwanie:

    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() kończy się niepowodzeniem z powodu ALREADY_EXISTS, jeśli wpis już istnieje na tej ścieżce. Aby utworzyć wpis lub zaktualizować istniejący, wywołaj memory_store.put() z tymi samymi argumentami.

  4. Przypomnij sobie wspomnienia użytkownika w późniejszej rozmowie za pomocą wyszukiwania w języku naturalnym:

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

interfejs API REST

Klienci wywołują interfejs API REST pod adresem /api/2.0/agents/memory-stores. Wywołuj ją bezpośrednio w językach innych niż Python.

  1. Wygeneruj token OAuth za pomocą Databricks CLI:

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

  2. Stwórz magazyn pamięci dla swojego agenta:

    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. Zapisz wpis w pamięci dla użytkownika. actor_id wskazuje, czyja to pamięć, path ją organizuje, a description usprawnia jej wyszukiwanie:

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

    Jeśli wpis już istnieje na tej ścieżce, żądanie kończy się niepowodzeniem z błędem ALREADY_EXISTS (HTTP 409). Aby zamiast tego zaktualizować istniejący wpis, wyszukaj go po ścieżce. Wyszukiwanie zwraca wpisy ścieżki dla każdej sesji, więc wybierz tę, której session_id odpowiada. Ostatnim segmentem jego name jest identyfikator wpisu:

    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"

    Następnie zaktualizuj zawartość wpisu według jego 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. Przywołaj wspomnienia użytkownika za pomocą wyszukiwania w języku naturalnym:

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

Agent Bricks

Jeśli zbudujesz swojego agenta za pomocą Agent Bricks CLI, magazyn pamięci jest deklarowany w agent.toml przez agentbricks init. agentbricks deploy Tworzy magazyn, jeśli jeszcze nie istnieje, i przyznaje wdrożonemu agentowi dostęp do niego.

Wybierz ścieżkę:

  • Rozpocznij od pustego (większość agentów): Wdróż agenta. agentbricks deploy tworzy magazyn danych w pamięci, który agentbricks init zadeklarował. Aby wdrożyć agenta o nazwie my-agent, wykonaj następujące czynności:

    agentbricks deploy my-agent

  • Zacznij od pamięci już znajdujących się w sklepie: najpierw utwórz sklep, dodaj wpisy, potem powiąż sklep z agentem i wdroż.

    1. Aby utworzyć sklep o nazwie my-agent-memory, uruchom poniższe polecenie. Wynik zawiera identyfikator sklepu, wygenerowany identyfikator oddzielny od nazwy sklepu:

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

    2. Aby dodać wpis, wykonaj poniższe polecenie, zastępując <store-id> identyfikatorem sklepu z poprzedniego kroku:

      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. Aby połączyć sklep i wdrożyć agenta, wykonaj poniższe. agentbricks memory bind zastępuje nazwę sklepu w agent.toml, a agentbricks deploy znajduje istniejący sklep po nazwie i używa go zamiast tworzyć nowy:

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

--path to klucz do wpisu w sklepie, a nie plik na twoim komputerze. --actor-id jest użytkownikiem, do którego należy obszar pamięci. Wdrożony agent używa adresu e-mail zalogowanego użytkownika jako identyfikatora aktora, więc dodaj do każdego wpisu adres e-mail użytkownika, który rozmawia z agentem.

W CLI Agent Bricks memory bind i agentbricks deploy odnoszą się do sklepu po jego nazwie. Polecenia działające na pojedynczym magazynie, takie jak memory entries create, przyjmują wygenerowany identyfikator magazynu.

Daj agentowi narzędzia do pamięci

Aby agent mógł zdecydować, kiedy zapisywać i odczytywać pamięć, opakuj operacje klienta w narzędzia i poinstruuj agenta w jego monicie systemowym, kiedy ma ich używać. Ustaw actor_id w zaufanym kodzie aplikacji na podstawie zweryfikowanej tożsamości użytkownika końcowego. Nigdy nie pozwól modelowi wybierać, czyją pamięć odczytać lub zapisać.

Poniższy przykład obejmuje AgentKit SDK memory_store z Get Start jako narzędzia dla 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() tworzy wpis lub zastępuje zawartość wpisu już znajdującego się na tej ścieżce. Aby zamiast tego dodać treść jako nowe linie, należy przekazać append=True. put() nie jest atomowe, więc współbieżne zapisy na tę samą ścieżkę mogą się nadpisywać nawzajem. list(path=...) zwraca wpisy na dokładnie tej ścieżce w każdej sesji, a forget_memory także usuwa wszelkie wpisy zapisane na ścieżce w danej sesji.

Ten sam schemat działa w Claude Agent SDK i innych frameworkach: opakowanie operacji wyszukiwania, wstawiania, listowania i usuwania magazynu jako typu narzędzia frameworka.

Jeśli uruchamiasz także potok pamięci na tym samym magazynie, potok może przepisywać, scalać, dzielić lub usuwać wpisy, które agent zapisuje dla każdego aktora, którego przetwarza.

Partycjonowanie i zabezpieczona pamięć

W sklepie actor_id służy do rozróżniania, które wspomnienia należą do kogo. Każda lista i wyszukiwanie są ograniczone do jednego actor_id, więc wybierz strategię odpowiadającą temu, co Twój agent powinien zapamiętać:

  • Pamięć prywatna dla każdego użytkownika: Ustaw actor_id zweryfikowaną tożsamość użytkownika końcowego. Każdy użytkownik otrzymuje własną partycję, a agent pamięta tylko wpisy tego użytkownika.
    • Przykład: Agent wsparcia zapamiętuje preferencje komunikacyjne jednego użytkownika oraz wcześniejsze zgłoszenia.
  • Współdzielona pamięć dla grupy: Ustaw actor_id na stały klucz, który wybierzesz, na przykład identyfikator zespołu, projektu lub organizacji. Wszyscy czytają i zapisują te same wspomnienia.
    • Przykład: Agent zespołu zapamiętuje wspólny słownik terminów firmowych i wewnętrznych konwencji.
  • Pamięć podzielona na coś innego: Buduj actor_id na podstawie własnych wartości, takich jak identyfikator tenanta lub kompozyt.user:project
    • Przykład: Aplikacja wielodzierżawna ustawia actor_id na {tenant}:{user}, aby użytkownicy każdego klienta pozostawali odizolowani od siebie nawzajem.

Ustaw actor_id w kodzie aplikacji w kontekście zaufanego wywołującego: zweryfikowaną tożsamość użytkownika końcowego dla pamięci przypisanej do użytkownika lub zaufany klucz zespołu albo projektu dla pamięci współdzielonej. Nigdy nie pozwól, by modelka go wybrała. Jeśli twoja strategia opiera się na tożsamości użytkownika końcowego, odrzucaj żądania, które jej nie posiadają, zamiast wracać do współdzielonej actor_id.

Warning

actor_id oddziela wspomnienia, ale nie jest kontrolą dostępu. Magazyny pamięci są ograniczone do przestrzeni roboczej, więc każdy principal, który może uzyskać dostęp do magazynu, może odczytywać i zapisywać każdy wpis we wszystkich aktorach. Sklep, a nie aktor, jest granicą bezpieczeństwa. Aby zapewnić ścisłą izolację między tenantami lub użytkownikami, utwórz oddzielny magazyn pamięci dla każdej granicy.

Aby umożliwić innemu podmiotowi, na przykład przedstawicielowi usługowym Twojego agenta, korzystanie z magazynu, przyznaj mu dostęp za pomocą operacji przyzwolenia sklepu (memory_store.grant_permission(principal_id) w AgentKit SDK). Dostęp może przyznać tylko twórca sklepu lub administrator przestrzeni roboczej.

Limitations

  • Pamięć agenta zapewnia wyłącznie pamięć długoterminową. Krótkoterminową historię rozmów można znaleźć w sesjach agentów.
  • Wyszukiwanie klasyfikuje wpisy według trafności, łącząc pełny tekst (BM25) i dopasowywanie semantyczne na podstawie treści i opisu każdego wpisu. Zwraca do 100 wpisów i nie obsługuje paginacji.
  • Kontrola dostępu jest egzekwowana na poziomie sklepu. Kontrola dostępu na poziomie poszczególnych wpisów i aktorów nie jest dostępna.
  • Kontrola dostępu do sklepu obejmuje wejścia do sklepu. Każdy użytkownik przestrzeni roboczej może wyświetlać listę i pobierać magazyny pamięci, w tym ich ID i opisy.
  • Nie możesz zmienić identyfikatora sklepu po jego utworzeniu. Tylko description można zaktualizować.

Następne kroki

  • Ostatnia aktualizacja o