Creación y uso de memoria en foundry Agent Service (versión preliminar)

Importante

La memoria (versión preliminar) en Foundry Agent Service y la API de Memory Store (versión preliminar) se le conceden bajo licencia como parte de su suscripción a Azure y están sujetas a los términos aplicables a las "versiones preliminares" en los Términos de productos de Microsoft, el Anexo de protección de datos de productos y servicios de Microsoft y los Términos de uso complementarios para las versiones preliminares de Microsoft Azure.

La versión preliminar más reciente ofrece nuevas funcionalidades y mejoras, entre las que se incluyen:

  • Operaciones de elementos de memoria para crear, leer, actualizar, enumerar y eliminar registros de memoria individuales.
  • Controles de retención predeterminados de nivel de almacén, incluido el TTL predeterminado para los almacenes de memoria recién creados.
  • Comportamiento directo de comandos de memoria sincronizada de recordar u olvidar.

Memory in Foundry Agent Service es una solución de memoria administrada y a largo plazo. Permite la continuidad del agente entre sesiones, dispositivos y flujos de trabajo. Al crear y administrar almacenes de memoria, puede crear agentes que conserven las preferencias del usuario, mantengan el historial de conversaciones y proporcionen experiencias personalizadas.

Los almacenes de memoria actúan como almacenamiento persistente, definiendo qué tipos de información son relevantes para cada agente. El acceso se controla mediante el scope parámetro , que segmenta la memoria entre los usuarios para garantizar experiencias seguras y aisladas.

En este artículo se explica cómo crear, administrar y usar almacenes de memoria. Para obtener información conceptual, consulte Memory in Foundry Agent Service.

Soporte de uso

Capacidad SDK de Python C# SDK SDK de JavaScript SDK de Java REST API
Crear, actualizar, enumerar y eliminar almacenes de memoria ✔️ ✔️ ✔️ ✔️ ✔️
Adjuntar memoria a un agente de solicitudes ✔️ ✔️ ✔️ ✔️ ✔️
Actualizar y buscar memorias ✔️ ✔️ ✔️ ✔️ ✔️
Crear, leer, actualizar, enumerar y eliminar elementos de memoria ✔️ ✔️ ✔️ ✔️ ✔️

Requisitos previos

Autorización y permisos

Se recomienda el control de acceso basado en rol para las implementaciones de producción. Si los roles no son factibles, omita esta sección y use la autenticación basada en claves en su lugar.

Para configurar el acceso basado en roles:

  1. Inicie sesión en el portal Azure.

  2. En tu proyecto:

    1. En el panel izquierdo, seleccione Administración de Recursos>Identidad.
    2. Usa el interruptor para habilitar una identidad administrada que el sistema asigna.

  3. En el recurso que contiene el proyecto:

    1. En el panel izquierdo, seleccione Control de acceso (IAM) .

    2. Seleccione Agregar>Agregar asignación de roles.

    3. Asigne Foundry User a la identidad administrada de su proyecto.

      Importante

      Recientemente se cambió el nombre de los roles RBAC de Foundry. Foundry User, Foundry Owner, Foundry Account Owner y Foundry Project Manager se llamaban anteriormente Usuario de Azure AI, Propietario de Azure AI, Propietario de la cuenta de Azure AI y Administrador de proyectos de Azure AI. Es posible que siga viendo los nombres anteriores en algunos lugares mientras se implementa el cambio de nombre. El cambio de nombre no modifica los identificadores de rol y los permisos principales.

Configuración del entorno

Instale los paquetes necesarios:

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

Instale los paquetes necesarios:

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

Instale los paquetes necesarios:

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

Instale los paquetes necesarios:

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-ai-agents</artifactId>
</dependency>
<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-identity</artifactId>
</dependency>

Establezca variables de entorno para el punto de conexión del proyecto y los nombres de implementación del modelo:

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

Establezca variables de entorno para el punto de conexión del proyecto, implementaciones de modelos, versión de API y token de acceso:

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

Comprender el alcance

El scope parámetro controla cómo se particiona la memoria. Cada ámbito del almacén de memoria mantiene una colección aislada de elementos de memoria. Por ejemplo, si crea un agente de soporte al cliente con memoria, cada cliente debe tener su propia memoria individual.

Como desarrollador, elige la clave que se usa para almacenar y recuperar elementos de memoria. El enfoque adecuado depende de cómo acceder a la memoria.

Mediante la herramienta de búsqueda de memoria

Al adjuntar la herramienta de búsqueda de memoria a un agente, establezca scope en {{$userId}} para habilitar el aislamiento de memoria por usuario sin identificadores de codificación rígida. El sistema resuelve automáticamente la identidad del usuario final en cada llamada de respuesta de uno de dos orígenes:

  • x-memory-user-id encabezado de solicitud: si está presente, el valor de encabezado se usa como identificador de usuario. Úselo en escenarios de proxy o back-end en los que el servicio llama a la API en nombre de un usuario final.

  • Token de autenticación de Microsoft Entra: si no se ha establecido el encabezado, el sistema recurre al identificador de inquilino (TID) del autor de la llamada y al identificador de objeto (OID). Este es el valor predeterminado en escenarios de front-end en los que los usuarios se autentican directamente con Microsoft Entra.

Si no necesita aislamiento por usuario, use un valor estático scope en su lugar.

A través de las API de memoria de bajo nivel

Al llamar directamente a las API de memoria , especifique scope explícitamente en cada solicitud. Puede pasar un valor estático, como un identificador único universal (UUID) u otro identificador estable del sistema. La extracción automática de identidades no se admite para estas operaciones.

Creación de un almacén de memoria

Cree un almacén de memoria dedicado para cada agente para establecer límites claros para el acceso a memoria y la optimización. Al crear un almacén de memoria, especifique el modelo de chat y las implementaciones del modelo de inserción que procesan el contenido de la memoria.

Use las opciones de almacenamiento de memoria para controlar el comportamiento de extracción y los valores predeterminados de retención. En la versión preliminar más reciente, puede habilitar la memoria de procedimientos y establecer un TTL predeterminado (segundos) para las entradas de memoria recién creadas.

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,
    procedural_memory_enabled=True,
    default_ttl_seconds=30 * 24 * 60 * 60,
    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 with procedural memory and 30-day default TTL",
)

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,
  procedural_memory_enabled: true,
  default_ttl_seconds: 30 * 24 * 60 * 60,
  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 with procedural memory and 30-day default TTL",
  },
);

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

import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.MemoryStoresClient;
import com.azure.ai.agents.models.MemoryStoreDefaultDefinition;
import com.azure.ai.agents.models.MemoryStoreDefaultOptions;
import com.azure.ai.agents.models.MemoryStoreDetails;
import com.azure.identity.DefaultAzureCredentialBuilder;

String projectEndpoint = System.getenv("FOUNDRY_PROJECT_ENDPOINT");
String chatModel = System.getenv("MEMORY_STORE_CHAT_MODEL_DEPLOYMENT_NAME");
String embeddingModel =
  System.getenv("MEMORY_STORE_EMBEDDING_MODEL_DEPLOYMENT_NAME");

MemoryStoresClient memoryStoresClient = new AgentsClientBuilder()
  .credential(new DefaultAzureCredentialBuilder().build())
  .endpoint(projectEndpoint)
  .buildMemoryStoresClient();

String memoryStoreName = "my_memory_store";

MemoryStoreDefaultDefinition definition =
  new MemoryStoreDefaultDefinition(chatModel, embeddingModel)
    .setOptions(new MemoryStoreDefaultOptions(true, true));

MemoryStoreDetails memoryStore = memoryStoresClient.createMemoryStore(
  memoryStoreName,
  definition,
  "Memory store for customer support agent",
  null);

System.out.println("Created memory store: " + memoryStore.getName());

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 with procedural memory and 30-day default TTL",
    "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,
        "procedural_memory_enabled": true,
        "default_ttl_seconds": 2592000,
        "user_profile_details": "Avoid irrelevant or sensitive data, such as age, financials, precise location, and credentials"
      }
    }
  }'

Sugerencia

  • Los fragmentos de código de Python, C#, TypeScript y Java restantes se basan en el cliente y las variables definidas en Creación de un almacén de memoria. Si ejecuta esos fragmentos de código de forma independiente, incluya el código de inicialización de cliente y de importación en esta sección.

  • Los fragmentos de código de C# de este artículo usan métodos sincrónicos. Para el uso asincrónico, consulte la herramienta de búsqueda de memoria y los ejemplos de almacenamiento de memoria.

Personalización de la memoria

Personalice la información que almacena el agente para mantener la memoria eficiente, relevante y respetando la privacidad. Use el user_profile_details parámetro para especificar los tipos de datos críticos para la función del agente.

Por ejemplo, establezca user_profile_details para dar prioridad a la "preferencia de operador de vuelos y restricciones alimentarias" para un agente de viajes. Este enfoque centrado ayuda al sistema de memoria a saber qué detalles extraer, resumir y confirmar en la memoria a largo plazo.

También puede usar este parámetro para excluir determinados tipos de datos, mantener la memoria ajustada y cumplir los requisitos de privacidad. Por ejemplo, establezca en user_profile_details "evitar datos irrelevantes o confidenciales, como edad, finanzas, ubicación precisa y credenciales".

Configurar TTL y directivas de retención

TTL se aplica a todas las memorias, ya sea desde comandos de memoria directa, extracción y consolidación, o operaciones CRUD de nivel de elemento. Si se actualiza y consolida una memoria, el servicio restablece su hora de última actualización.

TTL solo se aplica a los almacenes de memoria creados después de que se introdujo la compatibilidad con TTL. No afecta a los almacenes de memoria existentes.

Un default_ttl_seconds valor de 0 indica que no expira. Elija un período de retención que coincida con los requisitos de cumplimiento y ciclo de vida de los datos de usuario.

Actualización de un almacén de memoria

Actualice las propiedades del almacén de memoria, como description o metadata, para administrar mejor los almacenes de 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}`);

import com.azure.ai.agents.models.MemoryStoreDetails;

MemoryStoreDetails updatedStore = memoryStoresClient.updateMemoryStore(
  memoryStoreName,
  "Updated description",
  null);

System.out.println("Updated: " + updatedStore.getDescription());

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

Enumerar almacenes de memoria

Recupere una lista de almacenes de memoria en el proyecto para administrar y supervisar la infraestructura de 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})`);
}

import com.azure.ai.agents.models.MemoryStoreDetails;

System.out.println("Listing all memory stores...");
for (MemoryStoreDetails store : memoryStoresClient.listMemoryStores()) {
    System.out.println(
        "  - Memory Store: " + store.getName() + " (" + store.getId() + ")");
}

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

Usar memorias a través de una herramienta de agente

Tras crear un almacén de memoria, puede vincular la herramienta de búsqueda de memoria a un agente de instrucciones. Esta herramienta permite al agente leer y escribir en el almacén de memoria durante las conversaciones. Configure la herramienta con el adecuado scope y update_delay para controlar cómo y cuándo se actualizan los recuerdos.

Sugerencia

Para limitar los recuerdos a un usuario final individual, establezca scope"{{$userId}}" en la definición de la herramienta y pase x-memory-user-id: <user-id> como encabezado en cada llamada de respuesta. El sistema resuelve el ámbito de la identidad de ese usuario. Sin el encabezado, el alcance vuelve a la identidad Microsoft Entra del autor de la llamada (TID y OID). Para obtener más información, consulte Descripción del ámbito.

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

import com.azure.ai.agents.AgentsClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.models.AgentVersionDetails;
import com.azure.ai.agents.models.MemorySearchPreviewTool;
import com.azure.ai.agents.models.PromptAgentDefinition;
import com.azure.identity.DefaultAzureCredentialBuilder;

String scope = "user_123";

AgentsClient agentsClient = new AgentsClientBuilder()
  .credential(new DefaultAzureCredentialBuilder().build())
  .endpoint(projectEndpoint)
  .buildAgentsClient();

MemorySearchPreviewTool memoryTool = new MemorySearchPreviewTool(
  memoryStoreName,
  scope).setUpdateDelaySeconds(1);

PromptAgentDefinition agentDefinition = new PromptAgentDefinition(chatModel)
  .setInstructions("You are a helpful assistant that answers general questions")
  .setTools(java.util.Collections.singletonList(memoryTool));

AgentVersionDetails agent =
  agentsClient.createAgentVersion("MyAgent", agentDefinition);

System.out.println(
  "Agent created (id: " + agent.getId() + ", name: " + agent.getName()
    + ", version: " + agent.getVersion() + ")");

# 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
            }
        ]
    }
}'

Creación de una conversación

Ahora puede crear conversaciones y solicitar respuestas del agente. Al principio de cada conversación, se insertan memorias estáticas para que el agente tenga contexto inmediato y persistente. Los recuerdos contextuales se recuperan por turno en función de los mensajes más recientes para informar cada respuesta.

Después de que cada agente responda, el servicio llama internamente a update_memories. Sin embargo, las operaciones de escritura reales en la memoria a largo plazo se agrupan y se retrasan mediante la opción update_delay. La actualización se programa y solo se completa después del período configurado de inactividad.

Note

En el esquema de vista previa actualizado, la salida de la herramienta de búsqueda de memoria usa una memories colección en lugar del campo heredado results . Si procesa cargas de salida sin procesar, actualice los analizadores en consecuencia.

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}`);

import com.azure.ai.agents.ResponsesClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.models.AgentReference;
import com.azure.ai.agents.models.AzureCreateResponseOptions;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

ResponsesClient responsesClient = new AgentsClientBuilder()
  .credential(new DefaultAzureCredentialBuilder().build())
  .endpoint(projectEndpoint)
  .buildResponsesClient();

AgentReference agentReference = new AgentReference(agent.getName())
  .setVersion(agent.getVersion());

Response response = responsesClient.createAzureResponse(
  new AzureCreateResponseOptions().setAgentReference(agentReference),
  ResponseCreateParams.builder()
    .input("I prefer dark roast coffee"));

System.out.println("Response output: " + response.output());

System.out.println("Waiting for memories to be stored...");
Thread.sleep(65_000);

Response newResponse = responsesClient.createAzureResponse(
  new AzureCreateResponseOptions().setAgentReference(agentReference),
  ResponseCreateParams.builder()
    .input("Please order my usual coffee"));

System.out.println("Response output: " + newResponse.output());

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

Aplicar comportamiento directo de recordar u olvidar

Cuando un usuario pide explícitamente al agente que recuerde o olvide información, la herramienta de búsqueda de memoria de la tools matriz aplica la operación inmediatamente y devuelve el resultado como elementos de comando de memoria en la salida de la respuesta. No se requiere ninguna configuración adicional de herramientas.

Note

Los comandos de memoria directa no invalidan el TTL de memoria. Si un almacén de memoria tiene configurado TTL, los elementos de memoria todavía pueden expirar, incluso si se agregaron mediante un comando remember.

openai_client = project_client.get_openai_client()

# Configure the memory search tool
tools = [
    {
        "type": "memory_search_preview",
        "memory_store_name": memory_store_name,
        "scope": scope,
    }
]

# Ask the agent to remember information
remember_response = openai_client.responses.create(
    model=os.environ["MEMORY_STORE_CHAT_MODEL_DEPLOYMENT_NAME"],
    tools=tools,
    input="Remember that my preferred seat is aisle.",
)

for item in remember_response.output:
    if getattr(item, "type", None) == "memory_command_call":
        print(item.type)       # memory_command_call
        print(item.arguments)  # {"action": "remember", "content": "..."}
        print(item.status)     # completed

# Ask the agent to forget information
forget_response = openai_client.responses.create(
    model=os.environ["MEMORY_STORE_CHAT_MODEL_DEPLOYMENT_NAME"],
    tools=tools,
    input="Forget my preferred seat.",
)

for item in forget_response.output:
    if getattr(item, "type", None) == "memory_command_call":
        print(item.type)
        print(item.arguments)  # {"action": "forget", "content": "..."}
        print(item.status)

// This code snippet is currently unavailable.

const openaiClient = project.getOpenAIClient();

// Configure the memory search tool
const tools = [
  {
    type: "memory_search_preview",
    memory_store_name: memoryStoreName,
    scope: scope,
  },
];

// Ask the agent to remember information
const rememberResponse = await openaiClient.responses.create({
  model: chatModelDeployment,
  input: "Remember that my preferred seat is aisle.",
  tools: tools as any,
});

for (const item of rememberResponse.output) {
  const outputItem = item as Record<string, unknown>;
  if (outputItem["type"] === "memory_command_call") {
    console.log(outputItem["type"]);       // memory_command_call
    console.log(outputItem["arguments"]);
    // {"action": "remember", "content": "..."}
    console.log(outputItem["status"]);     // completed
  }
}

// Ask the agent to forget information
const forgetResponse = await openaiClient.responses.create({
  model: chatModelDeployment,
  input: "Forget my preferred seat.",
  tools: tools as any,
});

for (const item of forgetResponse.output) {
  const outputItem = item as Record<string, unknown>;
  if (outputItem["type"] === "memory_command_call") {
    console.log(outputItem["type"]);
    console.log(outputItem["arguments"]);
    // {"action": "forget", "content": "..."}
    console.log(outputItem["status"]);
  }
}

import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

Response rememberResponse = responsesClient.createAzureResponse(
  new AzureCreateResponseOptions().setAgentReference(agentReference),
  ResponseCreateParams.builder()
    .input("Remember that my preferred seat is aisle."));

System.out.println(rememberResponse.output());

Response forgetResponse = responsesClient.createAzureResponse(
  new AzureCreateResponseOptions().setAgentReference(agentReference),
  ResponseCreateParams.builder()
    .input("Forget my preferred seat."));

System.out.println(forgetResponse.output());

# Reuse the {conversation-id} from the previous section
# To scope memories to an end user, set x-memory-user-id in each request
curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/openai/v1/responses" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "x-memory-user-id: <user-id>" \
  -d '{
    "input": "Remember that my preferred seat is aisle.",
    "conversation": "{conversation-id}",
    "agent_reference": {
      "type": "agent_reference",
      "name": "MyAgent"
    }
  }'

curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/openai/v1/responses" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "x-memory-user-id: <user-id>" \
  -d '{
    "input": "Forget my preferred seat.",
    "conversation": "{conversation-id}",
    "agent_reference": {
      "type": "agent_reference",
      "name": "MyAgent"
    }
  }'

Uso de memorias mediante API

Puede interactuar con un almacén de memoria directamente mediante las API del almacén de memoria. Empiece por agregar memorias del contenido de conversación al almacén de memoria y, a continuación, busque memorias pertinentes para proporcionar contexto para las interacciones del agente.

Agregar memorias a un almacén de memoria

Agregue memorias proporcionando contenido de conversación al almacén de memoria. El sistema preprocesa y posprocesa los datos, incluida la extracción y consolidación de memoria, para optimizar la memoria del agente. Esta operación de larga duración puede tardar aproximadamente un minuto.

Decida cómo segmentar la memoria entre los usuarios especificando el scope parámetro . Puede limitar la memoria a un usuario final específico, un equipo u otro identificador.

Puede actualizar un almacén de memoria con contenido de varios turnos de conversación, o bien actualizar después de cada turno y encadenar actualizaciones usando el ID de la operación de actualización anterior.

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

import com.azure.ai.agents.models.MemoryStoreUpdateCompletedResult;
import com.azure.ai.agents.models.MemoryStoreUpdateResponse;
import com.azure.core.util.polling.SyncPoller;
import com.openai.models.responses.EasyInputMessage;
import com.openai.models.responses.ResponseInputItem;
import java.util.Arrays;

ResponseInputItem userMessage = ResponseInputItem.ofEasyInputMessage(
  EasyInputMessage.builder()
    .role(EasyInputMessage.Role.USER)
    .content("I prefer dark roast coffee and usually drink it in the morning")
    .build());

SyncPoller<MemoryStoreUpdateResponse, MemoryStoreUpdateCompletedResult> updatePoller =
  memoryStoresClient.beginUpdateMemories(
    memoryStoreName,
    scope,
    Arrays.asList(userMessage),
    null,
    0);

updatePoller.waitForCompletion();
MemoryStoreUpdateCompletedResult updateResult = updatePoller.getFinalResult();
System.out.println(
  "Updated with " + updateResult.getMemoryOperations().size()
    + " memory operation(s)");
for (var operation : updateResult.getMemoryOperations()) {
  System.out.println(
    "  - Operation: " + operation.getKind() + ", Memory ID: "
      + operation.getMemoryItem().getMemoryId() + ", Content: "
      + operation.getMemoryItem().getContent());
}

ResponseInputItem newMessage = ResponseInputItem.ofEasyInputMessage(
  EasyInputMessage.builder()
    .role(EasyInputMessage.Role.USER)
    .content("I also like cappuccinos in the afternoon")
    .build());

// Pass null for previousUpdateId to start a fresh independent update.
// To chain from the previous update, pass the update ID from the
// intermediate poller response instead.
SyncPoller<MemoryStoreUpdateResponse, MemoryStoreUpdateCompletedResult> newUpdatePoller =
  memoryStoresClient.beginUpdateMemories(
    memoryStoreName,
    scope,
    Arrays.asList(newMessage),
    null,
    0);

newUpdatePoller.waitForCompletion();
MemoryStoreUpdateCompletedResult newUpdateResult = newUpdatePoller.getFinalResult();
for (var newOperation : newUpdateResult.getMemoryOperations()) {
  System.out.println(
    "  - Operation: " + newOperation.getKind() + ", Memory ID: "
      + newOperation.getMemoryItem().getMemoryId() + ", Content: "
      + newOperation.getMemoryItem().getContent());
}

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

Buscar recuerdos en un almacén de memoria

Buscar memorias para recuperar el contexto pertinente para las interacciones del agente. Especifique el nombre y el ámbito del almacén de memoria para restringir la búsqueda.

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

import com.azure.ai.agents.models.MemorySearchItem;
import com.azure.ai.agents.models.MemorySearchOptions;
import com.azure.ai.agents.models.MemoryStoreSearchResponse;
import com.openai.models.responses.EasyInputMessage;
import com.openai.models.responses.ResponseInputItem;
import java.util.Arrays;

ResponseInputItem queryMessage = ResponseInputItem.ofEasyInputMessage(
  EasyInputMessage.builder()
    .role(EasyInputMessage.Role.USER)
    .content("What are my coffee preferences?")
    .build());

MemorySearchOptions searchOptions = new MemorySearchOptions()
  .setMaxMemories(5);

MemoryStoreSearchResponse searchResponse = memoryStoresClient.searchMemories(
  memoryStoreName,
  scope,
  Arrays.asList(queryMessage),
  null,
  searchOptions);

System.out.println("Found " + searchResponse.getMemories().size() + " memories");
for (MemorySearchItem item : searchResponse.getMemories()) {
  System.out.println(
    "  - Memory ID: " + item.getMemoryItem().getMemoryId() + ", Content: "
      + item.getMemoryItem().getContent());
}

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

Recuperar memorias estáticas o contextuales

A menudo, los recuerdos de perfil de usuario no se pueden recuperar en función de la similitud semántica con el mensaje de un usuario. Se recomienda insertar memorias estáticas al principio de cada conversación y usar memorias contextuales para generar cada respuesta del agente.

  • Para recuperar memorias estáticas, llame a search_memories con un scope pero sin items o previous_search_id. Esto devuelve memorias de perfil de usuario asociadas al ámbito.

  • Para recuperar memorias contextuales, llame a search_memories con el valor items en los mensajes más recientes. Esto puede mostrar tanto los datos del perfil de usuario como los resúmenes de chat más relevantes para los elementos indicados.

Para obtener más información sobre los recuerdos de resumen de chat y perfil de usuario, consulte Tipos de memoria.

Administrar elementos de memoria

Use operaciones de nivel de elemento para crear, inspeccionar, actualizar y eliminar registros de memoria individuales directamente. Para el borrado a nivel de ámbito o a nivel de almacén, consulte Eliminar recuerdos.

Creación de un elemento de memoria

# Create a memory item directly
created = project_client.beta.memory_stores.create_memory(
    name=memory_store_name,
    scope="defaultUser",
    content="User prefers concise changelogs with impact-first summaries.",
    kind="user_profile",
)

print(f"Memory ID: {created.memory_id}")
print(f"Content: {created.content}")
print(f"Kind: {created.kind}")

// This code snippet is currently unavailable.

// Create a memory item directly
const created = await project.beta.memoryStores.createMemory(
  memoryStoreName,
  "defaultUser",
  "User prefers concise changelogs with impact-first summaries.",
  "user_profile",
);

console.log(`Memory ID: ${created.memory_id}`);
console.log(`Content: ${created.content}`);
console.log(`Kind: ${created.kind}`);

import com.azure.ai.agents.models.MemoryItem;
import com.azure.ai.agents.models.MemoryItemKind;

MemoryItem created = memoryStoresClient.createMemory(
  memoryStoreName,
  "defaultUser",
  "User prefers concise changelogs with impact-first summaries.",
  MemoryItemKind.USER_PROFILE);

System.out.println("Memory ID: " + created.getMemoryId());
System.out.println("Content: " + created.getContent());
System.out.println("Kind: " + created.getKind());

curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/my_memory_store/items?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "defaultUser",
    "content": "User prefers concise changelogs with impact-first summaries.",
    "kind": "user_profile"
  }'

Obtener un elemento de memoria

# Retrieve a memory item by ID
item = project_client.beta.memory_stores.get_memory(
    name=memory_store_name,
    memory_id="<memory-item-id>",
)

print(f"Memory ID: {item.memory_id}")
print(f"Content: {item.content}")
print(f"Kind: {item.kind}")

// This code snippet is currently unavailable.

// Retrieve a memory item by ID
const item = await project.beta.memoryStores.getMemory(
  memoryStoreName,
  "<memory-item-id>",
);

console.log(`Memory ID: ${item.memory_id}`);
console.log(`Content: ${item.content}`);
console.log(`Kind: ${item.kind}`);

import com.azure.ai.agents.models.MemoryItem;

MemoryItem memItem = memoryStoresClient.getMemory(
  memoryStoreName,
  "<memory-item-id>");

System.out.println("Memory ID: " + memItem.getMemoryId());
System.out.println("Content: " + memItem.getContent());
System.out.println("Kind: " + memItem.getKind());

curl -X GET "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/my_memory_store/items/<memory-item-id>?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Enumerar elementos de memoria

# List all memory items in the store
memories = project_client.beta.memory_stores.list_memories(
    name=memory_store_name,
    scope="defaultUser",
)

count = 0
for item in memories:
    count += 1
    print(f"- {item.memory_id} [{item.kind}]: {item.content}")

print(f"Total memories: {count}")

// This code snippet is currently unavailable.

// List all memory items in the store
const memoriesList = project.beta.memoryStores.listMemories(
  memoryStoreName,
  "defaultUser",
);

let count = 0;
for await (const item of memoriesList) {
  count += 1;
  console.log(`- ${item.memory_id} [${item.kind}]: ${item.content}`);
}
console.log(`Total memories: ${count}`);

import com.azure.ai.agents.models.ListMemoriesOptions;
import com.azure.ai.agents.models.MemoryItem;

ListMemoriesOptions options = new ListMemoriesOptions(
  memoryStoreName,
  "defaultUser");

int count = 0;
for (MemoryItem memoryEntry : memoryStoresClient.listMemories(options)) {
  count++;
  System.out.println(
    "- " + memoryEntry.getMemoryId() + " [" + memoryEntry.getKind() + "]: "
      + memoryEntry.getContent());
}

System.out.println("Total memories: " + count);

curl -X GET "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/my_memory_store/items:list?scope=user_123&api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Actualizar un elemento de memoria

# Update a memory item by ID
updated = project_client.beta.memory_stores.update_memory(
    name=memory_store_name,
    memory_id="<memory-item-id>",
    content="User prefers detailed technical explanations with examples.",
)

print(f"Updated: {updated.content}")

// This code snippet is currently unavailable.

// Update a memory item by ID
const updated = await project.beta.memoryStores.updateMemory(
  memoryStoreName,
  "<memory-item-id>",
  "User prefers detailed technical explanations with examples.",
);

console.log(`Updated: ${updated.content}`);

import com.azure.ai.agents.models.MemoryItem;

MemoryItem updated = memoryStoresClient.updateMemory(
  memoryStoreName,
  "<memory-item-id>",
  "User prefers detailed technical explanations with examples.");

System.out.println("Updated: " + updated.getContent());

curl -X POST "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/my_memory_store/items/<memory-item-id>?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"content": "User prefers detailed technical explanations with examples."}'

Eliminar un elemento de memoria

# Delete a memory item by ID
project_client.beta.memory_stores.delete_memory(
    name=memory_store_name,
    memory_id="<memory-item-id>",
)

print("Memory item deleted successfully")

// This code snippet is currently unavailable.

// Delete a memory item by ID
await project.beta.memoryStores.deleteMemory(
  memoryStoreName,
  "<memory-item-id>",
);

console.log("Memory item deleted successfully");

memoryStoresClient.deleteMemory(memoryStoreName, "<memory-item-id>");

System.out.println("Memory item deleted successfully");

curl -X DELETE "${FOUNDRY_PROJECT_ENDPOINT}/memory_stores/my_memory_store/items/<memory-item-id>?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Eliminar memorias

Advertencia

Antes de eliminar un almacén de memoria, tenga en cuenta el impacto en los agentes dependientes. Es posible que los agentes con almacenes de memoria adjunta pierdan acceso al contexto histórico.

Los recuerdos se organizan por ámbito dentro de un almacén de memoria. Puede eliminar memorias de un ámbito específico para quitar datos específicos del usuario o puede eliminar todo el almacén de memoria para quitar todas las memorias en todos los ámbitos.

Eliminar memorias por ámbito

Quite todas las memorias asociadas a un ámbito de grupo o usuario determinado mientras conserva la estructura del almacén de memoria. Use esta operación para controlar las solicitudes de eliminación de datos de usuario o restablecer la memoria para usuarios específicos.

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

memoryStoresClient.deleteScope(memoryStoreName, "user_123");

System.out.println("Deleted memories for scope: user_123");

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

Eliminación de un almacén de memoria

Elimine todo el almacenamiento de memoria y todas las memorias asociadas en todos los ámbitos. Esta operación es irreversible.

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

memoryStoresClient.deleteMemoryStore(memoryStoreName);

System.out.println("Deleted memory store: " + memoryStoreName);

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

Procedimientos recomendados

  • Implemente controles de acceso por usuario: Evite proporcionar a los agentes acceso a los recuerdos compartidos entre todos los usuarios. Use la scope propiedad para particionar el almacén de memoria por usuario. Al compartir scope entre usuarios, use user_profile_details para indicar al sistema de memoria que no almacene información personal.

  • Asigne el ámbito al usuario final: al usar la herramienta de búsqueda de memoria, establezca scope en {{$userId}} en la definición de la herramienta. El sistema resuelve la identidad de usuario desde el x-memory-user-id encabezado de solicitud, si está presente. De lo contrario, se aplica el token de Microsoft Entra de la entidad de la llamada ({tid}_{oid}).

  • Minimizar y proteger los datos confidenciales: Almacene solo lo necesario para su caso de uso. Si debe almacenar datos confidenciales, como datos personales, datos de salud o entradas empresariales confidenciales, redacte o quite otro contenido que se pueda usar para realizar un seguimiento a una persona.

  • Compatibilidad con la privacidad y el cumplimiento: Proporcionar a los usuarios transparencia, incluidas las opciones para acceder a sus datos y eliminarlos. Registre todas las eliminaciones en un registro de auditoría a prueba de manipulaciones. Asegúrese de que el sistema cumple los requisitos de cumplimiento local y los estándares normativos.

  • Segmentar datos y aislar la memoria: En sistemas multiagente, segmente la memoria lógica y operativamente. Permitir que los clientes definan, aíslen, inspeccionen y eliminen su propia huella de memoria.

  • Supervisión del uso de memoria: Realice un seguimiento del uso de tokens y las operaciones de memoria para comprender los costos y optimizar el rendimiento.

  • Mostrar controles de memoria de cara al usuario: Proporcione acciones de edición y eliminación para cada elemento con el fin de respaldar flujos de trabajo de confianza y derechos sobre los datos.

  • Establezca los valores predeterminados de retención explícitos: Use la configuración de TTL que coincida con los requisitos de directiva. Documente el comportamiento de retención en la experiencia del usuario del producto.

Solución de problemas

Problema Causa Resolución
Las solicitudes fallan debido a un error de autenticación o autorización. Tu identidad o la identidad administrada del proyecto no tiene los roles necesarios. Compruebe los roles en Autorización y permisos. Para las llamadas REST, genere un token de acceso nuevo y vuelva a intentarlo.
Los recuerdos no aparecen después de una conversación. Las actualizaciones de memoria se desaplican o siguen procesando. Aumente el tiempo de espera o llame a la API de actualización con update_delay establecido en 0 para desencadenar el procesamiento inmediatamente.
La búsqueda de memoria no devuelve ningún resultado. El scope valor no coincide con el ámbito utilizado cuando se almacenan los recuerdos. Use el mismo ámbito para actualizar y buscar. Si asigna ámbito a los usuarios, use un identificador de usuario estable.
La respuesta del agente no usa memoria almacenada. El agente no está configurado con la herramienta de búsqueda de memoria o el nombre del almacén de memoria es incorrecto. Confirme que la definición del agente incluye la memory_search_preview herramienta y hace referencia al nombre correcto del almacén de memoria.
La configuración de memoria de procedimientos o TTL predeterminada no surtió efecto después de una actualización. En la versión preliminar más reciente, solo se pueden establecer opciones predeterminadas al crear el almacén de memoria. Vuelva a crear el almacén de memoria con los valores predeterminados deseados o compruebe si la versión de la API admite actualizaciones posteriores a la creación.
Una solicitud explícita de recordar u olvidar no ha devuelto elementos de comando de memoria en la respuesta. Las herramientas de memoria no están configuradas correctamente o la entrada no se reconoció como un comando remember-or-forget. Confirme la configuración de la herramienta de memoria y pruébela con formulaciones directas del tipo «recordar u olvidar».

Contenido relacionado

  • Last updated on