Pamięć zarządzanego agenta

Ważna

Ta funkcja jest dostępna w wersji beta. Administratorzy obszaru roboczego mogą kontrolować dostęp do tej funkcji ze strony Podglądy . Zobacz Zarządzanie wersjami zapoznawczami usługi Azure Databricks.

Zarządzana pamięć agenta zapewnia agentom pamięć długoterminową w różnych rozmowach. Azure Databricks uruchamia infrastrukturę i izoluje pamięć każdego zakresu, więc nie musisz samodzielnie zarządzać magazynem ani partycjonowaniem.

Dzięki pamięci zarządzanej agenci mogą wykonywać następujące czynności:

• Pamiętaj preferencje użytkownika, wcześniejsze decyzje i skumulowany kontekst między konwersacjami.
• Zabezpiecz tę wiedzę za pomocą mechanizmów zarządzania w Unity Catalog.
• Udostępnianie pamięci między agentami i projektami.
• Zwiększ ich dokładność i wydajność z czasem.

Requirements

• Obszar roboczy usługi Databricks z włączoną funkcją Unity Catalog.
• Uprawnienie CREATE MEMORY STORE do tworzenia magazynów pamięci w schemacie nadrzędnym.

Jak działa pamięć zarządzana

Pamięć zarządzana ma dwa poziomy:

• Magazyn pamięci to obiekt zabezpieczany w Unity Catalog, który pełni funkcję kontenera dla wpisów pamięci. Magazyn pamięci dziedziczy ten sam nadzór, kontrolę dostępu i pochodzenie danych jak każdy inny zasób w Unity Catalog.
• Wpis pamięci to pojedynczy element zawartości przechowywany w magazynie pamięci. Każdy wpis jest identyfikowany przez zakres i ścieżkę. Zakres określa, do których wspomnień należy wpis, a ścieżka organizuje wpisy w zakresie, podobnie jak ścieżka pliku (na przykład /memories/preferences.md).

Scope

Zakres to sposób, w jaki sprawiasz, że pamięć jest prywatna dla jednego użytkownika lub udostępniana w grupie. Twoja aplikacja ustawia zakres przy każdym odczytie i zapisie, a wyszukiwanie zwraca tylko wpisy z odpowiadającym zakresem. Wybierz strategię odpowiadającą temu, co Twój agent powinien zapamiętać:

• Pamięć prywatna dla każdego użytkownika: Ustaw zakres na zweryfikowaną tożsamość użytkownika końcowego. Każdy użytkownik otrzymuje własną partycję i widzi tylko swoje wpisy. Wartość user_client ustala za Ciebie identyfikator użytkownika końcowego.
  • Przykład: Agent wsparcia zapamiętuje preferencje komunikacyjne jednego użytkownika oraz wcześniejsze zgłoszenia.
• Wspólna pamięć dla grupy: Ustaw zakres na stały wybrany przez siebie klucz, na przykład organizację, zespół lub identyfikator projektu. Każdy użytkownik czyta i zapisuje te same wspomnienia.
  • Przykład: Agent zespołu pamięta wspólny słownik terminów firmy i wewnętrznych polityk.
• Pamięć podzielona przez coś innego: Buduj zakres na podstawie własnych wartości, takich jak identyfikator tenanta lub kompozyt.user_id:project
  • Przykład: Aplikacja wielodostępna utrzymuje pamięć każdego klienta oddzielnie albo pamięć pojedynczego użytkownika jest izolowana dla każdego projektu.

Pojedynczy agent może łączyć strategie w jednej rozmowie. Na przykład może odczytać prywatną pamięć użytkownika oraz wspólną pamięć zespołu w tym samym żądaniu.

Ustaw zakres w kodzie aplikacji na podstawie zaufanego kontekstu wywołującego, którym żądanie nie może manipulować: zweryfikowanej tożsamości użytkownika końcowego z tokenu OBO dla pamięci przypisanej do użytkownika albo zaufanej dzierżawy, zespołu lub klucza projektu dla pamięci współdzielonej. Nigdy nie pozwól, by modelka go wybrała. Jeśli strategia zakresu zależy od tożsamości użytkownika końcowego, odrzucaj żądania, które jej nie posiadają, zamiast wracać do wspólnego zakresu. Umiejętnośćmanaged-memory prowadzi cię przez ten układ.

Scope rozdziela wspomnienia, ale nie daje dostępu do sklepu. Aby go otworzyć, wywołujący nadal musi mieć uprawnienie READ MEMORY STORE lub WRITE MEMORY STORE. Zobacz Kontrola dostępu do pamięci.

Warning

Zakres to granica izolacji między użytkownikami, ale nie jest kontrolą dostępu. Właściciel usługi aplikacji może odczytać każdy zakres, więc odpowiednio chroń swoje poświadczenia.

Co agent zapisuje i pamięta

Pamięć zarządzana zapewnia magazyn pamięci oraz API do odczytu i zapisu wpisów. Twoja aplikacja kontroluje, co agent zapisuje, kiedy pobiera pamięć i jak wykorzystuje wyniki.

Zdefiniuj to zachowanie w pokrecie systemowym agenta: poinstruuj agenta, jakie trwałe informacje ma zapisać i kiedy je odzyskać. Funkcja managed-memory i szablony przechowują ten prompt systemowy w stałej o nazwie MEMORY_INSTRUCTIONS. Zakres jest konfigurowany osobno w zaufanym kodzie aplikacji i nigdy nie jest wybierany przez model.

Dopasuj sformułowanie do swojej strategii zakresu. Poniżej znajduje się przykład strategii dla poszczególnych użytkowników:

You have durable, cross-session memory about whoever (or whatever) this conversation is scoped to. Use it deliberately, not by reflex.

Recall whenever the answer is about the user or calls for personalized information — anything that might draw on preferences, decisions, or workflows they've shared before — and you don't already have it from this conversation; also list once before saving, to find the right existing topic. Don't tell the user you don't know their preferences without checking — list_memories first. Skip memory only when the answer truly doesn't depend on who's asking (general knowledge, math, coding) or you already have what you need. A `[has_contents]` entry has a body to get_memory; one without is fully captured by its description. Open a memory with get_memory before you state its specifics, and never assert a fact that isn't stored — if nothing relevant is stored, just answer without it. Don't re-list what you've already seen this turn.

Save only what will still matter in a future, unrelated conversation — a stable preference, fact, decision, or ongoing project the user actually stated or decided. Don't save your own suggestions or guesses, passing chatter, secrets, or anything scoped to this chat ("for now", a one-off label).
- Write each memory so it stands on its own out of context, under one broad, stable /memories/... topic per subject with the specifics inside it.
- Check the list first and update_memory an existing topic instead of minting a near-duplicate.
- For a very broad question that touches many memories, summarize from the list's descriptions; reserve get_memory for the specific entry you actually need.
- If the user's info changes or contradicts what's stored, update or replace it rather than keeping both — but don't rewrite a memory that already says the same thing.
- delete_memory what's stale.
- Briefly tell the user whenever you save, update, or delete.

Zacznij od umiejętności zarządzania pamięcią

Najprostszym sposobem na dodanie agentowi pamięci zarządzanej jest funkcja managed-memory Claude Code. Ta funkcja zajmuje się całą konfiguracją za Ciebie i współpracuje zarówno z pakietem SDK OpenAI Agents, jak i z LangGraph.

Uzyskaj umiejętności w projekcie na jeden z dwóch sposobów:

Rozpoczynanie od szablonu

Umiejętność jest dostarczana w ramach szablonów aplikacji Databricks. Utwórz nowego agenta na podstawie jednego z szablonów agenta, znajdź umiejętność pod .claude/skills/managed-memory/.

1. Sklonuj repozytorium szablonów:

   git clone https://github.com/databricks/app-templates.git
   

2. Przejdź do app-templates, wybierz szablon agenta, od którego chcesz zacząć. Aby na przykład użyć szablonu zestawu SDK agentów OpenAI:

   cd app-templates/agent-openai-agents-sdk
   

   Note

   W przypadku „zaawansowanych” szablonów aplikacji po wdrożeniu należy nadać nazwie głównej usługi aplikacji uprawnienia w Lakebase Postgres, w przeciwnym razie inicjowanie sesji zwróci błąd 502.

3. Gdy umiejętność znajduje się w projekcie, opisz, co chcesz, a asystent kodowania zajmuje się resztą:

   Tip

   Add Databricks managed long-term memory to my agent.
   

Dodawanie umiejętności do istniejącego projektu

Jeśli masz już projekt agenta, dodaj do niego umiejętności.

1. Utwórz katalog umiejętności, jeśli nie istnieje:

   mkdir -p .claude/skills/managed-memory
   

2. Pobierz plik SKILL.md z katalogu umiejętności managed-memory i zapisz go w .claude/skills/managed-memory/.

3. Gdy umiejętność znajduje się w projekcie, opisz, co chcesz, a asystent kodowania zajmuje się resztą:

   Tip

   Add Databricks managed long-term memory to my agent.
   

Ręczne tworzenie i używanie magazynu pamięci

W tej sekcji pokazano, jak utworzyć i używać magazynu pamięci bez managed-memory umiejętności Claude Code.

W poniższym przykładzie skonfigurowano pamięć zarządzaną dla agenta pomocy technicznej klienta, który przechowuje preferencje użytkownika i pobiera je w późniejszej konwersacji.

1. Wygeneruj token OAuth za pomocą Databricks CLI, aby wywoływać interfejsy API:

   databricks auth login --host ${DATABRICKS_HOST}
   databricks auth token
   

2. Utwórz magazyn pamięci do przechowywania pamięci agenta:

   curl -X POST "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "support_agent_memory",
       "catalog_name": "main",
       "schema_name": "default",
       "description": "Long-term memory for the customer support agent"
     }'
   

3. Napisz wpis pamięci po tym, jak agent nauczy się czegoś o użytkowniku. scope przypisuje wpis do jednego użytkownika. Użyj pola contents dla pełnej treści pamięci, a pola description jako krótkiego podsumowania, które usprawnia wyszukiwanie:

   curl -X POST \
     "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.support_agent_memory/entries?scope=user-123" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "path": "/memories/preferences.md",
       "contents": "Prefers email communication. Timezone: PST. Has an Enterprise subscription.",
       "description": "User 123 communication preferences and account details"
     }'
   

4. Wyszukaj wpisy w pamięci dotyczące tego użytkownika w późniejszej rozmowie, aby odzyskać informacje, których nauczył się agent:

   curl -X POST \
     "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.support_agent_memory/entries:search" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "scope": "user-123",
       "query": "communication preferences"
     }'
   

Pełny opis interfejsu REST API, w tym endpointy oraz pola żądań i odpowiedzi, znajdziesz w dokumencie Dokumentacja interfejsu Memory API.

Dodaj pamięć do agenta za pomocą rozmów

Powyższy przepływ pracy REST wywołuje bezpośrednio magazyn pamięci i interfejsy API wprowadzania. Zamiast tego podczas tworzenia agenta w punkcie końcowym obsługi modeli Azure Databricks połącz magazyn pamięci z rozmową za pomocą klienta zgodnego z OpenAI w pakiecie SDK databricks-openai.

Konwersacja to zgodny z OpenAI stan konwersacji — bieżąca historia wiadomości i wywołań narzędzi — oparty na magazynie pamięci i przypisany do jednego zakresu. Używaj tej samej rozmowy w kolejnych żądaniach, aby agent pamiętał wcześniejsze wypowiedzi.

1. Wiązanie istniejącego magazynu pamięci i zakresu z nową konwersacją. memory_store.name to trójpoziomowa nazwa magazynu danych, a scope dzieli stan konwersacji, zwykle według użytkownika końcowego:

   from databricks.sdk import WorkspaceClient
   from databricks_openai import DatabricksOpenAI
   
   workspace_client = WorkspaceClient()
   user_id = str(workspace_client.current_user.me().id)
   
   client = DatabricksOpenAI(workspace_client=workspace_client, use_ai_gateway=True)
   
   conversation = client.conversations.create(
       extra_body={
           "memory_store": {"name": "main.default.support_agent_memory"},
           "scope": {"kind": "user", "value": user_id},
       },
   )
   

2. Przekaż identyfikator rozmowy do responses.create. Agent odczytuje i zapisuje stan konwersacji w przypisanym magazynie pamięci w obrębie tego zakresu:

   response = client.responses.create(
       model="databricks-gpt-5-2",
       conversation=conversation.id,
       input=[{"type": "message", "role": "user", "content": "What is the average NYC taxi price?"}],
       stream=True,
   )
   
   for event in response:
       if event.type == "response.output_text.delta":
           print(event.delta, end="", flush=True)
   

3. Używaj tego samego identyfikatora konwersacji w kolejnych żądaniach, aby agent pamiętał wcześniejsze wypowiedzi. Nie twórz nowej rozmowy dla każdej tury:

   followup = client.responses.create(
       model="databricks-gpt-5-2",
       conversation=conversation.id,
       input=[{"type": "message", "role": "user", "content": "Restate the average taxi price you found, and how it was calculated."}],
       stream=True,
   )
   
   for event in followup:
       if event.type == "response.output_text.delta":
           print(event.delta, end="", flush=True)
   

Aby zapoznać się z punktami końcowymi konwersacji i polami żądania, zobacz Interfejsy API konwersacji.

Kontrola dostępu do pamięci

Magazyny pamięci są obiektami zabezpieczalnymi w Unity Catalog. Następujące uprawnienia kontrolują dostęp:

Przywilej	Dotyczy	Description
CREATE MEMORY STORE	Schemat nadrzędny	Utwórz nowe magazyny pamięci w ramach schematu.
READ MEMORY STORE	Magazyn pamięci	Odczytywanie metadanych magazynu pamięci i jego wpisów.
WRITE MEMORY STORE	Magazyn pamięci	Utwórz, zaktualizuj i usuń wpisy pamięci w repozytorium.
MANAGE	Magazyn pamięci	Zaktualizuj lub usuń sam magazyn pamięci. Udzielanie uprawnień innym użytkownikom.
USE SCHEMA	Schemat nadrzędny	Wyświetl magazyny danych w pamięci w schemacie.

Implementowanie pamięci krótkoterminowej

Interfejsy API wprowadzania pamięci zapewniają długoterminową pamięć jako narzędzia do użycia przez agenta. Aby zapewnić agentowi zarządzaną pamięć krótkoterminową w sesji, Databricks zaleca powiązanie magazynu pamięci z rozmową. Możesz również wykonać następujące czynności:

• Zachowaj pamięć sesji platformy agenta, taką jak parametr OpenAI session= lub program LangGraph checkpointer.
• Użyj pamięci agenta zarządzanej samodzielnie jako magazynu historii konwersacji.

Zalecenia dotyczące zabezpieczeń

Azure Databricks zapewnia magazyn danych podlegający nadzorowi, szyfrowanie, mechanizmy izolacji i ścieżkę audytu. Jako deweloper aplikacji usługa Databricks zaleca następujące zalecenia:

• Użyj domyślnego zakresu dla poszczególnych użytkowników (user_client), chyba że masz celowy powód, aby partycjonować inaczej (na przykład dla każdego projektu lub pamięci dla konta).
• Udziel najniższych uprawnień: tylko jednostka usługi twojego agenta wymaga WRITE MEMORY STORE. Przyznawaj READ MEMORY STORE tylko w niezbędnym zakresie i unikaj przyznawania zbyt szerokich uprawnień użytkownikom lub dużym grupom.
• Chroń poświadczenia nazwy głównej usługi App Service: to klucz do płaszczyzny danych magazynu. Traktuj je jak każde poświadczenie usługi o wysokiej wartości — używaj tokenów krótkotrwałych, unikaj rejestrowania go i dodawaj zabezpieczenia SSRF do aplikacji.

Limitations

• Wpisy w pamięci zapewniają wyłącznie pamięć długoterminową. Aby uzyskać różnicę między krótkoterminową i długoterminową pamięcią, zobacz Krótkoterminowa i długoterminowa pamięć.
• Magazyny pamięci i wpisy tworzy się i zarządza nimi wyłącznie za pośrednictwem interfejsu API REST usługi Unity Catalog; dla tych interfejsów API nie jest dostępny pakiet SDK dla języka Python. Aby użyć magazynu pamięci z agenta, połącz go z konwersacją z klientem zgodnym z programem OpenAI. Zobacz Dodawanie pamięci do agenta za pomocą konwersacji.

Następne kroki

• Dokumentacja interfejsu API pamięci