Partager via

Créer et utiliser de la mémoire dans Service de l’agent Foundry (version préliminaire)

Important

La mémoire (préversion) dans le service d’Agent Foundry et l’API Store de la Mémoire (préversion) sont concédées sous licence dans le cadre de votre abonnement Azure et sont soumises à des conditions applicables aux « préversions » dans les Conditions des Produits Microsoft et l’Addendum sur la protection des données des Produits et Services Microsoft, ainsi que les conditions supplémentaires d'utilisation pour les Préversions de Microsoft Azure dans les Conditions d'utilisation supplémentaires pour les Préversions de Microsoft Azure.

La mémoire dans Service de l’agent Foundry est une solution de mémoire managé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.

Assistance à l'utilisation

Capacité Kit de développement logiciel (SDK) Python API REST
Créer, mettre à jour, répertorier et supprimer des magasins de mémoire ✔️ ✔️
Mettre à jour et rechercher des souvenirs ✔️ ✔️
Attacher de la mémoire à un agent d'aide ✔️ ✔️

Prerequisites

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 :

  1. Connectez-vous au portail Azure.
  2. Sur votre projet :
    1. Dans le volet gauche, sélectionnez Resource Management>Identity.
    2. Utilisez le bouton bascule pour activer une identité managée affectée par le système.
  3. Sur la ressource qui contient votre projet :
    1. Dans le volet gauche, sélectionnez Contrôle d’accès (IAM) .
    2. Sélectionnez Ajouter>Ajouter une attribution de rôle.
    3. Affectez l’utilisateur Azure AI à l’identité managée de votre projet.

Définir le point de terminaison du projet

Pour les exemples Python de cet article, définissez une variable d’environnement pour votre point de terminaison de projet :

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

Comprendre la portée

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. Vous pouvez passer une valeur statique, telle qu’un identificateur universel unique (UUID) ou un autre identificateur stable de votre système.

Sinon, lorsque vous spécifiez {{$userId}} comme étendue, le système extrait automatiquement l’ID de locataire (TID) et l’ID d’objet (OID) de l’en-tête d’authentification de la demande. Cette approche donne à chaque utilisateur authentifié sa propre partition de mémoire isolée, ce qui élimine la nécessité de gérer manuellement les identificateurs.

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 le modèle de conversation et incorporez les déploiements de modèles 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
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}")

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

Lister les espaces 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})")

Utiliser des mémoires au moyen d’un outil d’agent

Après avoir créé un magasin de mémoire, vous pouvez attacher l’outil de recherche de mémoire à un agent de prompt. Cet outil permet à l’agent de lire et d’écrire dans votre stockage de mémoire pendant les conversations. Configurez l’outil avec les paramètres appropriés scope pour contrôler comment et update_delay quand les mémoires sont mises à jour.

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

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 à chaque itération en fonction des derniers messages afin d'orienter 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"}},
)

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

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 un magasin de mémoire avec du contenu provenant de plusieurs tours de conversation, ou mettre à jour après chaque tour et enchaîner les mises à jour en utilisant l’ID de l’opération de mise à jour précédente.

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

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.

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

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_memories avec un scope mais sans items ou previous_search_id. Cela retourne les données de profil utilisateur associées au périmètre.

  • Pour récupérer des mémoires contextuelles, appelez search_memories en définissant items sur les derniers messages. Cela peut renvoyer à la fois les souvenirs de profil utilisateur et les résumés de conversation les plus pertinents par rapport aux éléments spécifiés.

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 avec des unités de mémoire attachées peuvent perdre l’accès au contexte antérieur.

Les mémoires sont organisées par étendue dans un espace de stockage de 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 données associées à un domaine d'utilisateur ou de groupe spécifique tout en préservant la structure de l'espace 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")

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 contextes. Cette action 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}")

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 propriété scope pour partitionner le magasin de mémoire en fonction de l'utilisateur. Lorsque vous partagez scope entre les utilisateurs, utilisez cette option user_profile_details pour indiquer au système de mémoire de ne pas stocker les informations personnelles.

  • Associer l’étendue à un utilisateur authentifié : Lorsque vous spécifiez l’étendue dans l’outil de recherche de mémoire, définissez scope={{$userId}} la valeur pour qu'elle soit associée à l'utilisateur à partir du jeton d’authentification ({tid}_{oid}). Cela garantit que les recherches de mémoire ciblent automatiquement l’utilisateur approprié.

  • 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.

Résolution des problèmes

Problème La 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 en définissant update_delay 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 et fait référence au nom correct du magasin de mémoire.

Contenu connexe

  • Last updated on