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

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

Después de configurar tu agente de Agent Development Kit (ADK) para que use las sesiones y el banco de memoria de Vertex AI Agent Engine, tu agente leerá y escribirá automáticamente recuerdos y sesiones por ti.

Para la guía de inicio rápido con la API de REST, consulta Guía de inicio rápido con la API de REST.

En este instructivo, se muestra cómo puedes usar las sesiones y el banco de memoria de Vertex AI Agent Engine con el ADK para crear y usar sesiones y memorias a largo plazo:

Crea tu instancia de Vertex AI Agent Engine para acceder a las sesiones y al banco de memoria de Vertex AI Agent Engine.
Crea tu agente y ejecutor del ADK local.
Interactúa con tu agente para generar de forma dinámica recuerdos a largo plazo a los que se puede acceder en todas las sesiones.
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 Agent Development Kit y el SDK de Vertex AI:

pip install google-adk>=1.5.0
pip install google-cloud-aiplatform>=1.100.0

Configure las variables de entorno

Para usar el ADK, configura tus variables de entorno:

import os

os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "TRUE"
os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_CLOUD_LOCATION"] = "LOCATION"

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.

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 ningún código para comenzar a usar Sessions y Memory Bank. Sin la implementación de código, 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()

Crea tu agente del ADK

Cuando desarrolles tu agente de ADK, incluye una herramienta Memory, que controla cuándo se usa el servicio de memoria y cómo se incluyen los recuerdos en la instrucción. El agente de ejemplo usa PreloadMemoryTool, que siempre recupera recuerdos al comienzo de cada turno y los incluye en la instrucción del sistema:

from google import adk

agent = adk.Agent(
    model="gemini-2.0-flash",
    name='stateful_agent',
    instruction="""You are a Vehicle Voice Agent, designed to assist users with information and in-vehicle actions.

1.  **Direct Action:** If a user requests a specific vehicle function (e.g., "turn on the AC"), execute it immediately using the corresponding tool. You don't have the outcome of the actual tool execution, so provide a hypothetical tool execution outcome.
2.  **Information Retrieval:** Respond concisely to general information requests with your own knowledge (e.g., restaurant recommendation).
3.  **Clarity:** When necessary, try to seek clarification to better understand the user's needs and preference before taking an action.
4.  **Brevity:** Limit responses to under 30 words.
""",
    tools=[adk.tools.preload_memory_tool.PreloadMemoryTool()]
)

Crea un servicio de memoria VertexAiMemoryBankService, que el ejecutor del ADK usa para recuperar recuerdos.

from google.adk.memory import VertexAiMemoryBankService

agent_engine_id = agent_engine.api_resource.name.split("/")[-1]

memory_service = VertexAiMemoryBankService(
    project="PROJECT_ID",
    location="LOCATION",
    agent_engine_id=agent_engine_id
)

Crea un ejecutor de ADK, que coordina la ejecución de tus agentes, herramientas y devoluciones de llamada.

from google.adk.sessions import VertexAiSessionService

# You can use any ADK session service.
session_service = VertexAiSessionService(
    project_id="PROJECT_ID",
    location="LOCATION",
    agent_engine_id=agent_engine_id
)

app_name="APP_NAME"
runner = adk.Runner(
    agent=agent,
    app_name=app_name,
    session_service=session_service,
    memory_service=memory_service
)

def call_agent(query, session, user_id):
  content = types.Content(role='user', parts=[types.Part(text=query)])
  events = runner.run(user_id=user_id, session_id=session, new_message=content)

  for event in events:
      if event.is_final_response():
          final_response = event.content.parts[0].text
          print("Agent Response: ", final_response)

Reemplaza lo siguiente:

APP_NAME: Es el nombre de tu app del ADK.

Interactúa con el agente

Después de definir tu agente y configurar las sesiones y el banco de memoria, puedes interactuar con él.

Crea tu primera sesión. Como no hay recuerdos disponibles durante la primera sesión con un usuario, el agente no conoce ninguna preferencia del usuario, como su temperatura preferida:

Nota: Es posible que haya algunas variaciones en las respuestas del agente y del Banco de memoria según los modelos que se utilicen.
```
session = await session_service.create_session(
    app_name=app_name,
    user_id="USER_ID"
)

call_agent(
    "Can you update the temperature to my preferred temperature?",
    session.id,
    "USER_ID"
)

# Agent response: "What is your preferred temperature?"
call_agent("I like it at 71 degrees", session.id, "USER_ID")
# Agent Response:  Setting the temperature to 71 degrees Fahrenheit.
# Temperature successfully changed.
```
Reemplaza lo siguiente:
- USER_ID: Es un identificador para tu usuario. Las memorias generadas a partir de esta sesión se indexan con este identificador opaco. El alcance de los recuerdos generados se almacena como {"user_id": "USER_ID"}.

Genera recuerdos para tu sesión actual. Si Memory Bank extrae recuerdos de la conversación, se almacenan en el alcance {"user_id": USER_ID, "app_name": APP_NAME}.

session = await session_service.get_session(
    app_name=app_name,
    user_id="USER_ID",
    session_id=session.id
)
await memory_service.add_session_to_memory(session)

Crea tu segunda sesión. Si usaste PreloadMemoryTool, el agente recupera recuerdos al comienzo de cada turno para acceder a las preferencias que el usuario le comunicó anteriormente.

session = await session_service.create_session(
    app_name=app_name,
    user_id="USER_ID"
)

call_agent("Fix the temperature!", session.id, "USER_ID")
# Agent Response:  Setting temperature to 71 degrees.  Is that correct?

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 que pertenezca a ese Vertex AI Agent Engine.
```
agent_engine.delete(force=True)
```
Borra los archivos creados de forma local.

¿Qué sigue?

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