Compartir a través de

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

Importante

La memoria (versión preliminar) del servicio Foundry Agent y la API de almacenamiento de memoria (versión preliminar) tienen licencia para usted como parte de su suscripción de Azure y están sujetas a los términos aplicables a las "versiones preliminares" de los términos del producto de Microsoft y el anexo de protección de datos de productos y servicios de Microsoft, así como los términos de versión preliminar de Microsoft Generative AI Services en los términos complementarios de uso para las versiones preliminares de Microsoft Azure.

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 REST API
Crear, actualizar, enumerar y eliminar almacenes de memoria ✔️ ✔️
Actualizar y buscar memorias ✔️ ✔️
Adjuntar memoria a un agente prompt ✔️ ✔️

Prerrequisitos

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 Azure Portal.
  2. En tu proyecto:
    1. En el panel izquierdo, seleccione Gestión de recursos>Identidad.
    2. Utilice el conmutador para habilitar una identidad administrada asignada por el sistema.
  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 rol.
    3. Asigne Azure AI User a la identidad administrada de tu proyecto.

Establecer punto final del proyecto

Para ver los ejemplos de Python de este artículo, establezca una variable de entorno para el punto de conexión del proyecto:

export FOUNDRY_PROJECT_ENDPOINT="https://{your-ai-services-account}.services.ai.azure.com/api/projects/{project-name}"

$env:FOUNDRY_PROJECT_ENDPOINT = "https://{your-ai-services-account}.services.ai.azure.com/api/projects/{project-name}"

Descripción del ámbito

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. Puede pasar un valor estático, como un identificador único universal (UUID) u otro identificador estable del sistema.

Como alternativa, cuando se especifica {{$userId}} como ámbito, el sistema extrae automáticamente el identificador de inquilino (TID) y el identificador de objeto (OID) del encabezado de autenticación de solicitud. Este enfoque proporciona a cada usuario autenticado su propia partición de memoria aislada, lo que elimina la necesidad de administrar los identificadores manualmente.

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 de modelos de inserción que procesan el contenido de la memoria.

import os
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MemoryStoreDefaultDefinition, MemoryStoreDefaultOptions
from azure.identity import DefaultAzureCredential

project_client = AIProjectClient(
    endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

memory_store_name = "my_memory_store"

# Specify memory store options
options = MemoryStoreDefaultOptions(
    chat_summary_enabled=True,
    user_profile_enabled=True,
    user_profile_details="Avoid irrelevant or sensitive data, such as age, financials, precise location, and credentials"
)

# Create memory store
definition = MemoryStoreDefaultDefinition(
    chat_model="gpt-5.2",  # Your chat model deployment name
    embedding_model="text-embedding-3-small",  # Your embedding model deployment name
    options=options
)

memory_store = project_client.beta.memory_stores.create(
    name=memory_store_name,
    definition=definition,
    description="Memory store for customer support agent",
)

print(f"Created memory store: {memory_store.name}")

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 las "preferencias de la aerolínea y las restricciones alimentarias" para una agencia 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".

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

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

Uso de memorias a través de una herramienta de agente

Después de crear un almacén de memoria, puede adjuntar la herramienta de búsqueda de memoria a un agente de indicaciones. 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.

# Continue from the previous Python snippets.
from azure.ai.projects.models import MemorySearchPreviewTool, PromptAgentDefinition

# Set scope to associate the memories with
# You can also use "{{$userId}}" to take the TID and OID of the request authentication header
scope = "user_123"

openai_client = project_client.get_openai_client()

# Create memory search tool
tool = MemorySearchPreviewTool(
    memory_store_name=memory_store_name,
    scope=scope,
    update_delay=1,  # Wait 1 second of inactivity before updating memories
    # In a real application, set this to a higher value like 300 (5 minutes, default)
)

# Create a prompt agent with memory search tool
agent = project_client.agents.create_version(
    agent_name="MyAgent",
    definition=PromptAgentDefinition(
        model="gpt-5.2",
        instructions="You are a helpful assistant that answers general questions",
        tools=[tool],
    )
)

print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

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 en cada turno en función de los mensajes más recientes para informar cada respuesta.

Después de cada respuesta del agente, el servicio llama internamente a update_memories. Sin embargo, las escrituras reales en la memoria a largo plazo se desaplican mediante la update_delay configuración . La actualización se programa y solo se completa después del período configurado de inactividad.

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

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 recuerdos proporcionando contenido de conversación al almacén de recuerdos. 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 actualizarlo después de cada turno encadenando las actualizaciones mediante el identificador de la operación de actualización del turno anterior.

# Continue from the previous Python snippets.
# Set scope to associate the memories with
scope = "user_123"

user_message = {
  "role": "user",
  "content": "I prefer dark roast coffee and usually drink it in the morning",
   "type": "message"
}

update_poller = project_client.beta.memory_stores.begin_update_memories(
    name=memory_store_name,
    scope=scope,
    items=[user_message],  # Pass conversation items that you want to add to memory
    update_delay=0,  # Trigger update immediately without waiting for inactivity
)

# Wait for the update operation to complete, but can also fire and forget
update_result = update_poller.result()
print(f"Updated with {len(update_result.memory_operations)} memory operations")
for operation in update_result.memory_operations:
    print(
        f"  - Operation: {operation.kind}, Memory ID: {operation.memory_item.memory_id}, Content: {operation.memory_item.content}"
    )

# Extend the previous update with another update and more messages
new_message = {
    "role":"user", 
    "content":"I also like cappuccinos in the afternoon", 
    "type":"message"}

new_update_poller = project_client.beta.memory_stores.begin_update_memories(
    name=memory_store_name,
    scope=scope,
    items=[new_message],
    previous_update_id=update_poller.update_id,  # Extend from previous update ID
    update_delay=0,  # Trigger update immediately without waiting for inactivity
)
new_update_result = new_update_poller.result()
for operation in new_update_result.memory_operations:
    print(
        f"  - Operation: {operation.kind}, Memory ID: {operation.memory_item.memory_id}, Content: {operation.memory_item.content}"
    )

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.

# Continue from the previous Python snippets.
from azure.ai.projects.models import MemorySearchOptions

# Search memories by a query
query_message = {"role": "user", "content": "What are my coffee preferences?", "type": "message"}

search_response = project_client.beta.memory_stores.search_memories(
    name=memory_store_name,
    scope=scope,
    items=[query_message],
    options=MemorySearchOptions(max_memories=5)
)
print(f"Found {len(search_response.memories)} memories")
for memory in search_response.memories:
    print(f"  - Memory ID: {memory.memory_item.memory_id}, Content: {memory.memory_item.content}")

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 recuerdos contextuales, llame a search_memories configurando items en los mensajes más recientes. Esto puede devolver tanto los recuerdos de perfil de usuario como los resúmenes de chat más relevantes para los elementos especificados.

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

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

Eliminación de un almacén de memoria

Quite todo el almacenamiento de memoria y todas las memorias asociadas en todos los entornos. 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}")

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.

  • Asignar ámbito a un usuario autenticado: Al especificar el ámbito en la herramienta de búsqueda de memoria, establezca scope={{$userId}} para asignarlo al usuario desde el token de autenticación ().{tid}_{oid} Esto garantiza que las búsquedas de memoria tengan como destino automáticamente el usuario correcto.

  • 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 una pista de auditoría resistente a 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.

Solución de problemas

Cuestión Causa Resolución
Las solicitudes fallan con un error de autenticación o autorización. La identidad o la identidad administrada del proyecto no tienen 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 herramienta y hace referencia al nombre correcto del almacén de memoria.

Contenido relacionado

  • Last updated on