Memoria del agente administrado

Importante

Esta característica se encuentra en su versión beta. Los administradores del área de trabajo pueden controlar el acceso a esta característica desde la página Vistas previas . Consulte Administrar versiones preliminares de Azure Databricks.

La memoria gestionada del agente proporciona a tus agentes memoria a largo plazo entre distintas conversaciones. Azure Databricks se encarga de la infraestructura y aísla las memorias de cada ámbito, por lo que no tienes que administrar el almacenamiento ni el particionado por tu cuenta.

Con la memoria administrada, los agentes pueden:

• Recuerde las preferencias del usuario, las decisiones anteriores y el contexto acumulado en las conversaciones.
• Asegure ese conocimiento con la gobernanza de Unity Catalog.
• Compartir memoria entre agentes y proyectos.
• Mejore su precisión y eficacia a lo largo del tiempo.

Requirements

• Un área de trabajo de Databricks con unity Catalog habilitado.
• Privilegio CREATE MEMORY STORE en el esquema primario para crear almacenes de memoria.

Funcionamiento de la memoria administrada

La memoria administrada tiene dos niveles:

• Un almacén de memoria es un objeto protegible de Unity Catalog que actúa como contenedor de entradas de memoria. Un almacén de memoria hereda la misma gobernanza, control de acceso y linaje que cualquier otro recurso de Catálogo de Unity.
• Una entrada de memoria es un fragmento de contenido individual almacenado dentro de un almacén de memoria. Cada entrada se identifica mediante un ámbito y una ruta de acceso. El ámbito determina a cuyos recuerdos pertenece una entrada y la ruta de acceso organiza las entradas dentro de un ámbito, similar a una ruta de acceso de archivo (por ejemplo, /memories/preferences.md).

Ámbito

El alcance es cómo haces que una memoria sea privada para un usuario o compartida entre un grupo. Tu aplicación establece un alcance en cada lectura y escritura, y una búsqueda solo devuelve entradas con un alcance coincidente. Elige la estrategia que se ajuste a lo que tu agente necesita recordar:

• Memoria privada para cada usuario: Configura el ámbito a la identidad verificada del usuario final. Cada usuario recibe su propia partición y solo ve sus propias entradas. El valor user_client determina por usted el identificador del usuario final.
  • Ejemplo: Un agente de soporte recuerda las preferencias de comunicación de un usuario y tickets anteriores.
• Memoria compartida para un grupo: Establece el alcance a una clave fija que elijas, como un ID de organización, equipo o proyecto. Todos los usuarios leen y escriben los mismos recuerdos.
  • Ejemplo: Un agente de equipo recuerda un glosario compartido de términos de la empresa y políticas internas.
• División de memoria por otro criterio: Define el ámbito a partir de tus propios valores, como un ID de inquilino o un user_id:project compuesto.
  • Ejemplo: Una aplicación multiinquilino mantiene separada la memoria de cada cliente, o la memoria de un solo usuario está aislada por proyecto.

Un solo agente puede combinar estrategias en una sola conversación. Por ejemplo, puede leer la memoria privada de un usuario y la memoria compartida del equipo en la misma petición.

Establezca el ámbito en el código de su aplicación, a partir de un contexto de llamante de confianza que la solicitud no pueda manipular: la identidad verificada del usuario final a partir del token OBO para la memoria por usuario, o una clave de confianza de inquilino, equipo o proyecto para la memoria compartida. Nunca dejes que el modelo lo eliga. Si tu estrategia de alcance depende de una identidad de usuario final, rechaza las solicitudes que no la tengan en lugar de recurrir a un alcance compartido. La managed-memory función te guía durante esta configuración.

El ámbito separa las memorias, pero no concede acceso al almacén. Quien llame sigue necesitando el privilegio READ MEMORY STORE o WRITE MEMORY STORE para abrirlo. Ver Control de acceso a la memoria.

Warning

El alcance es el límite de aislamiento entre usuarios, pero no es un control de acceso. La entidad principal del servicio de la aplicación puede leer todos los ámbitos, por lo que debe proteger sus credenciales en consecuencia.

Lo que el agente guarda y recuerda

La memoria gestionada proporciona el almacenamiento de memoria y las APIs para leer y escribir entradas. Tu aplicación controla qué guarda el agente, cuándo recupera memoria y cómo utiliza los resultados.

Define este comportamiento en el mensaje del sistema del agente: indica al agente qué información permanente debe guardar y cuándo debe recuperarla. La managed-memory habilidad y las plantillas mantienen este mensaje del sistema en una constante denominada MEMORY_INSTRUCTIONS. El alcance se configura por separado en código de aplicación confiable y nunca es elegido por el modelo.

Ajusta la redacción a tu estrategia de alcance. A continuación se muestra un ejemplo de la estrategia por usuario:

You have durable, cross-session memory about whoever (or whatever) this conversation is scoped to. Use it deliberately, not by reflex.

Recall whenever the answer is about the user or calls for personalized information — anything that might draw on preferences, decisions, or workflows they've shared before — and you don't already have it from this conversation; also list once before saving, to find the right existing topic. Don't tell the user you don't know their preferences without checking — list_memories first. Skip memory only when the answer truly doesn't depend on who's asking (general knowledge, math, coding) or you already have what you need. A `[has_contents]` entry has a body to get_memory; one without is fully captured by its description. Open a memory with get_memory before you state its specifics, and never assert a fact that isn't stored — if nothing relevant is stored, just answer without it. Don't re-list what you've already seen this turn.

Save only what will still matter in a future, unrelated conversation — a stable preference, fact, decision, or ongoing project the user actually stated or decided. Don't save your own suggestions or guesses, passing chatter, secrets, or anything scoped to this chat ("for now", a one-off label).
- Write each memory so it stands on its own out of context, under one broad, stable /memories/... topic per subject with the specifics inside it.
- Check the list first and update_memory an existing topic instead of minting a near-duplicate.
- For a very broad question that touches many memories, summarize from the list's descriptions; reserve get_memory for the specific entry you actually need.
- If the user's info changes or contradicts what's stored, update or replace it rather than keeping both — but don't rewrite a memory that already says the same thing.
- delete_memory what's stale.
- Briefly tell the user whenever you save, update, or delete.

Empieza con las habilidades de memoria gestionada

La forma más fácil de añadir memoria gestionada a un agente es la función managed-memory Claude Code. La función se encarga de toda la configuración por ti y funciona tanto con el SDK de agentes de OpenAI como con LangGraph.

Incorpora la habilidad a tu proyecto de una de estas dos formas:

Utilizar una plantilla

La habilidad se incluye en las plantillas de aplicaciones de Databricks. Crea un nuevo agente a partir de una de las plantillas de agente; encontrarás la habilidad en .claude/skills/managed-memory/.

1. Clone el repositorio de plantillas:

   git clone https://github.com/databricks/app-templates.git
   

2. Explora app-templates y selecciona una plantilla de agente con la que empezar. Por ejemplo, para usar la plantilla del SDK de agentes de OpenAI:

   cd app-templates/agent-openai-agents-sdk
   

   Note

   En el caso de las plantillas de aplicación «avanzadas», después de realizar la implementación, debe conceder a la entidad de servicio de la aplicación los privilegios de Lakebase Postgres; de lo contrario, la inicialización de la sesión devolverá un error 502.

3. Una vez que la función forme parte de tu proyecto, describe lo que quieres y tu asistente de programación se encargará del resto:

   Tip

   Add Databricks managed long-term memory to my agent.
   

Adición de la aptitud a un proyecto existente

Si ya tiene un proyecto de agente, agréguele la habilidad.

1. Cree el directorio de habilidades si no existe:

   mkdir -p .claude/skills/managed-memory
   

2. Descargue el archivo SKILL.md del directorio de habilidades managed-memory y guárdelo en .claude/skills/managed-memory/.

3. Una vez que la función forme parte de tu proyecto, describe lo que quieres y tu asistente de programación se encargará del resto:

   Tip

   Add Databricks managed long-term memory to my agent.
   

Creación y uso manual de un almacén de memoria

En esta sección se muestra cómo crear y usar un almacén de memoria sin la función managed-memory Claude Code.

En el ejemplo siguiente se configura la memoria administrada para un agente de soporte al cliente que almacena las preferencias de un usuario y las recupera en una conversación posterior.

1. Genere un token de OAuth mediante la CLI de Databricks para llamar a las API:

   databricks auth login --host ${DATABRICKS_HOST}
   databricks auth token
   

2. Cree un almacén de memoria para almacenar los recuerdos del agente:

   curl -X POST "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "support_agent_memory",
       "catalog_name": "main",
       "schema_name": "default",
       "description": "Long-term memory for the customer support agent"
     }'
   

3. Escriba una entrada de memoria después de que el agente aprenda algo sobre un usuario. El scope particiona la entrada para un solo usuario. Use el contents campo para el texto de memoria completa y description como resumen corto que mejore la recuperación:

   curl -X POST \
     "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.support_agent_memory/entries?scope=user-123" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "path": "/memories/preferences.md",
       "contents": "Prefers email communication. Timezone: PST. Has an Enterprise subscription.",
       "description": "User 123 communication preferences and account details"
     }'
   

4. Buscar en las entradas de memoria de ese usuario en una conversación posterior para recuperar lo que el agente ha aprendido:

   curl -X POST \
     "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.support_agent_memory/entries:search" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "scope": "user-123",
       "query": "communication preferences"
     }'
   

Para obtener la API REST completa, incluidos los puntos de conexión, los campos de solicitud y los campos de respuesta, consulte Referencia de memory API.

Añadir memoria a un agente con conversaciones

El flujo de trabajo REST anterior llama directamente a las API del almacén de memoria y de entradas. Cuando cree un agente en un endpoint de servicio de modelos de Azure Databricks, conecte en su lugar un almacén de memoria a una conversación con el cliente compatible con OpenAI del SDK databricks-openai.

Una conversación es un estado de conversación compatible con OpenAI —el historial acumulado de mensajes y llamadas a herramientas—, respaldado por un almacén de memoria y vinculado a un único ámbito. Reutilice la misma conversación en distintas solicitudes para que el agente recuerde interacciones anteriores.

1. Asigna un almacén de memoria existente y un ámbito a una nueva conversación. memory_store.name es el nombre de tres niveles del almacén, y scope divide el estado de la conversación, normalmente por usuario final:

   from databricks.sdk import WorkspaceClient
   from databricks_openai import DatabricksOpenAI
   
   workspace_client = WorkspaceClient()
   user_id = str(workspace_client.current_user.me().id)
   
   client = DatabricksOpenAI(workspace_client=workspace_client, use_ai_gateway=True)
   
   conversation = client.conversations.create(
       extra_body={
           "memory_store": {"name": "main.default.support_agent_memory"},
           "scope": {"kind": "user", "value": user_id},
       },
   )
   

2. Pase el identificador de conversación a responses.create. El agente lee y escribe el estado de la conversación en el almacén de memoria asignado bajo ese ámbito:

   response = client.responses.create(
       model="databricks-gpt-5-2",
       conversation=conversation.id,
       input=[{"type": "message", "role": "user", "content": "What is the average NYC taxi price?"}],
       stream=True,
   )
   
   for event in response:
       if event.type == "response.output_text.delta":
           print(event.delta, end="", flush=True)
   

3. Vuelva a usar el mismo identificador de conversación en las solicitudes posteriores para que el agente recuerde los turnos anteriores. No cree una nueva conversación por turno:

   followup = client.responses.create(
       model="databricks-gpt-5-2",
       conversation=conversation.id,
       input=[{"type": "message", "role": "user", "content": "Restate the average taxi price you found, and how it was calculated."}],
       stream=True,
   )
   
   for event in followup:
       if event.type == "response.output_text.delta":
           print(event.delta, end="", flush=True)
   

Para consultar los endpoints de conversación y los campos de solicitud, consulte APIs de conversaciones.

Control de acceso a memoria

Los almacenes de memoria son elementos protegibles de Unity Catalog. Los privilegios siguientes controlan el acceso:

Privilegio	Se aplica a	Description
CREATE MEMORY STORE	Esquema principal	Cree nuevos almacenes de memoria en un esquema.
READ MEMORY STORE	Almacén de memoria	Lea los metadatos de un almacén de memoria y sus entradas.
WRITE MEMORY STORE	Almacén de memoria	Crear, actualizar y eliminar entradas de memoria en un almacén.
MANAGE	Almacén de memoria	Actualice o elimine el propio almacén de memoria. Conceda permisos a otros usuarios.
USE SCHEMA	Esquema principal	Enumerar los almacenes de memoria en un esquema.

Implementar memoria a corto plazo

Las API de entradas de memoria ofrecen memoria a largo plazo como herramientas que tu agente puede usar. Para proporcionar a su agente memoria a corto plazo administrada en una sesión, Databricks recomienda enlazar el almacén de memoria a una conversación. También puede:

• Mantenga la memoria de sesión de su framework de agentes, como el parámetro session= de OpenAI o un checkpointer de LangGraph.
• Use la memoria autogestionada del agente como almacén del historial de conversaciones.

Recomendaciones de seguridad

Azure Databricks proporciona el almacén regulado, el cifrado, los primitivos de aislamiento y la pista de auditoría. Como desarrollador de aplicaciones, Databricks recomienda lo siguiente:

• Utilice el ámbito predeterminado por usuario (user_client) a menos que tenga un motivo concreto para dividirlo de otro modo (por ejemplo, memoria por proyecto o por cuenta).
• Otorga el mínimo de privilegios: solo la entidad de servicio de tu agente necesita WRITE MEMORY STORE. Conceda READ MEMORY STORE concesiones limitadas y evite concesiones amplias a usuarios humanos o grupos grandes.
• Protege las credenciales de la entidad de servicio de la aplicación: son la clave para acceder al plano de datos del almacén. Tratarlo como cualquier credencial de servicio de alto valor: use tokens de corta duración, evite registrarlo y agregue defensas SSRF a la aplicación.

Limitations

• Las entradas de memoria solo proporcionan memoria a largo plazo. Para obtener la diferencia entre la memoria a corto y largo plazo, consulte Memoria a corto y largo plazo.
• Los almacenes de memoria y las entradas se crean y administran solo a través de la API REST del catálogo de Unity; no hay ningún SDK de Python para estas API. Para usar un almacén de memoria de un agente, conéctelo a una conversación con el cliente compatible con OpenAI. Consulte Cómo añadir memoria a un agente con conversaciones.

Pasos siguientes

• Referencia de la API de memoria