Guía de inicio rápido de la API de Agent Platform Memory Bank

Agent Platform Memory Bank te permite hacer llamadas a la API directamente a Sessions y Memory Bank con el SDK de Agent Platform. Usa el SDK de la plataforma de agentes si no quieres que un framework de agentes coordine las llamadas por ti o si quieres integrar Sessions y Memory Bank con frameworks de agentes que no sean el Kit de desarrollo de agentes (ADK).

En este documento, se muestra cómo crear, subir, recuperar y quitar recuerdos con llamadas a la API.

Para la guía de inicio rápido con el ADK, consulta Guía de inicio rápido de Memory Bank con el ADK.

Antes de comenzar

Para completar los pasos que se muestran en este instructivo, primero debes seguir los pasos que se indican en Configura Memory Bank.

Genera recuerdos con las sesiones de Agent Platform

Después de configurar las sesiones de la plataforma del agente y Memory Bank, puedes crear sesiones y agregarles eventos. Los recuerdos se generan como hechos a partir de la conversación del usuario con el agente, de modo que estén disponibles para futuras interacciones del usuario. Para obtener más información, consulta Genera recuerdos y Recupera recuerdos.

Crea una sesión con un ID de usuario opaco. Todos los recuerdos generados a partir de esta sesión se etiquetan automáticamente con el alcance {"user_id": "USER_ID"}, a menos que proporciones un alcance de forma explícita cuando generes recuerdos.
```
import vertexai

client = vertexai.Client(
project="PROJECT_ID",
location="LOCATION"
)

# This assumes that you already have an Agent Platform instance. If you don't,
# you can create one using `agent_engine = client.agent_engines.create()`.
session = client.agent_engines.sessions.create(
# The name can be fetched using `agent_engine.api_resource.name`.
name="AGENT_ENGINE_NAME",
user_id="USER_ID"
)
```
Reemplaza lo siguiente:
- PROJECT_ID: ID del proyecto
- LOCATION: Tu región. Consulta las regiones admitidas para Memory Bank.
- AGENT_ENGINE_NAME: Es el nombre de la instancia de Agent Platform que creaste o de una instancia existente de Agent Platform. El nombre debe tener el siguiente formato: projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}.
- USER_ID: Es un identificador para tu usuario. Todos los recuerdos generados a partir de esta sesión se indexan automáticamente según el alcance {"user_id": "USER_ID"}, a menos que proporciones un alcance de forma explícita cuando generes recuerdos.

Sube eventos a tu sesión de forma iterativa. Los eventos pueden incluir cualquier interacción entre el usuario, el agente y las herramientas. La lista ordenada de eventos representa el historial de conversaciones de tu sesión. Este historial de conversación se usa como material de referencia para generar recuerdos para ese usuario en particular.

import datetime

client.agent_engines.sessions.events.append(
name=session.response.name,
author="user",  # Required by Sessions.
invocation_id="1",  # Required by Sessions.
timestamp=datetime.datetime.now(tz=datetime.timezone.utc),  # Required by Sessions.
config={
  "content": {
    "role": "user",
    "parts": [{"text": "hello"}]
  }
}
)

Para generar recuerdos a partir de tu historial de conversaciones, activa una solicitud de generación de recuerdos para la sesión:

client.agent_engines.memories.generate(
name=agent_engine.api_resource.name,
vertex_session_source={
  # `session` should have the format "projects/.../locations/.../reasoningEngines/.../sessions/...".
"session": session.response.name
},
# Optional when using Sessions. Defaults to {"user_id": session.user_id}.
scope=SCOPE
)

Reemplaza lo siguiente:

(Opcional) SCOPE: Es un diccionario que representa el alcance de los recuerdos generados, con un máximo de 5 pares clave-valor y sin caracteres *. Por ejemplo, {"session_id": "MY_SESSION"}. Solo se consideran para la consolidación los recuerdos con el mismo alcance. Si no se proporciona, se usa {"user_id": session.user_id}.

Cómo subir recuerdos

Como alternativa a generar recuerdos con diálogo sin procesar, puedes subir recuerdos o hacer que tus agentes los agreguen directamente con GenerateMemories con hechos preextraídos. En lugar de que Memory Bank extraiga información de tu contenido, tú proporcionas directamente los datos que se deben almacenar sobre tu usuario.

Para garantizar la coherencia con los recuerdos generados, intenta escribir hechos extraídos previamente con la misma perspectiva que configuraste para el alcance determinado. De forma predeterminada, los recuerdos se generan en primera persona (por ejemplo, I am a software engineer).

client.agent_engines.memories.generate(
    name=agent_engine.api_resource.name,
    direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
    scope=SCOPE
)

Reemplaza lo siguiente:

FACT: Es el hecho extraído previamente que se debe consolidar con los recuerdos existentes. Puedes proporcionar hasta 5 hechos preextraídos en una lista como la siguiente:
```
{"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}
```
SCOPE: Es un diccionario que representa el alcance de los recuerdos generados. Por ejemplo, {"session_id": "MY_SESSION"} Solo se consideran para la consolidación los recuerdos con el mismo alcance.

Como alternativa, puedes usar CreateMemory para subir recuerdos sin usar Memory Bank para la extracción o consolidación de recuerdos.

memory = client.agent_engines.memories.create(
    name=agent_engine.api_resource.name,
    fact="This is a fact.",
    scope={"user_id": "123"}
)

"""
Returns an AgentEngineMemoryOperation containing the created Memory like:

AgentEngineMemoryOperation(
  done=True,
  metadata={
    "@type': 'type.googleapis.com/google.cloud.aiplatform.v1beta1.CreateMemoryOperationMetadata",
    "genericMetadata": {
      "createTime": '2025-06-26T01:15:29.027360Z',
      "updateTime": '2025-06-26T01:15:29.027360Z'
    }
  },
  name="projects/.../locations/us-central1/reasoningEngines/.../memories/.../operations/...",
  response=Memory(
    create_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC)),
    fact="This is a fact.",
    name="projects/.../locations/us-central1/reasoningEngines/.../memories/...",
    scope={
      "user_id": "123"
    },
    update_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC))
  )
)
"""

Cómo recuperar y usar recuerdos

Puedes recuperar recuerdos para tu usuario y agregarlos a las instrucciones del sistema para darle al LLM acceso a tu contexto personalizado.

Para obtener más información sobre cómo recuperar recuerdos con un método basado en el alcance, consulta Cómo recuperar recuerdos.

# Retrieve all memories for User ID 123.
retrieved_memories = list(
    client.agent_engines.memories.retrieve(
        name=agent_engine.api_resource.name,
        scope={"user_id": "123"}
    )
)

Puedes usar jinja para convertir tus recuerdos estructurados en una instrucción:


from jinja2 import Template

template = Template("""
<MEMORIES>
Here is some information about the user:
{% for retrieved_memory in data %}* {{ retrieved_memory.memory.fact }}
{% endfor %}</MEMORIES>
""")

prompt = template.render(data=retrieved_memories)

"""
Output:

<MEMORIES>
Here is some information about the user:
* This is a fact
</MEMORIES>
"""

Cómo quitar recuerdos

Existen varias formas de borrar recuerdos de tu instancia de Memory Bank, según cómo quieras seleccionar los recuerdos que se deben quitar.

Quitar por nombre del recurso

Si sabes exactamente qué recurso de memoria quieres quitar, puedes borrar una memoria específica con su nombre de recurso:

client.agent_engines.memories.delete(
    name=MEMORY_NAME,
    config={
        # Set to false (default) if you want to delete the memory asynchronously.
        "wait_for_completion": True
    }
)

Reemplaza lo siguiente:

MEMORY_NAME: Es el nombre de la memoria que se borrará. El nombre debe tener el siguiente formato: projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}/memories/{your memory}. Puedes encontrar el nombre del recuerdo recuperando recuerdos.

Quitar por criterios

Puedes usar la eliminación basada en criterios para quitar uno o más recuerdos. Solo se borrarán los recuerdos que coincidan con los filtros proporcionados. Debes especificar al menos uno de los atributos filter (se aplica a los campos del sistema) o filter_groups (se aplica a los campos de metadatos).

operation = client.agent_engines.memories.purge(
    name=agent_engine.api_resource.name,
    # Specify at least one of `filter` or `filter_groups`.
    filter="FILTER_STRING",
    filter_groups=FILTER_GROUPS,
    # Set to false (default) if you want to stage but not execute the purge operation.
    force=True,
    config={
        # Set to false (default) if you want to purge memories asynchronously.
        "wait_for_completion": True
    }
)

Reemplaza lo siguiente:

FILTER_STRING: Es una cadena que usa la sintaxis de la EBNF para filtrar los campos del sistema. Los campos del sistema incluyen create_time, update_time, fact y topics. Para obtener más información sobre el filtrado en función de los campos del sistema, consulta la sección Filtrar por campos de metadatos en la página Recuperar recuerdos.
FILTER_GROUPS: Es una lista de diccionarios o de objetos para filtrar los metadatos de la memoria. Para obtener más información sobre el filtrado en función de los campos de metadatos, consulta la sección Filtra por campos del sistema en la página Recupera recuerdos.

La operación devolverá un recuento de cuántos recuerdos se borraron (si es force=True) o se borrarían si se ejecutara la operación (si es force=False).

print(operation.response.purge_count)

Por ejemplo, puedes borrar definitivamente todos los recuerdos que pertenecen a un alcance para user_id "123":

operation = client.agent_engines.memories.purge(
    name=agent_engine.api_resource.name,
    filter="scope.user_id=\"123\""
    force=True
)

Quitar por significado semántico

Durante la generación de memoria, Memory Bank decidirá si crear, actualizar o borrar recuerdos según el contenido de la información recién extraída y los recuerdos existentes. Es posible que se borre una memoria si la información nueva la contradice o si el contenido extraído le indica a Memory Bank que olvide un sujeto (en el caso del tema de memoria EXPLICIT_INSTRUCTIONS).

Por ejemplo, la siguiente solicitud borraría los recuerdos existentes que contienen información sobre las preferencias dietéticas, si existen para el scope determinado:

from google import genai

client.agent_engines.memories.generate(
    name=agent_engine.api_resource.name,
    direct_contents_source={
      "events": [{
        "content": genai.types.Content(
          role="user",
          parts=[
            genai.types.Part.from_text(text="Forget my dietary preferences.")
          ]
        )
      }]
    },
    scope={...}
)

Realiza una limpieza

Para limpiar todos los recursos que se usaron en este proyecto, puedes borrar el proyecto que usaste para la guía de inicio rápido. Google Cloud

De lo contrario, puedes borrar los recursos individuales que creaste en este instructivo de la siguiente manera:

Usa la siguiente muestra de código para borrar la instancia de Agent Platform, lo que también borrará cualquier sesión o memoria asociada con la instancia de Agent Platform.
```
agent_engine.delete(force=True)
```
Borra los archivos creados de forma local.

¿Qué sigue?

Guía de inicio rápido

Inicio rápido con el Kit de desarrollo de agentes

Comienza a usar el Kit de desarrollo de agentes (ADK).

Guía de inicio rápido de la API de Agent Platform Memory Bank Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Antes de comenzar

Genera recuerdos con las sesiones de Agent Platform

Cómo subir recuerdos

Cómo recuperar y usar recuerdos

Cómo quitar recuerdos

Quitar por nombre del recurso

Quitar por criterios

Quitar por significado semántico

Realiza una limpieza

¿Qué sigue?

Inicio rápido con el Kit de desarrollo de agentes

Guía de inicio rápido de la API de Agent Platform Memory Bank