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 a Memory Bank. 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 memorias 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.

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 instancia de Sessions, como se muestra en el siguiente ejemplo:

import vertexai

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

memory_bank = client.agent_engines.create()
sessions = client.agent_engines.create()

Genera memorias 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 las memorias estén disponibles para futuras interacciones del usuario. Para obtener más información, consulta Genera memorias y Recupera memorias.

  1. Crea una sesión con un ID de usuario opaco. Todas las memorias generadas a partir de esta sesión se clavean automáticamente con el alcance {"user_id": "USER_ID"}, a menos que proporciones un alcance cuando generes memorias.

    import vertexai

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

session = client.agent_engines.sessions.create(
  # The name can be fetched using `sessions.api_resource.name`.
  name="SESSIONS_NAME",
  user_id="USER_ID"
)

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el ID del proyecto.

    • LOCATION: Es tu región. Consulta las regiones compatibles con 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. Todas las memorias generadas a partir de esta sesión se clavean automáticamente con el alcance {"user_id": "USER_ID"}, a menos que proporciones un alcance de forma explícita cuando generes memorias.

  2. Sube eventos de forma iterativa a tu sesión. Los eventos pueden incluir cualquier interacción entre tu usuario, agente y herramientas. La lista ordenada de eventos representa el historial de conversaciones de tu sesión. Este historial de conversaciones se usa como material de origen para generar memorias 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"}]
    }
  }
)

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

    client.agent_engines.memories.generate(
  name=memory_bank.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 las memorias generadas, con un máximo de 5 pares clave-valor y sin * caracteres. Por ejemplo, {"session_id": "MY_SESSION"}. Solo se consideran las memorias con el mismo alcance para la consolidación. Si no se proporciona, se usa {"user_id": session.user_id}.

Sube memorias

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

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

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

Reemplaza lo siguiente:

  • FACT: Es el hecho preextraído que se debe consolidar con las memorias 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 las memorias generadas. Por ejemplo, {"session_id": "MY_SESSION"}. Solo se consideran las memorias con el mismo alcance para la consolidación.

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

memory = client.agent_engines.memories.create(
    name=memory_bank.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))
  )
)
"""

Recupera y usa memorias

Puedes recuperar memorias para tu usuario y agregarlas a las instrucciones del sistema para otorgarle al LLM acceso a tu contexto personalizado.

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

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

Puedes usar jinja para convertir tus memorias estructuradas 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>
"""

Quita memorias

Existen varias formas de borrar memorias de tu instancia de Memory Bank, según cómo quieras seleccionar qué memorias se deben quitar.

Quita por nombre de 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:

Quita por criterios

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

operation = client.agent_engines.memories.purge(
    name=memory_bank.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 EBNF para filtrar en función de 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 Filtra por campos de metadatos en la página Recupera memorias.
  • FILTER_GROUPS: Es una lista de diccionarios o 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 memorias.

La operación mostrará un recuento de cuántas memorias 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 todas las memorias que pertenecen a un alcance para user_id "123":

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

Quita por significado semántico

Durante la generación de memoria, Memory Bank decidirá si crear, actualizar o borrar memorias en función del contenido de la información recién extraída y las memorias 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 tema (en el caso del EXPLICIT_INSTRUCTIONS tema de memoria).

Por ejemplo, la siguiente solicitud borraría las memorias existentes que contienen información sobre las preferencias alimentarias, si existen para el scope determinado:

from google import genai

client.agent_engines.memories.generate(
    name=memory_bank.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={...}
)

Limpia

Para limpiar todos los recursos usados en este proyecto, puedes borrar el Google Cloud proyecto 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 la instancia de Agent Platform, que también borra cualquier sesión o memoria asociada con la instancia de Agent Platform.

    agent_engine.delete(force=True)

  2. Borra los archivos creados de forma local.

¿Qué sigue?

Guía de inicio rápido

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