Guía de inicio rápido del SDK de Vertex AI Agent Engine

En este tutorial se muestra cómo hacer llamadas a la API directamente a las sesiones y al banco de memoria de Vertex AI Agent Engine mediante el SDK de Vertex AI Agent Engine. Usa el SDK de Vertex AI Agent Engine si no quieres que un framework de agentes orqueste las llamadas por ti o si quieres integrar Sessions y Memory Bank con frameworks de agentes que no sean Agent Development Kit (ADK).

Para consultar la guía de inicio rápido sobre ADK, consulta Guía de inicio rápido con Agent Development Kit.

En este tutorial se siguen estos pasos:

  1. Crea recuerdos con las siguientes opciones:
  2. Recuperar recuerdos.
  3. Liberar espacio.

Antes de empezar

Para completar los pasos que se muestran en este tutorial, primero debes seguir los pasos de Configuración de Memory Bank.

Generar recuerdos con sesiones de Vertex AI Agent Engine

Después de configurar las sesiones y el banco de memoria de Vertex AI Agent Engine, puedes crear sesiones y añadirles eventos. Las memorias se generan como datos de la conversación del usuario con el agente para que estén disponibles en futuras interacciones. Para obtener más información, consulta Generar recuerdos y Obtener recuerdos.

  1. Crea una sesión con un ID de usuario opaco. Los recuerdos generados a partir de esta sesión se etiquetan automáticamente con el ámbito {"user_id": "USER_ID"}, a menos que proporciones un ámbito explícitamente al generar recuerdos.

    import vertexai

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

session = client.agent_engines.sessions.create(
  name=AGENT_ENGINE_NAME,
  user_id="USER_ID"
)

    Haz los cambios siguientes:

    • PROJECT_ID: tu ID de proyecto.

    • LOCATION: tu región. Consulta las regiones admitidas para Banco de recuerdos.

    • AGENT_ENGINE_NAME: el nombre de la instancia de Vertex AI Agent Engine que has creado o de una instancia de Vertex AI Agent Engine que ya tengas. El nombre debe tener el siguiente formato: projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}.

    • USER_ID: identificador de tu usuario. Los recuerdos generados a partir de esta sesión se etiquetan automáticamente con el ámbito {"user_id": "USER_ID"}, a menos que proporciones un ámbito explícitamente al generar recuerdos.

  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 conversaciones se usa como material de origen para generar recuerdos de ese usuario concreto.

    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 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 Agent Engine Sessions. Defaults to {"user_id": session.user_id}.
  scope=SCOPE
)

Haz los cambios siguientes:

  • (Opcional) SCOPE: diccionario que representa el ámbito de las memorias generadas, con un máximo de 5 pares clave-valor y sin caracteres *. Por ejemplo, {"session_id": "MY_SESSION"}. Solo se tienen en cuenta para la consolidación los recuerdos que tengan el mismo ámbito. Si no se proporciona, se usa {"user_id": session.user_id}.

Subir recuerdos

Como alternativa a generar recuerdos usando el diálogo sin procesar, puedes subir recuerdos o pedirles a tus agentes que los añadan directamente usando 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. Te recomendamos que escribas datos sobre los usuarios 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
)

Haz los cambios siguientes:

  • FACT: el hecho preextraído que se debe consolidar con los recuerdos existentes. Puedes proporcionar hasta 5 datos preextraídos en una lista como la siguiente:

    {"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}

  • SCOPE: diccionario que representa el ámbito de los recuerdos generados. Por ejemplo, {"session_id": "MY_SESSION"}. Solo se tienen en cuenta para la consolidación los recuerdos que tengan el mismo ámbito.

También puedes usar CreateMemory para subir recuerdos sin usar el banco de recuerdos para extraerlos o consolidarlos.

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

Recuperar y usar recuerdos

Puedes recuperar recuerdos de tu usuario e incluirlos en las instrucciones del sistema para que el LLM tenga acceso a tu contexto personalizado.

Para obtener más información sobre cómo recuperar recuerdos mediante un método basado en el ámbito, consulta 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 petició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>
"""

Eliminar recuerdos

Puedes eliminar una memoria específica con su nombre de recurso:

client.agent_engines.memories.delete(name=MEMORY_NAME)

Haz los cambios siguientes:

  • MEMORY_NAME: el nombre de la memoria que se va a eliminar. El nombre debe tener el siguiente formato: projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}/memories/{your memory}. Puedes consultar el nombre del recuerdo obteniendo los recuerdos.

Limpieza

Para limpiar todos los recursos utilizados en este proyecto, puedes eliminar el proyecto Google Cloud que has usado en la guía de inicio rápido.

De lo contrario, puedes eliminar los recursos que has creado en este tutorial de la siguiente manera:

  1. Usa el siguiente código de ejemplo para eliminar la instancia de Vertex AI Agent Engine, lo que también elimina las sesiones o memorias asociadas a la instancia de Vertex AI Agent Engine.

    agent_engine.delete(force=True)

  2. Elimina los archivos creados localmente.

Siguientes pasos