Se usó la API de Cloud Translation para traducir esta página.

Guía de inicio rápido con la API de REST

En este instructivo, se muestra cómo realizar llamadas a la API de REST directamente a las sesiones y al banco de memoria de Vertex AI Agent Engine para crear y usar sesiones y recuerdos a largo plazo. Usa la API de REST 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 tu instancia de Vertex AI Agent Engine para acceder a las sesiones y al banco de memoria de Vertex AI Agent Engine.
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 que el banco de memoria de Vertex AI Agent Engine genere 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 configurar tu proyecto y tu entorno.

Configura tu proyecto

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Enable the API

Si seleccionaste un proyecto, asegúrate de tener el rol de IAM de usuario de Vertex AI (roles/aiplatform.user) en el proyecto.

Autentica en Vertex AI

Para usar las muestras de Python de esta página en un entorno de desarrollo local, instala e inicializa gcloud CLI y, luego, configura las credenciales predeterminadas de la aplicación con tus credenciales de usuario.

Install the Google Cloud CLI.
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
To initialize the gcloud CLI, run the following command:
```
gcloud init
```
If you're using a local shell, then create local authentication credentials for your user account:
```
gcloud auth application-default login
```
You don't need to do this if you're using Cloud Shell.

If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

Si deseas obtener más información, consulta Configura ADC para un entorno de desarrollo local en la Google Cloud documentación de autenticación.

Importa las bibliotecas

Instala el SDK de Vertex AI:

pip install google-cloud-aiplatform>=1.100.0

Crea tu instancia de Vertex AI Agent Engine

Para acceder a las sesiones de Vertex AI Agent Engine y al banco de memoria de Vertex AI Agent Engine, primero debes crear una instancia de Vertex AI Agent Engine. No es necesario que implementes un agente para comenzar a usar Sessions y Memory Bank. Sin la implementación del agente, la creación de una instancia de Vertex AI Agent Engine debería tardar unos segundos.

import vertexai

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

agent_engine = client.agent_engines.create()

Reemplaza lo siguiente:

PROJECT_ID: ID del proyecto
LOCATION: Tu región. Solo se admite us-central1 para el banco de memoria de Vertex AI Agent Engine.

Genera recuerdos a partir de sesiones de Vertex AI Agent Engine

Después de configurar las sesiones de Vertex AI Agent Engine y el banco de memoria, 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 Cómo generar y recuperar 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 por el alcance {"user_id": "USER_ID"}, a menos que proporciones un alcance de forma explícita cuando generes recuerdos.
```
from google.cloud import aiplatform_v1beta1

sessions_client = aiplatform_v1beta1.SessionServiceClient(
  client_options={
    "api_endpoint": "https://LOCATION-aiplatform.googleapis.com"
  },
  transport="rest"
)

session_lro = sessions_client.create_session(
  parent=AGENT_ENGINE_NAME,
  session={"user_id": "USER_ID"}
)
session_name = "/".join(session_lro.operation.name.split("/")[0:-2])
```
Reemplaza lo siguiente:
- LOCATION: Tu región. Solo se admite us-central1 para el banco de memoria de Vertex AI Agent Engine.
- 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 por 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.

event = aiplatform_v1beta1.SessionEvent(
    author="user",  # Required by Sessions.
    invocation_id="1",  # Required by Sessions.
    timestamp=datetime.now().strftime('%Y-%m-%dT%H:%M:%SZ'),  # Required by Sessions.
    content = aiplatform_v1beta1.Content(
        role="user",
        parts=[aiplatform_v1beta1.Part(text="Hello")]
    )
)

sessions_client.append_event(name=session_name, event=event)

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": session_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 CreateMemory. 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).

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

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.

¿Qué sigue?

Guía de inicio rápido del Kit de desarrollo de agentes