Pamięć zarządzanego agenta

Ważna

Ta funkcja jest dostępna w wersji beta.

Zarządzana pamięć agentów zapewnia agentom trwałą pamięć długoterminową, która utrzymuje się między rozmowami. Azure Databricks przechowuje pamięć w Lakebase i zarządza przechowywaniem, indeksowaniem oraz wyszukiwaniem semantycznym za Ciebie, dzięki czemu twoi agenci mogą pamiętać preferencje użytkowników, 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. Za samą pamięć agenta zarządzanego nie są naliczane dodatkowe opłaty. Ceny mogą ulec zmianie w miarę postępu zapowiedzi.

Używaj pamięci zarządzanej, 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.

Zarządzana pamięć działa z agentami zbudowanymi na dowolnym frameworku. Dla krótkoterminowej historii rozmów w ramach jednej interakcji korzystaj z sesji zarządzanych agentów.

Jak działa pamięć zarządzana

Hierarchia zasobów pamięci zarządzanego 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 przechowuje zawartość i opis.

Pamięć zarządzana ma dwa poziomy:

  • Magazyn pamięci to kontener w obrębie obszaru roboczego na wspomnienia agenta. Tworzenie sklepu automatycznie zapewnia pamięć Lakebase wspierającą. Odwołujesz się do sklepu za pomocą jego display_name.
  • 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): rejestruje, z której sesji pochodzi zapis pamięci, na potrzeby śledzenia i ustalania pochodzenia. Pozostaw to pole nieustawione dla pamięci, która nie jest powiązana z konkretną sesją.
    • 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.

Odzyskiwanie

Przywołaj pamięć na dwa sposoby:

  • Wyświetl wpisy dla aktora, opcjonalnie filtrowane według session_id lub prefiksu 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 uszeregowane według wskaźnika trafności pełnego tekstu (BM25).

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.

Wprowadzenie

Te przykłady tworzą zarządzaną pamięć dla agenta wsparcia: tworzy on magazyn pamięci, zapisuje preferencje użytkownika i przywołuje je w późniejszej rozmowie. Wybierz klienta, który pasuje do Twojego projektu. Parametr display_name magazynu pamięci musi mieć od 3 do 56 znaków, zaczynać się małą literą, kończyć się literą lub cyfrą oraz zawierać tylko małe litery, cyfry i myślniki.

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

  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" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"display_name": "support-agent-memory", "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"}'

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

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

Ten sam schemat działa z Claude Agent SDK i innymi frameworkami: opakuj wyszukiwanie sklepu i dodaj operacje jako typ narzędzia frameworka.

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. Zasoby pamięci zarządzanej są ograniczone do obszaru roboczego, więc każdy podmiot, który ma dostęp do takiego zasobu, może odczytywać i zapisywać każdy wpis dla wszystkich aktorów. 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).

Limitations

  • Pamięć zarządzana zapewnia wyłącznie pamięć długotrwałą. Krótkoterminową historię rozmów można znaleźć w artykule o sesjach z zarządzanymi agentami.
  • Wyszukiwanie to pełnotekstowa operacja (BM25) uszeregowana według trafności, która zwraca zestaw N najlepszych wyników obejmujący maksymalnie 100 pozycji. Nie obsługuje paginacji ani wyszukiwania podobności wektorów.
  • Kontrola dostępu jest egzekwowana na poziomie sklepu. Kontrola dostępu na poziomie poszczególnych wpisów i aktorów nie jest dostępna.
  • Magazyn display_name jest niemodyfikowalny po utworzeniu. Tylko description można zaktualizować.

Następne kroki

  • Last updated on