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

Puedes usar el SDK de Agent Platform para realizar llamadas a la API directamente al banco de memoria. Usa el SDK de Agent Platform si no quieres que un framework de agentes organice las llamadas por ti o si quieres integrar 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 obtener la guía de inicio rápido con ADK, consulta la guía de inicio rápido de Memory Bank con ADK.

Para ver un ejemplo de cómo usar con el SDK, ejecuta el notebook "Comienza a usar Memory Bank" en uno de los siguientes entornos:

Abrir en Colab | Abrir en Colab Enterprise | Abrir en Agent Platform Workbench | Ver en GitHub

Para ver un ejemplo de cómo usar con LangGraph, ejecuta el notebook "Comienza a usar - LangGraph" en uno de los siguientes entornos:

Abrir en Colab | Abrir en Colab Enterprise | Abrir en Agent Platform Workbench | Ver en GitHub

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. Antes de comenzar esta guía de inicio rápido, asegúrate de haber creado una instancia de Memory Bank y una de Sessions, como se muestra en el siguiente ejemplo:

import agentplatform

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

memory_bank = client.memory_banks.create()
sessions = client.runtimes.create()

Genera recuerdos con Agent Platform Sessions

Después de configurar Agent Platform Sessions, puedes crear sesiones y agregarles eventos. Luego, puedes usar Memory Bank para generar memorias 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.

Nota: También puedes proporcionar el historial de conversaciones directamente en la carga útil de GenerateMemories con la fuente de contenido directa.

1. Crea una sesión con un ID de usuario opaco. Cualquier memoria que se genere a partir de esta sesión se asocia automáticamente con el permiso {"user_id": "USER_ID"}, a menos que proporciones un permiso de forma explícita cuando generes memorias.

   import agentplatform
   
   client = agentplatform.Client(
     project="PROJECT_ID",
     location="LOCATION"
   )
   
   session = client.sessions.create(
     # The name can be fetched using `sessions.name`.
     name="SESSIONS_NAME",
     user_id="USER_ID"
   )
   

   Reemplaza lo siguiente:

   • PROJECT_ID: ID del proyecto

   • LOCATION: Tu región. Consulta las regiones admitidas para Memory Bank.

   • SESSIONS_NAME: Es el nombre de la instancia de Sessions que creaste o una instancia de Sessions existente. 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. Cualquier memoria que se genere a partir de esta sesión se clavea automáticamente con el permiso {"user_id": "USER_ID"}, a menos que proporciones un permiso de forma explícita cuando generes memorias.

2. 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 memorias para ese usuario en particular.

   import datetime
   
   client.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"}]
       }
     }
   )
   

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

   client.memory_banks.memories.generate(
     name=memory_bank.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 las memorias con el mismo permiso. Si no se proporciona, se usa {"user_id": session.user_id}.

Sube recuerdos

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

Para garantizar la coherencia con los recuerdos generados, intenta escribir los datos 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.memory_banks.memories.generate(
    name=memory_bank.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 extraídos previamente 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 las memorias con el mismo permiso.

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

Precaución: Las memorias subidas con CreateMemory no se consolidarán con las existentes, por lo que puedes terminar con memorias duplicadas para el mismo alcance. Las memorias creadas están disponibles para la búsqueda de similitud y se pueden consolidar para solicitudes futuras cuando se generan memorias.

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

"""
Returns a MemoryOperation containing the created Memory like:

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

Recupera y usa recuerdos

Puedes recuperar recuerdos de tu usuario y, luego, incluirlos en las instrucciones del sistema para que el LLM acceda a tu contexto personalizado.

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

# Retrieve memories for User ID 123.
retrieved_memories = client.memory_banks.memories.retrieve(
    name=memory_bank.name,
    scope={"user_id": "123"}
).page

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 de recurso

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

client.memory_banks.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}. Para encontrar el nombre de la memoria, recupera las memorias.

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 campos filter (aplicado a los campos del sistema) o filter_groups (aplicado a los campos de metadatos).

operation = client.memory_banks.memories.purge(
    name=memory_bank.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 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 cómo filtrar por campos del sistema, consulta la sección Filtra por campos de metadatos en la página Recupera recuerdos.
• FILTER_GROUPS: Es una lista de diccionarios u objetos para filtrar en función de 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 force=True) o se borrarían si se ejecutara la operación (si force=False).

print(operation.response.purge_count)

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

operation = client.memory_banks.memories.purge(
    name=memory_bank.name,
    filter="scope.user_id=\"123\"",
    force=True
)

Quita por significado semántico

Nota: El comportamiento esperado puede variar según los temas de memoria y los ejemplos de pocos intentos que hayas configurado.

Durante la generación de recuerdos, Memory Bank decidirá si crear, actualizar o borrar recuerdos en función del contenido de la información recién extraída y de los recuerdos existentes. Se puede borrar una memoria si la información nueva la contradice o si el contenido extraído le indica al Memory Bank que olvide un tema (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 alimentarias, si existen para el scope determinado:

from google import genai

client.memory_banks.memories.generate(
    name=memory_bank.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 de Google Cloud que usaste para la guía de inicio rápido.

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

1. Usa la siguiente muestra de código para borrar el banco de memoria de Agent Platform y Agent Runtime en las instancias de Gemini Enterprise Agent Platform:

   client.memory_banks.delete(name=memory_bank.name, force=True)
   client.runtimes.delete(name=sessions.name, force=True)
   

2. Borra los archivos creados de forma local.

¿Qué sigue?

Guía de inicio rápido

Guía de inicio rápido con el Kit de desarrollo de agentes

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