Udostępnij przez

Tworzenie i używanie pamięci w agencie Foundry (wersja zapoznawcza)

Ważna

Pamięć (wersja zapoznawcza) w usłudze agenta rozwiązania Foundry i interfejs API magazynu pamięci (wersja zapoznawcza) są licencjonowane jako część subskrypcji Azure i podlegają warunkom "wersja zapoznawcza" w warunkach produktów i usług firmy Microsoft oraz dodatku do ochrony danych produktów i usług firmy Microsoft, a także warunkach wersji zapoznawczych usługi generatywna AI firmy Microsoft w ramach dodatkowych warunków użytkowania wersji zapoznawczych Microsoft Azure.

Pamięć w usłudze Foundry Agent to zarządzane, długoterminowe rozwiązanie pamięci. Umożliwia ciągłość agenta między sesjami, urządzeniami i przepływami pracy. Tworząc magazyny pamięci i zarządzając nimi, można tworzyć agentów, którzy zachowują preferencje użytkownika, przechowują historię konwersacji i dostarczają spersonalizowane doświadczenia.

Magazyny pamięci działają jako magazyn trwały, definiując, które typy informacji są istotne dla każdego agenta. Dostęp można kontrolować przy użyciu parametru scope , który segmentuje pamięć między użytkownikami, aby zapewnić bezpieczne i izolowane środowiska.

W tym artykule wyjaśniono, jak tworzyć magazyny pamięci, zarządzać nimi i korzystać z nich. Aby uzyskać informacje koncepcyjne, zobacz Pamięć w usłudze agenta Foundry.

Wsparcie użytkowania

Capability Zestaw SDK dla języka Python interfejs API REST
Tworzenie, aktualizowanie, wyświetlanie listy i usuwanie magazynów pamięci ✔️ ✔️
Aktualizowanie i wyszukiwanie wspomnień ✔️ ✔️
Dołączanie pamięci do agenta monitu ✔️ ✔️

Wymagania wstępne

Autoryzacja i uprawnienia

Zalecamy kontrolę dostępu opartą na rolach dla wdrożeń produkcyjnych. Jeśli role nie są wykonalne, pomiń tę sekcję i zamiast tego użyj uwierzytelniania opartego na kluczach.

Aby skonfigurować dostęp oparty na rolach:

  1. Zaloguj się do Portal Azure.
  2. W projekcie:
    1. W okienku po lewej stronie wybierz Zarządzanie zasobami>Tożsamość.
    2. Użyj przełącznika , aby włączyć tożsamość zarządzaną przypisaną przez system.
  3. Na zasobie, który zawiera Twój projekt:
    1. W okienku po lewej stronie wybierz pozycję Kontrola dostępu (Zarządzanie dostępem i tożsamościami).
    2. Wybierz Dodaj>Dodaj przypisanie roli.
    3. Przypisz użytkownika usługi Azure AI do tożsamości zarządzanej projektu.

Ustawianie punktu końcowego projektu

W przypadku przykładów języka Python w tym artykule ustaw zmienną środowiskową dla punktu końcowego projektu:

export FOUNDRY_PROJECT_ENDPOINT="https://{your-ai-services-account}.services.ai.azure.com/api/projects/{project-name}"

$env:FOUNDRY_PROJECT_ENDPOINT = "https://{your-ai-services-account}.services.ai.azure.com/api/projects/{project-name}"

Objaśnienie zakresu

Parametr scope określa sposób partycjonowania pamięci. Każdy zakres w magazynie pamięci przechowuje izolowane kolekcje elementów pamięci. Jeśli na przykład utworzysz agenta pomocy technicznej klienta z pamięcią, każdy klient powinien mieć własną pamięć indywidualną.

Jako deweloper wybierasz klucz używany do przechowywania i pobierania elementów pamięci. Można przekazać wartość statyczną, taką jak unikatowy identyfikator (UUID) lub inny stabilny identyfikator z systemu.

Alternatywnie po określeniu {{$userId}} jako zakresu system automatycznie wyodrębnia identyfikator dzierżawy (TID) i identyfikator obiektu (OID) z nagłówka uwierzytelniania żądania. Takie podejście zapewnia każdemu uwierzytelnionemu użytkownikowi własną partycję izolowanej pamięci, eliminując konieczność ręcznego zarządzania identyfikatorami.

Tworzenie magazynu pamięci

Utwórz dedykowany magazyn pamięci dla każdego agenta, aby ustalić jasne granice dostępu do pamięci i optymalizacji. Podczas tworzenia magazynu pamięci określ model czatu i osadzanie wdrożeń modelu, które przetwarzają zawartość pamięci.

import os
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MemoryStoreDefaultDefinition, MemoryStoreDefaultOptions
from azure.identity import DefaultAzureCredential

project_client = AIProjectClient(
    endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

memory_store_name = "my_memory_store"

# Specify memory store options
options = MemoryStoreDefaultOptions(
    chat_summary_enabled=True,
    user_profile_enabled=True,
    user_profile_details="Avoid irrelevant or sensitive data, such as age, financials, precise location, and credentials"
)

# Create memory store
definition = MemoryStoreDefaultDefinition(
    chat_model="gpt-5.2",  # Your chat model deployment name
    embedding_model="text-embedding-3-small",  # Your embedding model deployment name
    options=options
)

memory_store = project_client.beta.memory_stores.create(
    name=memory_store_name,
    definition=definition,
    description="Memory store for customer support agent",
)

print(f"Created memory store: {memory_store.name}")

Dostosowywanie pamięci

Dostosuj informacje przechowywane przez agenta, aby były efektywne pod względem pamięci, istotne i z poszanowaniem prywatności. Użyj parametru user_profile_details , aby określić typy danych, które mają kluczowe znaczenie dla funkcji agenta.

Na przykład ustaw priorytet na "preferencje dotyczące przewoźnika lotniczego i ograniczenia żywieniowe" dla agenta turystycznego używającego user_profile_details. Takie ukierunkowane podejście pomaga systemowi pamięci wiedzieć, które szczegóły mają być wyodrębnione, podsumowane i zatwierdzane w pamięci długoterminowej.

Możesz również użyć tego parametru, aby wykluczyć niektóre typy danych, zachowując bezpieczeństwo pamięci i zgodność z wymaganiami dotyczącymi prywatności. Na przykład ustaw wartość user_profile_details: "unikaj danych nieistotnych lub poufnych, takich jak wiek, finanse, dokładna lokalizacja i poświadczenia".

Aktualizowanie magazynu pamięci

Zaktualizuj właściwości magazynu pamięci, takie jak description lub metadata, aby lepiej zarządzać magazynami pamięci.

# Update memory store properties
updated_store = project_client.beta.memory_stores.update(
    name=memory_store_name,
    description="Updated description"
)

print(f"Updated: {updated_store.description}")

Lista magazynów pamięci

Pobierz listę magazynów pamięci w projekcie, aby zarządzać infrastrukturą pamięci i monitorować nią.

# List all memory stores
stores_list = list(project_client.beta.memory_stores.list())

print(f"Found {len(stores_list)} memory stores")
for store in stores_list:
    print(f"- {store.name} ({store.description})")

Używanie pamięci przy użyciu narzędzia agentowego

Po utworzeniu magazynu pamięci można dołączyć narzędzie wyszukiwania pamięci do agenta monitu. To narzędzie umożliwia agentowi odczytywanie i zapisywanie w magazynie pamięci podczas konwersacji. Skonfiguruj narzędzie, używając odpowiednich scope i update_delay, aby kontrolować sposób i moment aktualizowania pamięci.

# Continue from the previous Python snippets.
from azure.ai.projects.models import MemorySearchPreviewTool, PromptAgentDefinition

# Set scope to associate the memories with
# You can also use "{{$userId}}" to take the TID and OID of the request authentication header
scope = "user_123"

openai_client = project_client.get_openai_client()

# Create memory search tool
tool = MemorySearchPreviewTool(
    memory_store_name=memory_store_name,
    scope=scope,
    update_delay=1,  # Wait 1 second of inactivity before updating memories
    # In a real application, set this to a higher value like 300 (5 minutes, default)
)

# Create a prompt agent with memory search tool
agent = project_client.agents.create_version(
    agent_name="MyAgent",
    definition=PromptAgentDefinition(
        model="gpt-5.2",
        instructions="You are a helpful assistant that answers general questions",
        tools=[tool],
    )
)

print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

Tworzenie konwersacji

Teraz możesz tworzyć konwersacje i żądać odpowiedzi agenta. Na początku każdej konwersacji są wstrzykiwane statyczne wspomnienia, dzięki czemu agent ma natychmiastowy, trwały kontekst. Pamięci kontekstowe są pobierane na zmianę na podstawie najnowszych komunikatów, aby wpłynąć na każdą odpowiedź.

Po każdej odpowiedzi agenta usługa wewnętrznie wywołuje update_memories. Jednak rzeczywiste zapisy w pamięci długoterminowej są odrzucene update_delay przez ustawienie. Aktualizacja jest zaplanowana i kończy się tylko po skonfigurowanym okresie braku aktywności.

import time

# Create a conversation with the agent with memory tool enabled
conversation = openai_client.conversations.create()
print(f"Created conversation (id: {conversation.id})")

# Create an agent response to initial user message
response = openai_client.responses.create(
    input="I prefer dark roast coffee",
    conversation=conversation.id,
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)

print(f"Response output: {response.output_text}")

# After an inactivity in the conversation, memories will be extracted from the conversation and stored
print("Waiting for memories to be stored...")
time.sleep(65)

# Create a new conversation
new_conversation = openai_client.conversations.create()
print(f"Created new conversation (id: {new_conversation.id})")

# Create an agent response with stored memories
new_response = openai_client.responses.create(
    input="Please order my usual coffee",
    conversation=new_conversation.id,
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)

print(f"Response output: {new_response.output_text}")

Używanie pamięci za pośrednictwem interfejsów API

Możesz korzystać z magazynu pamięci bezpośrednio przy użyciu interfejsów API magazynu pamięci. Zacznij od dodania wspomnień z zawartości konwersacji do magazynu pamięci, a następnie wyszukaj odpowiednie wspomnienia, aby zapewnić kontekst interakcji z agentem.

Dodawanie pamięci do magazynu pamięci

Dodaj wspomnienia, udostępniając zawartość konwersacji do magazynu pamięci. System wstępnie i końcowo przetwarza dane, w tym wyodrębnianie pamięci i konsolidację, w celu optymalizacji pamięci agenta. Ta długotrwała operacja może potrwać około jednej minuty.

Zdecyduj, jak podzielić pamięć na użytkowników, określając scope parametr . Możesz określić zakres pamięci dla określonego użytkownika końcowego, zespołu lub innego identyfikatora.

Magazyn pamięci można zaktualizować zawartością z wielu tur rozmowy lub po każdej turze i łączyć aktualizacje, wykorzystując poprzedni identyfikator operacji aktualizacji.

# Continue from the previous Python snippets.
# Set scope to associate the memories with
scope = "user_123"

user_message = {
  "role": "user",
  "content": "I prefer dark roast coffee and usually drink it in the morning",
   "type": "message"
}

update_poller = project_client.beta.memory_stores.begin_update_memories(
    name=memory_store_name,
    scope=scope,
    items=[user_message],  # Pass conversation items that you want to add to memory
    update_delay=0,  # Trigger update immediately without waiting for inactivity
)

# Wait for the update operation to complete, but can also fire and forget
update_result = update_poller.result()
print(f"Updated with {len(update_result.memory_operations)} memory operations")
for operation in update_result.memory_operations:
    print(
        f"  - Operation: {operation.kind}, Memory ID: {operation.memory_item.memory_id}, Content: {operation.memory_item.content}"
    )

# Extend the previous update with another update and more messages
new_message = {
    "role":"user", 
    "content":"I also like cappuccinos in the afternoon", 
    "type":"message"}

new_update_poller = project_client.beta.memory_stores.begin_update_memories(
    name=memory_store_name,
    scope=scope,
    items=[new_message],
    previous_update_id=update_poller.update_id,  # Extend from previous update ID
    update_delay=0,  # Trigger update immediately without waiting for inactivity
)
new_update_result = new_update_poller.result()
for operation in new_update_result.memory_operations:
    print(
        f"  - Operation: {operation.kind}, Memory ID: {operation.memory_item.memory_id}, Content: {operation.memory_item.content}"
    )

Wyszukiwanie pamięci w magazynie pamięci

Przeszukiwanie wspomnień w celu pobrania odpowiedniego kontekstu interakcji z agentem. Określ nazwę i zakres magazynu pamięci, aby zawęzić wyszukiwanie.

# Continue from the previous Python snippets.
from azure.ai.projects.models import MemorySearchOptions

# Search memories by a query
query_message = {"role": "user", "content": "What are my coffee preferences?", "type": "message"}

search_response = project_client.beta.memory_stores.search_memories(
    name=memory_store_name,
    scope=scope,
    items=[query_message],
    options=MemorySearchOptions(max_memories=5)
)
print(f"Found {len(search_response.memories)} memories")
for memory in search_response.memories:
    print(f"  - Memory ID: {memory.memory_item.memory_id}, Content: {memory.memory_item.content}")

Pobieranie pamięci statycznych lub kontekstowych

Często nie można pobrać danych profilu użytkownika na podstawie semantycznego podobieństwa do wiadomości użytkownika. Zalecamy wstrzyknięcie statycznych wspomnień na początku każdej konwersacji i użycie wspomnień kontekstowych w celu wygenerowania odpowiedzi agenta.

  • Aby pobrać pamięci statyczne, wywołaj search_memories z argumentem scope, ale bez items lub previous_search_id. Spowoduje to zwrócenie pamięci profilu użytkownika skojarzonych z zakresem.

  • Aby pobrać pamięci kontekstowe, wywołaj metodę search_memories, ustawiając items na najnowsze komunikaty. Może to zwracać zarówno informacje o profilu użytkownika, jak i podsumowaniu czatu, które są najbardziej istotne dla danego elementu.

Aby uzyskać więcej informacji na temat wspomnień dotyczących profilu użytkownika i podsumowania czatów, zobacz Typy pamięci.

Usuwanie pamięci

Ostrzeżenie

Przed usunięciem magazynu pamięci należy wziąć pod uwagę wpływ na agentów zależnych. Agenci z dołączonymi magazynami pamięci mogą utracić dostęp do kontekstu historycznego.

Pamięci są uporządkowane pod względem zakresu w magazynie pamięci. Możesz usunąć pamięci dla określonego zakresu w celu usunięcia danych specyficznych dla użytkownika lub usunąć cały magazyn pamięci, aby usunąć wszystkie wspomnienia we wszystkich zakresach.

Usuwanie pamięci według zakresu

Usuń wszystkie wspomnienia skojarzone z określonym zakresem użytkownika lub grupy, zachowując strukturę magazynu pamięci. Ta operacja służy do obsługi żądań usunięcia danych użytkownika lub resetowania pamięci dla określonych użytkowników.

# Delete memories for a specific scope
project_client.beta.memory_stores.delete_scope(
    name=memory_store_name,
    scope="user_123"
)

print(f"Deleted memories for scope: user_123")

Usuwanie magazynu pamięci

Usuń cały magazyn pamięci i wszystkie skojarzone pamięci we wszystkich zakresach. Ta operacja jest nieodwracalna.

# Delete the entire memory store
delete_response = project_client.beta.memory_stores.delete(memory_store_name)
print(f"Deleted memory store: {delete_response.deleted}")

Najlepsze rozwiązania

  • Zaimplementuj mechanizmy kontroli dostępu poszczególnych użytkowników: Unikaj udzielania agentom dostępu do wspomnień udostępnianych wszystkim użytkownikom. Użyj właściwości scope, aby podzielić magazyn pamięci według użytkownika. Gdy udostępniasz scope dane użytkownikom, użyj polecenia user_profile_details , aby system pamięci nie przechowywał danych osobowych.

  • Mapuj zakres na uwierzytelnionego użytkownika: Po określeniu zakresu w narzędziu wyszukiwania pamięci ustaw opcję scope={{$userId}} mapowania na użytkownika z tokenu uwierzytelniania ({tid}_{oid}). Dzięki temu wyszukiwanie pamięci będzie automatycznie kierowane do poprawnego użytkownika.

  • Minimalizuj i chroń poufne dane: Przechowuj tylko to, co jest niezbędne w twoim przypadku użycia. Jeśli musisz przechowywać dane o charakterze poufnym, takie jak dane osobowe, zdrowotne lub poufne informacje biznesowe, zredaguj lub usuń inną zawartość, której można użyć, aby dotrzeć do konkretnej osoby.

  • Obsługa prywatności i zgodności: Zapewnienie użytkownikom przejrzystości, w tym opcji uzyskiwania dostępu do danych i ich usuwania. Zarejestruj wszystkie usunięcia w dzienniku audytu odpornym na manipulacje. Upewnij się, że system jest zgodny z lokalnymi wymaganiami dotyczącymi zgodności i standardami prawnymi.

  • Segmentowanie danych i izolowanie pamięci: W systemach z wieloma agentami segmentuj pamięć logicznie i operacyjnie. Zezwól klientom na definiowanie, izolowanie, inspekcję i usuwanie własnych śladów pamięci.

  • Monitorowanie użycia pamięci: Śledzenie użycia tokenu i operacji pamięci w celu zrozumienia kosztów i optymalizacji wydajności.

Rozwiązywanie problemów

Problematyka Przyczyna Rezolucja
Żądania kończą się niepowodzeniem z powodu błędu uwierzytelniania lub autoryzacji. Twoja tożsamość lub zarządzana tożsamość w projekcie nie ma wymaganych ról. Sprawdź role w Autoryzacji i uprawnieniach. W przypadku wywołań REST wygeneruj nowy token dostępu i spróbuj ponownie.
Wspomnienia nie pojawiają się po rozmowie. Aktualizacje pamięci są odrzucene lub nadal przetwarzane. Zwiększ czas oczekiwania lub wywołaj interfejs API aktualizacji, ustawiając update_delay na 0, aby natychmiast wyzwolić przetwarzanie.
Wyszukiwanie pamięci nie zwraca żadnych wyników. Wartość scope nie jest zgodna z zakresem używanym podczas zapisywania danych w pamięci. Użyj tego samego zakresu na potrzeby aktualizacji i wyszukiwania. Jeśli przypisujesz zakres funkcji użytkownikom, użyj stabilnego identyfikatora użytkownika.
Odpowiedź agenta nie używa przechowywanej pamięci. Agent nie jest skonfigurowany za pomocą narzędzia wyszukiwania pamięci lub nazwa magazynu pamięci jest niepoprawna. Upewnij się, że definicja agenta zawiera memory_search narzędzie i odwołuje się do poprawnej nazwy magazynu pamięci.

Treści powiązane

  • Last updated on