Condividi tramite

Creare e usare la memoria nel servizio agente Foundry (anteprima)

Importante

La memoria (anteprima) nel servizio Foundry Agent e l'API Memory Store (anteprima) vengono concesse in licenza all'utente come parte della sottoscrizione di Azure e sono soggette alle condizioni applicabili alle "anteprime" nei Termini del prodotto Microsoft e nel Componente aggiuntivo per la protezione dei dati dei prodotti e dei servizi Microsoft, nonché alle condizioni per le anteprime dei servizi di intelligenza artificiale generativa di Microsoft nelle Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.

La memoria nel servizio agente Foundry è una soluzione di memoria gestita a lungo termine. Consente la continuità dell'agente tra sessioni, dispositivi e flussi di lavoro. Creando e gestendo archivi di memoria, è possibile creare agenti che mantengono le preferenze utente, mantengono la cronologia delle conversazioni e offrono esperienze personalizzate.

Gli archivi di memoria fungono da risorsa di archiviazione permanente, definendo quali tipi di informazioni sono rilevanti per ogni agente. È possibile controllare l'accesso usando il parametro , che segmenta la scope memoria tra gli utenti per garantire esperienze sicure e isolate.

Questo articolo illustra come creare, gestire e usare archivi di memoria. Per informazioni concettuali, vedere Memory in Foundry Agent Service.

Supporto per l'utilizzo

Capability Python SDK REST API
Creare, aggiornare, elencare ed eliminare archivi di memoria ✔️ ✔️
Aggiornare e cercare ricordi ✔️ ✔️
Collegare la memoria a un assistente prompt ✔️ ✔️

Prerequisiti

Autorizzazione e autorizzazioni

È consigliabile controllare l'accesso in base al ruolo per le distribuzioni di produzione. Se i ruoli non sono fattibili, ignorare questa sezione e usare invece l'autenticazione basata su chiave.

Per configurare l'accesso in base al ruolo:

  1. Accedi al portale di Azure.
  2. Nel progetto:
    1. Nel riquadro sinistro selezionare Gestione risorse>Identità.
    2. Usare l'interruttore per abilitare un'identità gestita assegnata dal sistema.
  3. Nella risorsa che contiene il progetto:
    1. Nel riquadro sinistro selezionare Controllo di accesso (IAM).
    2. Seleziona Aggiungi>Aggiungi assegnazione ruolo.
    3. Assegna Azure AI User all'identità gestita del tuo progetto.

Impostare l'endpoint del progetto

Per gli esempi python in questo articolo, impostare una variabile di ambiente per l'endpoint del progetto:

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

Comprendere l'ambito

Il scope parametro controlla la modalità di partizionamento della memoria. Ogni ambito nell'archivio memoria mantiene una raccolta isolata di elementi di memoria. Ad esempio, se si crea un agente di supporto clienti con memoria, ogni cliente deve avere la propria memoria individuale.

Gli sviluppatori scelgono la chiave usata per archiviare e recuperare gli elementi di memoria. È possibile passare un valore statico, ad esempio un identificatore univoco universale (UUID) o un altro identificatore stabile dal sistema.

In alternativa, quando si specifica {{$userId}} come ambito, il sistema estrae automaticamente l'ID tenant (TID) e l'ID oggetto (OID) dall'intestazione di autenticazione della richiesta. Questo approccio offre a ogni utente autenticato la propria partizione di memoria isolata, eliminando la necessità di gestire manualmente gli identificatori.

Creare un archivio di memoria

Creare un archivio memoria dedicato per ogni agente per stabilire limiti chiari per l'accesso alla memoria e l'ottimizzazione. Quando si crea un archivio di memoria, indicare il modello di chat e le distribuzioni di modelli di embedding che elaborano il contenuto della memoria.

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

Personalizzare la memoria

Personalizzare le informazioni archiviate dall'agente per mantenere la memoria efficiente, pertinente e rispetto della privacy. Usare il user_profile_details parametro per specificare i tipi di dati critici per la funzione dell'agente.

Ad esempio, impostare user_profile_details come priorità "preferenza vettore di volo e restrizioni dietetiche" per un agente di viaggio. Questo approccio incentrato consente al sistema di memoria di individuare i dettagli da estrarre, riepilogare e archiviare nella memoria a lungo termine.

È anche possibile usare questo parametro per escludere determinati tipi di dati, mantenendo la memoria snella e conforme ai requisiti di privacy. Ad esempio, impostare su user_profile_details "evitare dati irrilevanti o sensibili, ad esempio età, finanziari, posizione precisa e credenziali".

Aggiornare un archivio di memoria

Aggiornare le proprietà dell'archivio memoria, ad esempio description o metadata, per gestire meglio gli archivi di memoria.

# 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}")

Elencare gli archivi di memoria

Recuperare un elenco di archivi di memoria nel progetto per gestire e monitorare l'infrastruttura di memoria.

# 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})")

Usare le memorie tramite uno strumento agente

Dopo aver creato un archivio memoria, è possibile collegare lo strumento di ricerca della memoria a un agente prompt. Questo strumento consente all'agente di leggere e scrivere nell'archivio memoria durante le conversazioni. Configurare lo strumento con il appropriato scope e update_delay per controllare come e quando vengono aggiornati i ricordi.

# 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})")

Creare una conversazione

È ora possibile creare conversazioni e richiedere risposte dell'agente. All'inizio di ogni conversazione, i ricordi statici vengono inseriti in modo che l'agente abbia un contesto immediato e permanente. I ricordi contestuali vengono recuperati per turno in base ai messaggi più recenti per informare ogni risposta.

Dopo ogni risposta dell'agente, il servizio chiama internamente update_memories. Tuttavia, le scritture effettive nella memoria a lungo termine vengono annullate dall'impostazione update_delay . L'aggiornamento è pianificato e viene completato solo dopo il periodo di inattività configurato.

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

Utilizzare memoria tramite API

È possibile interagire con un archivio di memoria direttamente usando le API dell'archivio di memoria. Per iniziare, aggiungere memorie dal contenuto della conversazione all'archivio memoria e quindi cercare memorie pertinenti per fornire contesto per le interazioni con l'agente.

Aggiungere ricordi a un archivio memoria

Aggiungi ricordi fornendo il contenuto della conversazione allo store di memoria. Il sistema pre-elabora e post-elabora i dati, inclusi l'estrazione e il consolidamento della memoria, per ottimizzare la memoria dell'agente. Questa operazione di lunga durata potrebbe richiedere circa un minuto.

Decidere come segmentare la memoria tra gli utenti specificando il scope parametro . È possibile definire l'ambito della memoria a un utente finale specifico, a un team o a un altro identificatore.

È possibile aggiornare un archivio di memoria con il contenuto di più turni di conversazione, oppure eseguire un aggiornamento dopo ogni turno concatenando gli aggiornamenti utilizzando l'ID dell'operazione di aggiornamento precedente.

# 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}"
    )

Cercare ricordi in un archivio memoria

Cercare ricordi per recuperare il contesto pertinente per le interazioni con l'agente. Specificare il nome e l'ambito dell'archivio di memoria per restringere la ricerca.

# 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}")

Recupera ricordi statici o contestuali

Spesso, i ricordi del profilo utente non possono essere recuperati in base alla somiglianza semantica con il messaggio di un utente. È consigliabile inserire memorie statiche all'inizio di ogni conversazione e usare memorie contestuali per generare ogni risposta dell'agente.

  • Per recuperare memorie statiche, chiamare search_memories con un scope ma senza items o previous_search_id. In questo modo vengono restituiti i ricordi del profilo utente associati all'ambito.

  • Per recuperare i ricordi contestuali, chiamare search_memories con items impostato sui messaggi più recenti. Questo può restituire sia i ricordi di riepilogo del profilo utente che i ricordi di riepilogo della chat più rilevanti per gli elementi specificati.

Per altre informazioni sui ricordi di riepilogo del profilo utente e della chat, vedere Tipi di memoria.

Eliminare i ricordi

Avviso

Prima di eliminare un archivio di memoria, prendere in considerazione l'impatto sugli agenti dipendenti. Gli agenti con archivi di memoria collegati potrebbero perdere l'accesso al contesto cronologico.

I ricordi sono organizzati in base all'ambito all'interno di un archivio di memoria. È possibile eliminare i ricordi per un ambito specifico per rimuovere i dati specifici dell'utente oppure eliminare l'intero archivio memoria per rimuovere tutti i ricordi in tutti gli ambiti.

Eliminare i ricordi in base all'ambito

Rimuovere tutti i ricordi associati a un determinato ambito utente o gruppo mantenendo al tempo stesso la struttura dell'archivio memoria. Usare questa operazione per gestire le richieste di eliminazione dei dati utente o reimpostare la memoria per utenti specifici.

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

Eliminare un archivio di memoria

Rimuovere l'intera memoria e tutte le memorie associate in tutti gli ambiti. questa operazione è irreversibile.

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

Procedure consigliate

  • Implementare i controlli di accesso per utente: Evitare di concedere agli agenti l'accesso ai ricordi condivisi tra tutti gli utenti. Usare la scope proprietà per partizionare l'archivio di memoria in base all'utente. Quando si condivide scope tra gli utenti, usare user_profile_details per indicare al sistema di memoria di non archiviare le informazioni personali.

  • Eseguire il mapping dell'ambito a un utente autenticato: Quando si specifica l'ambito nello strumento di ricerca della memoria, impostare scope={{$userId}} per eseguire il mapping all'utente dal token di autenticazione ({tid}_{oid}). Ciò garantisce che le ricerche in memoria siano destinate automaticamente all'utente corretto.

  • Ridurre al minimo e proteggere i dati sensibili: Archiviare solo ciò che è necessario per il caso d'uso. Se è necessario archiviare dati sensibili, ad esempio dati personali, dati sanitari o input aziendali riservati, oscurare o rimuovere altri contenuti che possano essere utilizzati per risalire a una persona.

  • Supporto della privacy e della conformità: Fornire agli utenti la trasparenza, incluse le opzioni per accedere ed eliminare i dati. Registrare tutte le eliminazioni in un audit trail a prova di manomissione. Assicurarsi che il sistema rispetti i requisiti di conformità locali e gli standard normativi.

  • Segmentare i dati e isolare la memoria: Nei sistemi multi-agente segmentare la memoria in modo logico e operativo. Consentire ai clienti di definire, isolare, ispezionare ed eliminare la propria impronta di memoria.

  • Monitorare l'utilizzo della memoria: Tenere traccia dell'utilizzo dei token e delle operazioni di memoria per comprendere i costi e ottimizzare le prestazioni.

Risoluzione dei problemi

Problema Motivo Risoluzione
Le richieste hanno esito negativo con un errore di autenticazione o autorizzazione. L'identità o l'identità gestita del progetto non dispone dei ruoli necessari. Verificare i ruoli in Autorizzazione e autorizzazioni. Per le chiamate REST, generare un nuovo token di accesso e riprovare.
I ricordi non vengono visualizzati dopo una conversazione. Gli aggiornamenti della memoria vengono annullati o ancora in elaborazione. Aumentare il tempo di attesa o chiamare l'API di aggiornamento con update_delay impostato su 0 per attivare immediatamente l'elaborazione.
La ricerca di memoria non restituisce risultati. Il scope valore non corrisponde all'ambito usato durante l'archiviazione delle memorie. Usare lo stesso ambito per l'aggiornamento e la ricerca. Se si mappa l'ambito agli utenti, utilizzare un identificatore utente stabile.
La risposta dell'agente non usa la memoria archiviata. L'agente non è configurato con lo strumento di ricerca della memoria o il nome dell'archivio memoria non è corretto. Verificare che la definizione dell'agente includa lo memory_search strumento e faccia riferimento al nome corretto dell'archivio di memoria.

Contenuti correlati

  • Last updated on