En este instructivo, se muestra cómo realizar llamadas a la API directamente a las sesiones y al banco de memoria de Vertex AI Agent Engine con el SDK de Vertex AI Agent Engine. Usa el SDK de Vertex AI Agent Engine 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 Agent Development Kit (ADK).
Para la guía de inicio rápido con el ADK, consulta Guía de inicio rápido con el Agent Development Kit.
En este instructivo, se siguen los siguientes pasos:
- Crea recuerdos con las siguientes opciones:
- Genera recuerdos con el banco de memoria de Vertex AI Agent Engine: Escribe sesiones y eventos en las sesiones de Vertex AI Agent Engine como fuentes para el banco de memoria de Vertex AI Agent Engine y genera recuerdos.
- Subir recuerdos directamente: Escribe tus propios recuerdos o pídele a tu agente que los cree si quieres tener control total sobre la información que se conserva.
- Recuperar recuerdos
- Realiza una limpieza.
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 Vertex AI Agent Engine
Después de configurar las sesiones y el banco de memoria de Vertex AI Agent Engine, 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 indexan automáticamente según 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" ) session = client.agent_engines.create_session( 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 Vertex AI Agent Engine que creaste o de una instancia existente de Vertex AI Agent Engine. 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 conversación de tu sesión. Este historial de conversaciones se usa como material de origen para generar recuerdos para ese usuario en particular.
import datetime client.agent_engines.append_session_event( 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.generate_memories( 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 )
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álogos 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. Te recomendamos que escribas datos sobre los usuarios en primera persona (por ejemplo, I am a software engineer).
client.agent_engines.generate_memories(
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.create_memory(
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 que el LLM tenga 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.retrieve_memories(
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 borrar recuerdos
Puedes borrar una memoria específica con su nombre de recurso:
client.agent_engines.delete_memory(name=MEMORY_NAME)
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.
Limpia
Para limpiar todos los recursos que se usaron en este proyecto, puedes borrar el proyecto 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:
Usa el siguiente muestra de código para borrar la instancia de Vertex AI Agent Engine, lo que también borrará cualquier sesión o memoria asociada con la instancia de Vertex AI Agent Engine.
agent_engine.delete(force=True)Borra los archivos creados de forma local.