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

Importante

La memoria (anteprima) nel servizio agente Foundry e l'API di Memory Store (anteprima) vengono concesse in licenza all'utente come parte della sottoscrizione Azure e sono soggette ai termini applicabili alle "anteprime" nei Microsoft Product Terms e nel Microsoft Products and Services Data Protection Addendum, e i termini delle anteprime dei Servizi di Intelligenza Artificiale Generativa Microsoft nei Supplemental Terms of Use for Microsoft Azure Previews.

La memoria nel servizio Agent di Foundry è una soluzione gestita per la memoria 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.For conceptual information, see Memory in Foundry Agent Service.

Supporto per l'utilizzo

Capacità PYTHON SDK C# SDK JavaScript SDK REST API
Creare, aggiornare, elencare ed eliminare archivi di memoria ✔️ ✔️ ✔️ ✔️
Aggiornare e cercare ricordi ✔️ ✔️ ✔️ ✔️
Collegare la memoria a un agente 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. Accedere al portale Azure.

  2. Nel progetto:

    1. Nel riquadro sinistro selezionare Gestione delle 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. Selezionare Aggiungi assegnazione>di ruolo.
    3. Assegnare utente di Azure AI all'identità gestita del progetto.

Configurare l'ambiente

Installare i pacchetti necessari:

pip install "azure-ai-projects>=2.0.0" azure-identity

Installare i pacchetti necessari:

dotnet add package Azure.AI.Projects
dotnet add package Azure.AI.Projects.Agents
dotnet add package Azure.AI.Extensions.OpenAI
dotnet add package Azure.Identity

Installare i pacchetti necessari:

npm install @azure/ai-projects@2 @azure/identity

Impostare le variabili di ambiente per i nomi dell'endpoint del progetto e della distribuzione del modello:

export FOUNDRY_PROJECT_ENDPOINT="https://{your-ai-services-account}.services.ai.azure.com/api/projects/{project-name}"
export MEMORY_STORE_CHAT_MODEL_DEPLOYMENT_NAME="<chat-model-deployment-name>"
export MEMORY_STORE_EMBEDDING_MODEL_DEPLOYMENT_NAME="<embedding-model-deployment-name>"

Impostare le variabili di ambiente per l'endpoint del progetto, le distribuzioni di modelli, la versione dell'API e il token di accesso:

FOUNDRY_PROJECT_ENDPOINT="https://{your-ai-services-account}.services.ai.azure.com/api/projects/{project-name}"
MEMORY_STORE_CHAT_MODEL_DEPLOYMENT_NAME="<chat-model-deployment-name>" # For example, gpt-5.2
MEMORY_STORE_EMBEDDING_MODEL_DEPLOYMENT_NAME="<embedding-model-deployment-name>" # For example, text-embedding-3-small
API_VERSION="2025-11-15-preview"

# Get a short-lived access token using Azure CLI
ACCESS_TOKEN="$(az account get-access-token --resource https://ai.azure.com/ --query accessToken -o tsv)"

Comprendere l'ambito

Il scope parametro controlla la modalità di partizionamento della memoria. Ogni ambito nell'archivio di 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. L'approccio corretto dipende dalla modalità di accesso alla memoria.

Tramite lo strumento di ricerca della memoria

Quando si collega lo strumento di ricerca della memoria a un agente, impostare scope su {{$userId}} per abilitare l'isolamento della memoria per utente senza identificatori codificati manualmente. Il sistema risolve automaticamente l'identità dell'utente finale in ogni chiamata di risposta da una delle due origini:

  • x-memory-user-id intestazione della richiesta: se presente, il valore dell'intestazione viene usato come ID utente. Usarlo in scenari proxy o back-end in cui il servizio chiama l'API per conto di un utente finale.

  • Microsoft Entra token di autenticazione: Se l'intestazione non è impostata, il sistema esegue il fallback all'ID tenant del chiamante (TID) e all'ID oggetto (OID). Si tratta dell'impostazione predefinita negli scenari front-end in cui gli utenti eseguono l'autenticazione diretta con Microsoft Entra.

Se non è necessario l'isolamento per utente, usare invece un valore statico scope .

Tramite API di memoria di basso livello

Quando si chiamano direttamente le API di memoria , specificare scope in modo esplicito in ogni richiesta. È possibile passare un valore statico, ad esempio un identificatore univoco universale (UUID) o un altro identificatore stabile dal sistema. L'estrazione automatica delle identità non è supportata per queste operazioni.

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 crei un archivio di memoria, specifica il modello di chat e le implementazioni del modello di incorporamento 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
chat_model = os.environ["MEMORY_STORE_CHAT_MODEL_DEPLOYMENT_NAME"]
embedding_model = os.environ["MEMORY_STORE_EMBEDDING_MODEL_DEPLOYMENT_NAME"]

definition = MemoryStoreDefaultDefinition(
    chat_model=chat_model,
    embedding_model=embedding_model,
    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}")

using System;
using Azure.AI.Projects;
using Azure.AI.Projects.Memory;
using Azure.Identity;

#pragma warning disable AAIP001

var projectEndpoint = Environment.GetEnvironmentVariable(
    "FOUNDRY_PROJECT_ENDPOINT");
var chatModel = Environment.GetEnvironmentVariable(
    "MEMORY_STORE_CHAT_MODEL_DEPLOYMENT_NAME");
var embeddingModel = Environment.GetEnvironmentVariable(
    "MEMORY_STORE_EMBEDDING_MODEL_DEPLOYMENT_NAME");

AIProjectClient projectClient = new(
    new Uri(projectEndpoint),
    new DefaultAzureCredential());

var memoryStoreName = "my_memory_store";

// Specify memory store options
MemoryStoreDefaultDefinition memoryStoreDefinition = new(
    chatModel: chatModel,
    embeddingModel: embeddingModel
);
memoryStoreDefinition.Options = new(
    isUserProfileEnabled: true,
    isChatSummaryEnabled: true);
memoryStoreDefinition.Options.UserProfileDetails =
    "Avoid irrelevant or sensitive data, such as age, "
    + "financials, precise location, and credentials";

// Create memory store
MemoryStore memoryStore = projectClient.MemoryStores.CreateMemoryStore(
    name: memoryStoreName,
    definition: memoryStoreDefinition,
    description: "Memory store for customer support agent"
);

Console.WriteLine($"Created memory store: {memoryStore.Name}");

import { DefaultAzureCredential } from "@azure/identity";
import type {
  MemoryStoreDefaultDefinition,
  MemoryStoreDefaultOptions,
} from "@azure/ai-projects";
import { AIProjectClient } from "@azure/ai-projects";

const projectEndpoint =
  process.env["FOUNDRY_PROJECT_ENDPOINT"] ||
  "<project endpoint>";
const chatModelDeployment =
  process.env["MEMORY_STORE_CHAT_MODEL_DEPLOYMENT_NAME"] ||
  "<chat model deployment name>";
const embeddingModelDeployment =
  process.env["MEMORY_STORE_EMBEDDING_MODEL_DEPLOYMENT_NAME"] ||
  "<embedding model deployment name>";

const memoryStoreName = "my_memory_store";

const project = new AIProjectClient(
  projectEndpoint,
  new DefaultAzureCredential(),
);

const memoryOptions: MemoryStoreDefaultOptions = {
  user_profile_enabled: true,
  chat_summary_enabled: true,
  user_profile_details:
    "Avoid irrelevant or sensitive data, such as age, " +
    "financials, precise location, and credentials",
};

const definition: MemoryStoreDefaultDefinition = {
  kind: "default",
  chat_model: chatModelDeployment,
  embedding_model: embeddingModelDeployment,
  options: memoryOptions,
};

const memoryStore = await project.beta.memoryStores.create(
  memoryStoreName,
  definition,
  {
    description: "Memory store for customer support agent",
  },
);

console.log(
  `Created memory store: ${memoryStore.name} (${memoryStore.id})`,
);

curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my_memory_store",
    "description": "Memory store for customer support agent",
    "definition": {
      "kind": "default",
      "chat_model": "'"${MEMORY_STORE_CHAT_MODEL_DEPLOYMENT_NAME}"'",
      "embedding_model": "'"${MEMORY_STORE_EMBEDDING_MODEL_DEPLOYMENT_NAME}"'",
      "options": {
        "chat_summary_enabled": true,
        "user_profile_enabled": true,
        "user_profile_details": "Avoid irrelevant or sensitive data, such as age, financials, precise location, and credentials"
      }
    }
  }'

Suggerimento

  • I frammenti di codice Python, C# e TypeScript rimanenti si basano sul client e sulle variabili definite in Creare un archivio di memoria. Se esegui questi frammenti di codice in modo indipendente, includi il codice di importazione e di inizializzazione del client da questa sezione.
  • I frammenti di codice C# in questo articolo usano metodi sincroni. Per l'utilizzo asincrono, consultare gli esempi dello strumento di ricerca memoria e del negozio di memoria.

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 identificare i dettagli da estrarre, riepilogare e memorizzare 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}")

// Update memory store properties
MemoryStore updatedStore = projectClient.MemoryStores.UpdateMemoryStore(
    name: memoryStoreName,
    description: "Updated description"
);

Console.WriteLine($"Updated: {updatedStore.Description}");

const updatedStore = await project.beta.memoryStores.update(
  memoryStoreName,
  {
    description: "Updated description",
  },
);

console.log(`Updated: ${updatedStore.description}`);

MEMORY_STORE_NAME="my_memory_store"

curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/${MEMORY_STORE_NAME}?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated 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})")

// List all memory stores
foreach (MemoryStore store in projectClient.MemoryStores.GetMemoryStores())
{
    Console.WriteLine(
        $"Memory store: {store.Name} ({store.Description})");
}

const storeList = project.beta.memoryStores.list();

console.log("Listing all memory stores...");
for await (const store of storeList) {
  console.log(`  - Memory Store: ${store.name} (${store.id})`);
}

curl -X GET "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Usare i ricordi 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.

Suggerimento

Per limitare le memorie a un singolo utente finale, impostare scope su "{{$userId}}" nella definizione dello strumento e passare x-memory-user-id: <user-id> come intestazione per ogni richiesta di risposta. Il sistema risolve l'ambito in base all'identità dell'utente. Senza l'intestazione, l'ambito ricade sull'identità Microsoft Entra del chiamante (TID e OID). Per altre informazioni, vedere Comprendere l'ambito.

from azure.ai.projects.models import MemorySearchPreviewTool, PromptAgentDefinition

# Set scope to associate the memories with
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=os.environ["MEMORY_STORE_CHAT_MODEL_DEPLOYMENT_NAME"],
        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})")

using Azure.AI.Projects.Agents;
using Azure.AI.Extensions.OpenAI;
using OpenAI.Responses;

#pragma warning disable OPENAI001

// Set scope to associate the memories with
string scope = "user_123";

// Create a prompt agent with memory search tool
DeclarativeAgentDefinition agentDefinition = new(model: chatModel)
{
    Instructions = "You are a helpful assistant that answers "
        + "general questions",
};
agentDefinition.Tools.Add(new MemorySearchPreviewTool(
    memoryStoreName: memoryStore.Name,
    scope: scope)
{
    UpdateDelayInSecs = 1, // Wait 1 second of inactivity before updating memories
    // In a real application, set this to a higher value
    // like 300 (5 minutes, default)
});

ProjectsAgentVersion agent =
    projectClient.AgentAdministrationClient.CreateAgentVersion(
        agentName: "MyAgent",
        options: new(agentDefinition));

Console.WriteLine(
    $"Agent created (id: {agent.Id}, name: {agent.Name}, "
    + $"version: {agent.Version})");

// Set scope to associate the memories with
const scope = "user_123";

const agent = await project.agents.createVersion(
  "memory-search-agent",
  {
    kind: "prompt",
    model: chatModelDeployment,
    instructions:
      "You are a helpful assistant that retrieves relevant " +
      "information from the user's memory store to answer their questions.",
    tools: [
      {
        type: "memory_search_preview",
        memory_store_name: memoryStoreName,
        scope: scope,
        update_delay: 1,
      },
    ],
  },
);

console.log(
  `Created agent with memory search tool, agent ID: ${agent.id}, ` +
    `name: ${agent.name}, version: ${agent.version}`,
);

# The agents API uses api-version=v1, which differs from the memory store API version
curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/agents?api-version=v1" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MyAgent",
    "definition": {
        "kind": "prompt",
        "model": "gpt-5.2",
        "instructions": "You are a helpful assistant that answers general questions",
        "tools": [
            {
              "type": "memory_search_preview",
              "memory_store_name": "my_memory_store",
              "scope": "user_123",
              "update_delay": 1
            }
        ]
    }
}'

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 internamente chiama 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"}},
    # To scope memories to an end user, uncomment:
    # extra_headers={"x-memory-user-id": "<user-id>"},
)

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

using System.Threading;

#pragma warning disable OPENAI001

// Get a response client scoped to the agent
ProjectResponsesClient responseClient =
    projectClient.ProjectOpenAIClient
        .GetProjectResponsesClientForAgent(agent.Name);

// Create an agent response to initial user message
ResponseItem request = ResponseItem.CreateUserMessageItem(
    "I prefer dark roast coffee");
ResponseResult response = responseClient.CreateResponse([request]);
// To scope memories to an end user, uncomment:
// var options = new CreateResponseOptions();
// options.InputItems.Add(request);
// var requestOptions = new RequestOptions();
// requestOptions.AddHeader("x-memory-user-id", "<user-id>");
// ClientResult result = responseClient.CreateResponse(
//     BinaryContent.Create(options), requestOptions);
// ResponseResult response = ModelReaderWriter.Read<ResponseResult>(
//     result.GetRawResponse().Content);

Console.WriteLine($"Response output: {response.GetOutputText()}");

// After inactivity, memories are extracted and stored
Console.WriteLine("Waiting for memories to be stored...");
Thread.Sleep(65_000);

// Create a new response to demonstrate cross-session recall
ResponseItem newRequest = ResponseItem.CreateUserMessageItem(
    "Please order my usual coffee");
ResponseResult newResponse = responseClient.CreateResponse(
    [newRequest]);

Console.WriteLine(
    $"Response output: {newResponse.GetOutputText()}");

import { setTimeout } from "timers/promises";

const openaiClient = project.getOpenAIClient();

// Create a conversation with the agent with memory tool enabled
const conversation = await openaiClient.conversations.create();
console.log(`Created conversation (id: ${conversation.id})`);

// Create an agent response to initial user message
const response = await openaiClient.responses.create(
  {
    conversation: conversation.id,
    input: "I prefer dark roast coffee",
  },
  {
    body: {
      agent: { name: agent.name, type: "agent_reference" },
    },
    // To scope memories to an end user, uncomment:
    // headers: { "x-memory-user-id": "<user-id>" },
  },
);

console.log(`Response output: ${response.output_text}`);

// After inactivity, memories are extracted and stored
console.log("Waiting for memories to be stored...");
await setTimeout(65_000);

// Create a new conversation to demonstrate cross-session recall
const newConversation = await openaiClient.conversations.create();
console.log(`Created new conversation (id: ${newConversation.id})`);

// Create an agent response with stored memories
const newResponse = await openaiClient.responses.create(
  {
    conversation: newConversation.id,
    input: "Please order my usual coffee",
  },
  {
    body: {
      agent: { name: agent.name, type: "agent_reference" },
    },
  },
);

console.log(`Response output: ${newResponse.output_text}`);

curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/openai/v1/conversations" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{}'

# Copy the "id" field from the previous response
# To scope memories to an end user, add -H "x-memory-user-id: <user-id>" to the following request
curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/openai/v1/responses" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
      "input": "I prefer dark roast coffee",
      "conversation": "{conversation-id}",
      "agent_reference": {
        "type": "agent_reference",
        "name": "MyAgent"
      }
    }'

Usare memorie 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

Aggiungere ricordi fornendo contenuto di conversazione all'archivio 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 a esecuzione prolungata 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 contenuti da più turni di conversazione oppure aggiornare dopo ogni turno concatenando gli aggiornamenti usando l'ID dell'operazione di aggiornamento precedente.

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

#pragma warning disable OPENAI001

// Set scope to associate the memories with
string scope = "user_123";

MemoryUpdateOptions memoryOptions = new(scope)
{
    UpdateDelay = 0, // Trigger update immediately without waiting for inactivity
};
memoryOptions.Items.Add(ResponseItem.CreateUserMessageItem(
    "I prefer dark roast coffee and usually drink it "
    + "in the morning"));

// Wait for the update operation to complete
MemoryUpdateResult updateResult =
    projectClient.MemoryStores.WaitForMemoriesUpdate(
        memoryStoreName: memoryStore.Name,
        options: memoryOptions,
        pollingInterval: 500);

if (updateResult.Status == MemoryStoreUpdateStatus.Failed)
{
    throw new InvalidOperationException(
        updateResult.ErrorDetails);
}
Console.WriteLine(
    $"Updated with {updateResult.Details.MemoryOperations.Count} "
    + "memory operations");
foreach (var operation in updateResult.Details.MemoryOperations)
{
    Console.WriteLine(
        $"  - Operation: {operation.Kind}, "
        + $"Memory ID: {operation.MemoryItem.MemoryId}, "
        + $"Content: {operation.MemoryItem.Content}");
}

// Extend the previous update with another message
MemoryUpdateOptions newMemoryOptions = new(scope)
{
    PreviousUpdateId = updateResult.UpdateId,
    UpdateDelay = 0, // Trigger update immediately without waiting for inactivity
};
newMemoryOptions.Items.Add(ResponseItem.CreateUserMessageItem(
    "I also like cappuccinos in the afternoon"));

MemoryUpdateResult newUpdateResult =
    projectClient.MemoryStores.WaitForMemoriesUpdate(
        memoryStoreName: memoryStore.Name,
        options: newMemoryOptions,
        pollingInterval: 500);

if (newUpdateResult.Status == MemoryStoreUpdateStatus.Failed)
{
    throw new InvalidOperationException(
        newUpdateResult.ErrorDetails);
}
foreach (var operation in newUpdateResult.Details.MemoryOperations)
{
    Console.WriteLine(
        $"  - Operation: {operation.Kind}, "
        + $"Memory ID: {operation.MemoryItem.MemoryId}, "
        + $"Content: {operation.MemoryItem.Content}");
}

const scope = "user_123";

const userMessage: Record<string, unknown> = {
  type: "message",
  role: "user",
  content: [
    {
      type: "input_text",
      text: "I prefer dark roast coffee and usually drink it in the morning",
    },
  ],
};

console.log("\nSubmitting memory update request...");
const updatePoller = project.beta.memoryStores.updateMemories(
  memoryStoreName,
  scope,
  {
    items: [userMessage],
    updateDelayInSecs: 0,
  },
);

const updateResult = await updatePoller.pollUntilDone();
console.log(
  `Updated with ${updateResult.memory_operations.length} ` +
    `memory operation(s)`,
);
for (const operation of updateResult.memory_operations) {
  console.log(
    `  - Operation: ${operation.kind}, ` +
      `Memory ID: ${operation.memory_item.memory_id}, ` +
      `Content: ${operation.memory_item.content}`,
  );
}

// Extend the previous update with another message
const newMessage = {
  role: "user",
  content: "I also like cappuccinos in the afternoon",
  type: "message",
};

const newUpdatePoller = project.beta.memoryStores.updateMemories(
  memoryStoreName,
  scope,
  {
    items: [newMessage],
    updateDelayInSecs: 0,
  },
);

const newUpdateResult = await newUpdatePoller.pollUntilDone();
console.log(
  `Updated with ${newUpdateResult.memory_operations.length} ` +
    `memory operation(s)`,
);
for (const operation of newUpdateResult.memory_operations) {
  console.log(
    `  - Operation: ${operation.kind}, ` +
      `Memory ID: ${operation.memory_item.memory_id}, ` +
      `Content: ${operation.memory_item.content}`,
  );
}

curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/my_memory_store:update_memories?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user_123",
    "items": [
      {
        "type": "message",
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "I prefer dark roast coffee and usually drink it in the morning"
          }
        ]
      }
    ],
    "update_delay": 0
  }'

# Get add memory status by polling the update_id
# Use the "update_id" from previous response
UPDATE_ID=<your_update_id>
curl -X GET "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/my_memory_store/updates/${UPDATE_ID}?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

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.

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

#pragma warning disable OPENAI001

// Search memories by a query
MemorySearchOptions searchOptions = new(scope)
{
    Items =
    {
        ResponseItem.CreateUserMessageItem(
            "What are my coffee preferences?")
    },
    ResultOptions = new() { MaxMemories = 5 },
};

MemoryStoreSearchResponse searchResponse =
    projectClient.MemoryStores.SearchMemories(
        memoryStoreName: memoryStore.Name,
        options: searchOptions);

Console.WriteLine(
    $"Found {searchResponse.Memories.Count} memories");
foreach (MemorySearchItem item in searchResponse.Memories)
{
    Console.WriteLine(
        $"  - Content: {item.MemoryItem.Content}");
}

const queryMessage: Record<string, unknown> = {
  type: "message",
  role: "user",
  content: [
    { type: "input_text", text: "What are my coffee preferences?" },
  ],
};

console.log("\nSearching memories for stored preferences...");
const searchResponse =
  await project.beta.memoryStores.searchMemories(
    memoryStoreName,
    scope,
    {
      items: [queryMessage],
      options: { max_memories: 5 },
    },
  );

console.log(`Found ${searchResponse.memories.length} memory item(s)`);
for (const memory of searchResponse.memories) {
  console.log(
    `  - Memory ID: ${memory.memory_item.memory_id}, ` +
      `Content: ${memory.memory_item.content}`,
  );
}

curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/my_memory_store:search_memories?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user_123",
    "items": [
      {
        "type": "message",
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "What are my coffee preferences?"
          }
        ]
      }
    ],
    "options": {
      "max_memories": 5
    }
  }'

Richiamare memorie statiche 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")

// Delete memories for a specific scope
MemoryStoreDeleteScopeResponse deleteScopeResponse =
    projectClient.MemoryStores.DeleteScope(
        name: memoryStore.Name,
        scope: "user_123");

Console.WriteLine(
    $"Deleted scope: {deleteScopeResponse.Name}, "
    + $"success: {deleteScopeResponse.IsDeleted}");

console.log("\nDeleting memories for scope...");
await project.beta.memoryStores.deleteScope(memoryStoreName, scope);

curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/my_memory_store:delete_scope?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user_123"
  }'

Eliminare un archivio di memoria

Rimuovere l'intero archivio memoria e tutti i ricordi associati 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}")

// Delete the entire memory store
DeleteMemoryStoreResponse deleteResponse =
    projectClient.MemoryStores.DeleteMemoryStore(
        name: memoryStore.Name);

Console.WriteLine(
    $"Deleted memory store: {deleteResponse.Name}, "
    + $"success: {deleteResponse.IsDeleted}");

console.log("Deleting memory store...");
await project.beta.memoryStores.delete(memoryStoreName);

curl -X DELETE "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/my_memory_store?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

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.

  • Associare l'ambito all'utente finale: Quando si usa lo strumento di ricerca della memoria, impostare scope su {{$userId}} nella definizione dello strumento. Il sistema identifica l'identità utente dall'intestazione della richiesta x-memory-user-id, se presente. In caso contrario, ricorre al token di Microsoft Entra del chiamante ({tid}_{oid}).

  • 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 possono essere usati per risalire a un individuo.

  • 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 Causa Risoluzione
Le richieste hanno esito negativo con un errore di autenticazione o autorizzazione. L'identità o l'identità gestita del progetto non ha i 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 esegui il mapping dell'ambito agli utenti, usa 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_preview strumento e faccia riferimento al nome corretto dell'archivio di memoria.

Contenuto correlato

  • Last updated on