Partage 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 de l’agent Foundry et l’API Memory Store (préversion) vous sont concédées sous licence dans le cadre de votre abonnement Azure et sont soumises aux conditions applicables aux « préversions » dans les Microsoft Product Terms et le Microsoft Products and Services Data Protection Addendum, ainsi qu'aux conditions de préversion des services Microsoft Generative AI dans les Conditions supplémentaires d'utilisation 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 mémoires agissent comme des stockages persistants, définissant les types d'informations qui sont pertinents pour chaque agent. Vous contrôlez access à l’aide du paramètre scope, qui segmente la 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 Kit de développement logiciel (SDK) JavaScript API REST
Créer, mettre à jour, répertorier et supprimer des magasins de mémoire ✔️ ✔️ ✔️
Mettre à jour et rechercher des souvenirs ✔️ ✔️ ✔️
Associer une mémoire à un agent de prompt ✔️ ✔️ ✔️

Prerequisites

Autorisation et permissions

Nous vous recommandons le contrôle d'accès basé sur les rôles 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 les accès basés sur les rôles :

  1. Connectez-vous au Azure portal.
  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 project :
    1. Dans le volet gauche, sélectionnez Access control (IAM).
    2. Sélectionnez Ajouter>Ajouter une attribution de rôle.
    3. Affectez Utilisateur IA Azure à l’identité managée de votre projet.

Définir des variables d’environnement

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 la portée

Le scope paramètre contrôle la façon dont la mémoire est partitionnée. Chaque étendue 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 espace 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
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}")

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 / Astuce

Les extraits de code dans les sections restantes de cet article 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 de manière indépendante, incluez le code d'importation et d'initialisation du client à partir de cette section.

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

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

Lister les espaces mémoire

Récupérez une 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})")

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

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

// Set scope to associate the memories with
// You can also use "{{$userId}}" to take the TID and OID of the request authentication header
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}`,
);

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

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

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

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

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

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_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 ayant des éléments de mémoire associés peuvent perdre l'accès au contexte historique.

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 étendue

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

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

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 de donner aux agents accès aux mémoires partagées 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.

  • Supportez la confidentialité et la conformité : Fournir aux utilisateurs une transparence, y compris les options de access et de suppression de leurs données. Consignez toutes les suppressions dans un journal 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 de 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 access et réessayez.
Les souvenirs n’apparaissent pas après une conversation. Les mises à jour de mémoire sont débouncées ou encore en cours de traitement. 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_preview et fait référence au nom correct du magasin de mémoire.

Contenu connexe

  • Last updated on