Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Important
La Mémoire (préversion) dans le service Agent Foundry et l’API Mémoire Store (préversion) est concédée sous licence dans le cadre de votre abonnement Azure et est soumise à des conditions applicables aux « préversions » dans les conditions d’utilisation du produit Microsoft et à l’Addenda relatif à la protection des données des produits et services Microsoft, ainsi qu'aux conditions d'utilisation des préversions des services d'IA générative de Microsoft mentionnées dans les Conditions d'utilisation supplémentaires pour les préversions Microsoft Azure.
La mémoire dans le service de l'agent Foundry est une solution de mémoire gérée à long terme. Il permet la continuité de l’agent entre les sessions, les appareils et les flux de travail. En créant et en gérant des magasins de mémoire, vous pouvez créer des agents qui conservent les préférences utilisateur, conservent l’historique des conversations et fournissent des expériences personnalisées.
Les magasins de mémoire agissent en tant que stockage persistant, définissant quels types d’informations sont pertinents pour chaque agent. Vous contrôlez l’accès à l’aide du paramètre, qui segmente la scope mémoire entre les utilisateurs pour garantir des expériences sécurisées et isolées.
Cet article explique comment créer, gérer et utiliser des magasins de mémoire. Pour plus d’informations conceptuelles, consultez Memory in Foundry Agent Service.
Support d'utilisation
| Capacité | SDK Python | C# SDK | Kit de développement logiciel (SDK) JavaScript | REST API |
|---|---|---|---|---|
| Créer, mettre à jour, répertorier et supprimer des magasins de mémoire | ✔️ | ✔️ | ✔️ | ✔️ |
| Mettre à jour et rechercher des souvenirs | ✔️ | ✔️ | ✔️ | ✔️ |
| Associer de la mémoire à un agent de prompt | ✔️ | ✔️ | ✔️ | ✔️ |
Conditions préalables
- Un abonnement Azure. Créez-en un gratuitement.
- Un projet Microsoft Foundry avec autorisation et permissions configurées.
- Un déploiement de modèle de conversation, tel que
gpt-5.2, dans votre projet. - Un déploiement de modèle d'intégration dans votre projet, tel que
text-embedding-3-small. - Environnement local configuré avec les packages et variables d’environnement requis.
Autorisation et permissions
Nous vous recommandons de contrôler l’accès en fonction du rôle pour les déploiements de production. Si les rôles ne sont pas réalisables, ignorez cette section et utilisez plutôt l’authentification basée sur des clés.
Pour configurer l’accès en fonction du rôle :
Connectez-vous au portail Azure.
Sur votre projet :
- Dans le volet gauche, sélectionnez Resource Management>Identity.
- Utilisez le bouton bascule pour activer une identité managée affectée par le système.
Sur la ressource qui contient votre projet :
- Dans le volet gauche, sélectionnez Contrôle d’accès (IAM) .
- Sélectionnez Ajouter une>attribution de rôle.
- Affectez Utilisateur Azure AI à l’identité managée de votre projet.
Configurer votre environnement
Installez les packages requis :
pip install "azure-ai-projects>=2.0.0" azure-identity
Installez les packages requis :
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
Installez les packages requis :
npm install @azure/ai-projects@2 @azure/identity
Définissez des variables d’environnement pour votre point de terminaison de projet et les noms de déploiement de modèle :
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>"
Définissez des variables d’environnement pour votre point de terminaison de projet, les déploiements de modèles, la version de l’API et le jeton d’accès :
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)"
Comprendre l’étendue
Le scope paramètre contrôle la façon dont la mémoire est partitionnée. Chaque portée du magasin de mémoire conserve une collection isolée d’éléments de mémoire. Par exemple, si vous créez un agent de support client avec de la mémoire, chaque client doit avoir sa propre mémoire individuelle.
En tant que développeur, vous choisissez la clé utilisée pour stocker et récupérer des éléments de mémoire. La bonne approche dépend de la façon dont vous accédez à la mémoire.
À l'aide de l'outil de recherche en mémoire
Lorsque vous attachez l’outil de recherche de mémoire à un agent, définissez scope à {{$userId}} pour activer l’isolation de la mémoire par utilisateur sans avoir à coder en dur des identifiants. Le système résout automatiquement l’identité de l’utilisateur final sur chaque appel de réponse à partir d’une des deux sources :
x-memory-user-iden-tête de requête : s’il est présent, la valeur d’en-tête est utilisée comme ID utilisateur. Utilisez-le dans les scénarios proxy ou back-end dans lesquels votre service appelle l’API pour le compte d’un utilisateur final.Jeton d'authentification Microsoft Entra : Si l'en-tête n'est pas configuré, le système revient à l'ID du client de l'appelant (TID) et à l'ID d'objet (OID). Il s’agit de la valeur par défaut dans les scénarios frontaux où les utilisateurs s’authentifient directement avec Microsoft Entra.
Si vous n’avez pas besoin d’isolation par utilisateur, utilisez plutôt une valeur statique scope .
Via des API de mémoire de bas niveau
Lorsque vous appelez directement des API mémoire , spécifiez scope explicitement dans chaque requête. Vous pouvez passer une valeur statique, telle qu’un identificateur universel unique (UUID) ou un autre identificateur stable de votre système. L’extraction automatique d’identité n’est pas prise en charge pour ces opérations.
Créer un magasin de mémoire
Créez un magasin de mémoire dédié pour chaque agent afin d’établir des limites claires pour l’accès à la mémoire et l’optimisation. Lorsque vous créez un magasin de mémoire, spécifiez les déploiements du modèle de conversation et du modèle d'intégration qui traitent votre contenu mémoire.
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"
}
}
}'
Conseil
- Les extraits de code Python, C# et TypeScript restants s’appuient sur le client et les variables définis dans Créer un magasin de mémoire. Si vous exécutez ces extraits de code indépendamment, incluez le code d’initialisation de l’importation et du client à partir de cette section.
- Les extraits de code C# de cet article utilisent des méthodes synchrones. Pour une utilisation asynchrone, consultez les exemples de l’outil de recherche de mémoire et du stockage de mémoire.
Personnaliser la mémoire
Personnalisez les informations que l’agent stocke pour maintenir l’efficacité, la pertinence et le respect de la confidentialité de la mémoire. Utilisez le user_profile_details paramètre pour spécifier les types de données critiques pour la fonction de l’agent.
Par exemple, définissez user_profile_details la priorité « préférence des transporteurs d’avion et restrictions alimentaires » pour un agent de voyage. Cette approche axée aide le système de mémoire à savoir quels détails extraire, résumer et stocker dans la mémoire à long terme.
Vous pouvez également utiliser ce paramètre pour exclure certains types de données, en conservant la mémoire maigre et conforme aux exigences de confidentialité. Par exemple, définissez user_profile_details sur « éviter les données non pertinentes ou sensibles, telles que l’âge, les finances, l’emplacement précis et les informations d’identification ».
Mettre à jour un magasin de mémoire
Mettez à jour les propriétés du magasin de mémoire, telles que description ou metadata, pour mieux gérer les magasins de mémoire.
# 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"
}'
Répertorier les stockages de mémoire
Récupérez la liste des magasins de mémoire dans votre projet pour gérer et surveiller votre infrastructure de mémoire.
# 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}"
Utiliser des mémoires via un outil d’agent
Après avoir créé un magasin de mémoire, vous pouvez attacher l’outil de recherche mémoire à un agent de suggestion. Cet outil permet à l’agent de lire et d’écrire dans votre stockage de mémoire pendant les conversations. Configurez l'outil avec le(s) scope et update_delay approprié(s) pour contrôler comment et quand les mémoires sont mises à jour.
Conseil
Pour associer les mémoires à un utilisateur final individuel, définissez scope sur "{{$userId}}" dans la définition de l'outil et transmettez x-memory-user-id: <user-id> comme en-tête à chaque appel de réponse. Le système résout l’étendue de l’identité de cet utilisateur. Sans l'en-tête, la portée revient à l'identité Microsoft Entra de l'appelant (TID et OID). Pour plus d’informations, consultez Comprendre l’étendue.
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
}
]
}
}'
Créer une conversation
Vous pouvez maintenant créer des conversations et demander des réponses de l’agent. Au début de chaque conversation, les mémoires statiques sont injectées afin que l’agent ait un contexte immédiat et persistant. Les mémoires contextuelles sont récupérées par tour en fonction des derniers messages pour informer chaque réponse.
Après chaque réponse de l'agent, le service appelle en interne update_memories. Toutefois, les écritures réelles dans la mémoire à long terme sont débouncées par le update_delay paramètre. La mise à jour est planifiée et se termine uniquement après la période d’inactivité configurée.
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"
}
}'
Utiliser des souvenirs via des API
Vous pouvez interagir avec un magasin de mémoire directement à l’aide des API du magasin de mémoire. Commencez par ajouter des souvenirs du contenu de conversation au magasin de mémoire, puis recherchez des souvenirs pertinents pour fournir un contexte pour les interactions de l’agent.
Ajouter des mémoires à un stockage de mémoire
Ajoutez des souvenirs en fournissant du contenu de conversation au magasin de mémoire. Le système prétrait et postprocesse les données, y compris l’extraction et la consolidation de la mémoire, pour optimiser la mémoire de l’agent. Cette opération longue peut prendre environ une minute.
Déterminez comment segmenter la mémoire entre les utilisateurs en spécifiant le scope paramètre. Vous pouvez étendre la mémoire à un utilisateur final spécifique, à une équipe ou à un autre identificateur.
Vous pouvez mettre à jour une boutique de mémoire avec du contenu à partir de plusieurs tours de conversation ou mettre à jour après chaque tour et chaîner les mises à jour en utilisant l'ID de l'opération de mise à jour précédente.
# 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}"
Rechercher des souvenirs dans un magasin de mémoire
Recherchez des souvenirs pour récupérer le contexte pertinent pour les interactions de l’agent. Spécifiez le nom et l’étendue du magasin de mémoire pour affiner la recherche.
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
}
}'
Récupérer des mémoires statiques ou contextuelles
Souvent, les mémoires de profil utilisateur ne peuvent pas être récupérées en fonction de la similarité sémantique du message d’un utilisateur. Nous vous recommandons d’injecter des mémoires statiques au début de chaque conversation et d’utiliser des souvenirs contextuels pour générer chaque réponse de l’agent.
Pour récupérer des mémoires statiques, appelez
search_memoriesavec unscopemais sansitemsouprevious_search_id. Cela retourne les données de profil utilisateur associées à la portée.Pour récupérer des souvenirs contextuels, appelez
search_memoriesavecitemsla valeur définie sur les derniers messages. Cela peut retourner à la fois les données de profil utilisateur et les résumés de conversation les plus pertinents pour les éléments fournis.
Pour plus d’informations sur le profil utilisateur et les souvenirs de synthèse de conversation, consultez Types de mémoire.
Supprimer des souvenirs
Avertissement
Avant de supprimer un magasin de mémoire, tenez compte de l’impact sur les agents dépendants. Les agents disposant d'espaces de stockage mémoire peuvent perdre l’accès au contexte historique.
Les mémoires sont organisées par étendue dans un stockage mémoire. Vous pouvez supprimer des mémoires pour une étendue spécifique pour supprimer des données spécifiques à l’utilisateur, ou supprimer l’intégralité du magasin de mémoire pour supprimer tous les souvenirs dans toutes les étendues.
Supprimer des mémoires par portée
Supprimez toutes les mémoires associées à une portée utilisateur ou groupe spécifique tout en préservant la structure du stockage de mémoire. Utilisez cette opération pour gérer les demandes de suppression de données utilisateur ou réinitialiser la mémoire pour des utilisateurs spécifiques.
# 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"
}'
Supprimer un magasin de mémoire
Supprimez l'intégralité du magasin de mémoire et toutes les mémoires associées dans tous les périmètres. Cette opération est irréversible.
# 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}"
Meilleures pratiques
Implémentez des contrôles d’accès par utilisateur : Évitez d’accorder aux agents l’accès aux souvenirs partagés entre tous les utilisateurs. Utilisez la
scopepropriété pour partitionner le magasin de mémoire par utilisateur. Lorsque vous partagezscopeentre les utilisateurs, utilisez cette optionuser_profile_detailspour indiquer au système de mémoire de ne pas stocker les informations personnelles.Mapper la portée à l’utilisateur final : Lorsque vous utilisez l’outil de recherche de mémoire, définissez
scopesur{{$userId}}dans la définition de l’outil. Le système résout l’identité de l’utilisateur à partir de l’en-têtex-memory-user-idde requête, le cas échéant. Sinon, il revient au jeton Microsoft Entra de l'appelant ({tid}_{oid}).Réduisez et protégez les données sensibles : Stockez uniquement ce qui est nécessaire pour votre cas d’usage. Si vous devez stocker des données sensibles, telles que des données personnelles, des données d’intégrité ou des entrées commerciales confidentielles, réactez ou supprimez d’autres contenus qui pourraient être utilisés pour revenir à un individu.
Prise en charge de la confidentialité et de la conformité : Fournir aux utilisateurs une transparence, y compris des options d’accès et de suppression de leurs données. Enregistrez toutes les suppressions dans une piste d’audit infalsifiable. Assurez-vous que le système respecte les exigences de conformité locales et les normes réglementaires.
Segmenter les données et isoler la mémoire : Dans les systèmes multi-agents, segmentez la mémoire de manière logique et opérationnelle. Permettre aux clients de définir, d’isoler, d’inspecter et de supprimer leur propre empreinte mémoire.
Surveiller l’utilisation de la mémoire : Suivez l’utilisation des jetons et les opérations de mémoire pour comprendre les coûts et optimiser les performances.
Dépannage
| Problème | Cause | Résolution |
|---|---|---|
| Les demandes échouent avec une erreur d’authentification ou d’autorisation. | Votre identité ou l’identité managée du projet n’a pas les rôles requis. | Vérifiez les rôles dans l'autorisation et les permissions. Pour les appels REST, générez un nouveau jeton d’accès et réessayez. |
| Les souvenirs n’apparaissent pas après une conversation. | Les mises à jour de mémoire sont débouncées ou encore traitées. | Augmentez le temps d’attente ou appelez l’API de mise à jour avec update_delay défini sur 0 pour déclencher le traitement immédiatement. |
| La recherche en mémoire ne retourne aucun résultat. | La scope valeur ne correspond pas à l’étendue utilisée lors du stockage des mémoires. |
Utilisez la même étendue pour la mise à jour et la recherche. Si vous mappez l’étendue aux utilisateurs, utilisez un identificateur d’utilisateur stable. |
| La réponse de l’agent n’utilise pas de mémoire stockée. | L’agent n’est pas configuré avec l’outil de recherche de mémoire, ou le nom du magasin de mémoire est incorrect. | Vérifiez que la définition de l’agent inclut l’outil memory_search_preview et fait référence au nom correct de l'espace de stockage de mémoire. |
Contenu connexe
- Azure extensions AI pour OpenAI : exemple d’outil de recherche de mémoire
- Bibliothèque client Azure AI Projects pour .NET : exemple de stockage de mémoire
- Informations de référence sur l’API REST du magasin de mémoire
- Mémoire dans le service de l’agent Foundry
- Quotas et limites du service de l’agent Foundry
- Builder un agent avec Microsoft Foundry