Este tema describe cómo seleccionar un origen de memoria, crear un almacén de memoria, integrarlo con una aplicación y recuperar y mantener memorias a largo plazo. Para comenzar, seleccione Manual write y utilice una conversación de ejemplo para comprobar el proceso completo. Si ya cuenta con trazas de agente o conjuntos de datos empresariales, configure el origen de datos correspondiente en el asistente de creación. Para conocer los conceptos básicos, consulte Memory Store overview.
Requisitos previos
Se creó un espacio de agente y usted tiene acceso a la consola AgentLoop de dicho espacio.
Determinó qué información almacenar y qué identificadores de usuario empresarial, agente o aplicación asociará con las memorias.
Si utiliza trazas de agente como origen, deben existir trazas utilizables en el espacio actual.
Si emplea un Dataset como origen, prepare un conjunto de datos en el mismo espacio y cuente con permisos de lectura sobre él. Consulte la sección a continuación para conocer los requisitos de los campos.
Si integra una aplicación mediante API, el entorno de ejecución debe poder acceder al endpoint proporcionado en la consola.
Paso 1: Crear un almacén de memoria
Inicie sesión en la consola AgentLoop, seleccione una región y un espacio de agente, elija Context Engineering > Memory Store y luego haga clic en Create Memory Store.
1. Seleccionar un origen de datos
Introduzca un valor en Memory Store Name y, de forma opcional, una Description. Después, seleccione un tipo de origen de datos.
|
Tipo |
Método de entrada |
Ejemplo |
|
Manual write |
La aplicación envía conversaciones mediante una API. |
Escribir las preferencias alimenticias de un usuario en |
|
Agent traces |
Lee continuamente las trazas de agente del espacio actual. |
Extraer el contexto del usuario a partir de las trazas de ejecución de un asistente de estilo de vida. |
|
Dataset |
Lee un conjunto de datos compatible del mismo espacio. |
Extraer hechos de un conjunto de datos curado de conversaciones con clientes. |
Haga clic en Next. No es posible cambiar el tipo de origen de datos después de crear el almacén de memoria. Defina cómo preparará los datos antes de continuar.
2. Configurar las condiciones de filtro o el esquema
Manual write
No es necesario configurar condiciones de filtro de origen. Continúe con el siguiente paso. Una vez creado el almacén de memoria, siga el paso 2 para integrar su aplicación y enviar conversaciones.
Agent traces
|
Parámetro |
Descripción |
|
Service name |
Seleccione o introduzca el nombre del servicio que se consumirá. Se admiten comodines de sufijo como |
|
Agent name |
Seleccione o introduzca el agente que se consumirá. Deje este parámetro vacío si no desea restringir el nombre del agente. |
|
Minimum steps |
Omite las trazas que contengan menos pasos que la cantidad especificada. Introduzca un número entero no negativo. |
|
Start time |
Especifique cuándo inicia el consumo. Si deja este parámetro vacío, el consumo comienza cuando se crea el almacén de memoria. |
|
Exclude degraded traces |
Excluya las trazas degradadas según sea necesario. |
|
SLS query statement |
Añade una condición de consulta al origen. Esta condición se aplica junto con las condiciones de filtro anteriores. |
Los valores múltiples dentro de una misma lista de nombres se evalúan con el operador OR. Los distintos elementos de filtro deben cumplirse simultáneamente. El origen se compone de trazas de agente ensambladas, por lo que la entrada depende de los datos recopilados realmente en el espacio actual. Antes de elegir una hora de inicio anterior, compruebe que los datos históricos correspondientes sigan disponibles.
Los identificadores de usuario, agente y aplicación presentes en las trazas deben corresponderse con los objetos empresariales para los cuales desea acumular memorias. Durante la recuperación, utilice los identificadores asociados realmente con dichas memorias. No dé por hecho que cada traza contiene un ID de usuario empresarial.
Dataset
Seleccione un Dataset Name dentro del mismo espacio de agente. El Schema Contract es
MemorySourceV1.Elija una Version Policy. La opción Incremental Follow lee continuamente los datos de las secuencias recién añadidas, mientras que Fixed Version Full lee una instantánea de una versión específica. Para una versión fija, introduzca el nombre real de dicha versión. En el seguimiento incremental, puede especificar un Start seq.
Introduzca una Filter Condition (where) según sea necesario para seleccionar los registros que se procesarán.
Revise los Additional Fields. Para los campos que el modelo necesita interpretar, seleccione Extraction Input e introduzca una descripción de su significado. Para el resto, elija Ignore. Las columnas adicionales no declaradas no se utilizan automáticamente como entradas de extracción.
El Dataset de origen debe contener los nueve campos fijos que se muestran a continuación.
|
Campo |
Tipo |
Descripción |
|
|
text |
Identificador de origen de una entrada. Utilice un valor estable y no vacío. |
|
|
json |
Arreglo de mensajes no vacío. Cada mensaje contiene |
|
|
long |
Marca de tiempo Unix positiva expresada en segundos. |
|
|
text |
Identificador del usuario empresarial. |
|
|
text |
Identificador del agente. |
|
|
text |
Identificador de la aplicación. |
|
|
text |
Identificador de la ejecución. |
|
|
json |
Objeto de metadatos empresariales. Si no hay información adicional, utilice |
|
|
json |
Objeto de descripción del origen donde |
Como mínimo uno de los cuatro identificadores empresariales debe tener un valor no vacío. No codifique arreglos u objetos JSON nuevamente como cadenas JSON. Convierta las marcas de tiempo de milisegundos a segundos.
El siguiente ejemplo muestra la estructura de campos de una entrada de Dataset. Durante la importación, sustituya el identificador de origen, la marca de tiempo, los mensajes y los identificadores empresariales por los valores reales.
{
"sourceId": "conversation-001",
"messages": [{"role": "user", "content": "I prefer light, mildly spicy dishes."}],
"timestamp": 1788796800,
"userId": "user-001",
"agentId": "cooking-assistant",
"appId": "cooking-app",
"runId": "",
"metadata": {},
"lineage": {"sourceKind": "dataset"}
}
Para asociar información empresarial externa, complete primero la asociación y la preparación de campos en el flujo de trabajo de procesamiento de datos. Luego, escriba los resultados en el Dataset de origen. Este último y el Dataset de resultados que almacena las memorias a largo plazo extraídas son recursos distintos.
3. Configurar las estrategias
Para la verificación inicial, seleccione Fact Extraction y Merge Update, y conserve los parámetros predeterminados. Si desea acumular perfiles de usuario basados en sus hábitos, elija Consumer User Profile. Para almacenar contexto empresarial, seleccione Enterprise Digital Twin. Cuando necesite definir objetivos de extracción específicos, opte por Custom Instructions.
En Scope and Audit, puede especificar un tipo de identificador empresarial obligatorio para la recuperación, como userId. Para obtener detalles sobre los parámetros y las diferencias entre los dos modos de almacenamiento, consulte Configure memory extraction and storage strategies.
4. Previsualizar y crear
Revise el origen de datos, las condiciones de filtro y el resumen de estrategia en Preview and Confirm. Puede pegar una muestra representativa y hacer clic en Run Preview para consultar los hechos extraídos, las acciones de almacenamiento y los motivos por los que se omitió contenido. Si el origen es una traza de agente o un Dataset, también puede tomar muestras directamente desde el origen configurado sin necesidad de pegarlas manualmente.
La vista previa no escribe memorias formales. Si falla, corrija la configuración o la entrada y vuelva a ejecutarla. Una vez confirmados los ajustes, haga clic en Create Memory Store. Para conocer el formato de la muestra, consulte Configure memory extraction and storage strategies.
Después de crear el almacén de memoria, vaya a la página de descripción general para comprobar su estado y el del origen de datos. Cuando el origen sea una traza de agente o un Dataset, también podrá consultar el progreso de consumo, la ventana de consumo más reciente y el último error. Además, haga clic en Pause Consumption o Resume Consumption para controlar las lecturas posteriores.
Paso 2: Integrar una aplicación
Con la escritura manual, envíe las conversaciones tal como se describe en esta sección. Los orígenes de trazas de agente y de Dataset leen los datos según sus fuentes configuradas. Cuando una aplicación necesite recuperar memorias, cree una clave de API y configure los parámetros de acceso.
Crear una clave de API
Vaya a la pestaña API Key del almacén de memoria, cree una clave y cópiela. Esta credencial queda vinculada al espacio y al almacén correspondientes. Diríjase a la pestaña Integration y copie el endpoint de la región de destino. Al utilizar las API de memoria, no es necesario especificar el nombre del espacio ni el del almacén en las solicitudes.
Guarde la credencial en una variable de entorno del servidor o en un administrador de secretos. El siguiente ejemplo utiliza la API HTTP. Sustituya los marcadores de posición por la configuración proporcionada en la página actual:
export AGENTLOOP_ENDPOINT="<Endpoint copied from the Integration tab>"
export AGENTLOOP_API_KEY="<API key of the current memory store>"Los recursos nuevos requieren tiempo para estar listos. Antes de la primera llamada, siga las instrucciones de la pestaña Integration para comprobar que el recurso está disponible.
Escribir una conversación
La siguiente solicitud asocia una conversación con el usuario empresarial user-001 y utiliza infer: true para solicitar la extracción de memoria a largo plazo.
curl -X POST "$AGENTLOOP_ENDPOINT/v1/memories" \
-H "Authorization: Token $AGENTLOOP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{"role": "user", "content": "I prefer light, mildly spicy home-style dishes."},
{"role": "assistant", "content": "I will consider your preferences when recommending dishes."}
],
"user_id": "user-001",
"infer": true
}'Primero, compruebe si la respuesta fue exitosa. Aunque se acepte una solicitud de escritura, las memorias a largo plazo aún deben pasar por un proceso asíncrono de extracción y almacenamiento. Que el asistente indique en un mensaje que recordó la información no reemplaza la verificación del resultado en el servidor.
Recuperar memorias en la aplicación
curl -X POST "$AGENTLOOP_ENDPOINT/v2/memories/search" \
-H "Authorization: Token $AGENTLOOP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "What are this user's dietary preferences?",
"user_id": "user-001",
"top_k": 5
}'El valor de user_id debe coincidir con el utilizado durante la operación de escritura. Por su parte, top_k define el número máximo de resultados que se devolverán. También puede usar la siguiente API para listar las memorias por usuario empresarial y comprobar si los datos se escribieron correctamente.
curl -X POST "$AGENTLOOP_ENDPOINT/v2/memories" \
-H "Authorization: Token $AGENTLOOP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"user_id": "user-001", "limit": 20}'Si trabaja con una aplicación en Python, elija Integration > Python SDK. Instale e inicialice MemoryClient siguiendo el ejemplo de la página. Utilice la versión, los métodos y los parámetros indicados ahí.
Paso 3: Recuperar y mantener memorias en la consola
Comprobar los resultados de recuperación
Vaya a la pestaña Long-term Memory Retrieval, introduzca "What are this user's dietary preferences?", establezca User ID en user-001, configure topK y haga clic en Start Retrieval.
Según sea necesario, añada condiciones de filtro como App ID, Agent ID, Run ID, kind y category. Los identificadores empresariales múltiples se combinan mediante el operador AND. Para consultar las preferencias de un usuario entre sesiones, no agregue un ID de ejecución que no esté relacionado con la memoria objetivo.
Las tarjetas de resultados muestran el contenido de la memoria, así como información sobre clasificación, revisiones, origen, ediciones manuales y estados de revisión. Compruebe que el significado coincida con la entrada. El modelo no necesita reproducir los mensajes palabra por palabra ni generar una cantidad fija de memorias. La puntuación indica la relevancia de la recuperación, no la exactitud factual.
Editar y eliminar memorias
Abra los detalles de una memoria, haga clic en Edit, modifique el contenido y luego haga clic en Save. Cuando la operación de guardado sea exitosa, actualice los resultados y revise el contenido más reciente. Si se reporta un conflicto de revisión, vuelva a abrir los detalles para leer la última versión antes de decidir cómo modificar la memoria.
Utilice la operación de eliminación en la tarjeta de una memoria para quitar el contenido que ya no necesite. Verifique cuál es la memoria objetivo antes de confirmar. Eliminar los datos de origen, borrar una memoria a largo plazo y eliminar un almacén de memoria completo son operaciones distintas.
Al habilitar la protección contra edición manual, los cambios nuevos propuestos por la extracción automática para contenido revisado manualmente pasan al estado de revisión pendiente y se conserva el texto original. Revise los registros de origen y auditoría para determinar el motivo. Para conocer los detalles de la estrategia, consulte Configure memory extraction and storage strategies.
Consultar los registros de origen y recuperación
Si un registro de memoria proporciona información de origen y existe un registro de escritura correspondiente, use la entrada de origen para consultar la entrada original. Cuando la página devuelva un ID de evento de recuperación, diríjase a Audit Details para inspeccionar la consulta. Para obtener una visión general, consulte View memory audits and statistics.
Paso 4: Permitir que un agente utilice las memorias
Cuando la aplicación recibe una pregunta nueva, determina el identificador de usuario a partir de su estado de inicio de sesión o del contexto empresarial. Luego recupera las memorias relevantes y entrega los resultados útiles al agente junto con la pregunta actual y las conversaciones recientes necesarias.
Por ejemplo, si el mismo usuario pregunta "¿Qué debería cenar hoy?" en una sesión nueva, la aplicación puede organizar la siguiente entrada:
Current question: What should I eat tonight?
Relevant user memory: The user prefers light, mildly spicy home-style dishes.
Response requirement: Provide suggestions based on the current question and relevant preferences, while honoring any new requirements explicitly stated by the user.Las memorias incluidas en la entrada deben provenir de resultados de recuperación reales. Una vez generada la respuesta, escriba la conversación de la ronda actual según sea necesario o permita que el origen de datos configurado proporcione las entradas posteriores.
Preguntas frecuentes
¿Por qué no hay resultados tras una escritura exitosa?
Primero, confirme el almacén de memoria y la región asociados con la clave de API. Después, compruebe si se utilizó el mismo identificador de usuario para escribir y recuperar, y si aplicó demasiados filtros adicionales. En el caso de escritura manual, revise los eventos de entrada. Para orígenes de trazas de agente y Dataset, verifique el estado de consumo, las condiciones de filtro, la posición inicial y el último error. Finalmente, utilice las auditorías de extracción y almacenamiento para determinar si el procesamiento sigue en curso, si una estrategia excluyó el contenido o si este quedó pendiente de revisión.
¿Por qué puedo previsualizar resultados pero no recuperarlos?
La vista previa de una muestra no escribe memorias formales. Envíe una entrada real o permita que el origen de datos consuma el registro correspondiente. Recupere las memorias únicamente después de completar el almacenamiento.
¿Cambiar una estrategia reprocesa todos los datos históricos?
Después de guardar una estrategia, puede consultar la nueva versión en el historial. Los registros históricos no se reconstruyen automáticamente en su totalidad al guardarla. Para comprobar el efecto de una estrategia nueva, ejecute primero una vista previa de muestra y luego observe las entradas reales posteriores.
¿Qué hago si el consumo se detiene tras modificar los campos del Dataset de origen?
Revise el último error en la página de descripción general y confirme que los nombres y tipos de los campos fijos, así como los campos adicionales en uso, siguen cumpliendo las convenciones definidas durante la creación. No reinicie el consumo repetidamente para ignorar errores de esquema. Corrija los datos primero y luego compruebe el estado de consumo.