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

Versión preliminar

Esta función está sujeta a las “Condiciones de la Oferta de la Fase Previa a la DG” en la sección Condiciones del Servicio Generales de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles sin modificaciones y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Después de configurar tu agente del Kit de desarrollo de agentes (ADK) para que use Memory Bank, el agente coordina las llamadas a Memory Bank para administrar las memorias a largo plazo por ti.

En este instructivo, se muestra cómo puedes usar Memory Bank con el ADK para administrar recuerdos a largo plazo:

1. Crea tu agente y ejecutor del ADK local. Los ejecutores del ADK conectan tu agente a los servicios que proporcionan administración de sesión y memoria.

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

3. Realiza una limpieza.

Para realizar llamadas directamente a Memory Bank sin la organización del ADK, consulta la Guía de inicio rápido con el SDK de Agent Engine. Usar el SDK de Agent Engine es útil para comprender cómo Memory Bank genera recuerdos o para inspeccionar el contenido de Memory Bank.

Importante: El ADK usa principalmente funciones asíncronas. Si ejecutas código en un notebook como Colab, puedes await funciones asíncronas directamente porque ya se está ejecutando un bucle de eventos. Si ejecutas este código como una secuencia de comandos estándar de Python, debes incluir tus llamadas a funciones asíncronas con asyncio.run() para crear y administrar un bucle de eventos que ejecute tus funciones asíncronas. De lo contrario, es posible que veas un error como 'await' outside function.

Para ver un ejemplo del uso de Memory Bank con el ADK, ejecuta el notebook “Comienza a usar Memory Bank en el ADK” en uno de los siguientes entornos:

Abrir en Colab | Abrir en Colab Enterprise | Abrir en Vertex AI Workbench | Ver en GitHub

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.

Nota: Si ya tienes un proyecto Google Cloud , puedes seguir la guía con el número y la ubicación de tu proyecto usando las instrucciones de "Google Cloud Project". Si es la primera vez que usas Google Cloud Vertex AI, puedes registrarte con tu cuenta de Gmail para obtener un proyecto en modo Exprés y una clave de API sin facturación a través del registro en modo Exprés y, luego, seguir la guía con las instrucciones de "Modo Exprés de Vertex AI".

Configure las variables de entorno

Para usar el ADK, configura tus variables de entorno:

Google Cloud Proyecto

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. Consulta las regiones compatibles con Memory Bank.

Modo Express de Vertex AI

import os

os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "TRUE"
os.environ["GOOGLE_API_KEY"] = "API_KEY"

Reemplaza lo siguiente:

• API_KEY: Es tu clave de API del modo Express de Vertex AI. Si es la primera vez que usas Google Cloud, puedes registrarte con tu cuenta de Gmail para obtener una clave de API a través del Registro en modo exprés.

Crea tu agente del ADK

1. Cuando desarrolles tu agente del ADK, incluye una herramienta Memory que controle cuándo el agente recupera recuerdos y cómo se incluyen 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()]
   )
   

2. Crea un servicio de memoria VertexAiMemoryBankService, que el ejecutor del ADK usa para recuperar recuerdos. Este paso es opcional si usas la plantilla del ADK de Agent Engine en lugar de definir tu propio entorno de ejecución del ADK. Si deseas configurar el comportamiento de tu instancia de Memory Bank, consulta la guía de configuración.

   Google Cloud Proyecto

   from google.adk.memory import VertexAiMemoryBankService
   import vertexai
   
   client = vertexai.Client(
     project="PROJECT_ID",
     location="LOCATION"
   )
   # If you don't have an Agent Engine instance already, create an Agent Engine
   # Memory Bank instance using the default configuration.
   agent_engine = client.agent_engines.create()
   
   # Optionally, print out the Agent Engine resource name. You will need the
   # resource name to interact with your Agent Engine instance later on.
   print(agent_engine.api_resource.name)
   
   agent_engine_id = agent_engine.api_resource.name.split("/")[-1]
   
   memory_service = VertexAiMemoryBankService(
       project="PROJECT_ID",
       location="LOCATION",
       agent_engine_id=agent_engine_id
   )
   

   Reemplaza lo siguiente:

   • PROJECT_ID: ID del proyecto
   • LOCATION: Tu región. Consulta las regiones compatibles con Memory Bank.

   Modo Express de Vertex AI

   from google.adk.memory import VertexAiMemoryBankService
   import vertexai
   
   client = vertexai.Client(
     api_key="API_KEY",
   )
   # If you don't have an Agent Engine instance already, create an Agent Engine
   # Memory Bank instance using the default configuration.
   agent_engine = client.agent_engines.create()
   
   # Optionally, print out the Agent Engine resource name. You will need the
   # resource name to interact with your Agent Engine instance later on.
   print(agent_engine.api_resource.name)
   
   agent_engine_id = agent_engine.api_resource.name.split("/")[-1]
   
   # Make sure your environment variables are set. VertexAiMemoryBankService
   # will read your api key from the GOOGLE_API_KEY environment variable.
   memory_service = VertexAiMemoryBankService(
       agent_engine_id=agent_engine_id
   )
   

   Reemplaza lo siguiente:

   • API_KEY: Es tu clave de API del modo Express de Vertex AI. Si es la primera vez que usas Google Cloud, puedes registrarte con tu cuenta de Gmail para obtener una clave de API a través del Registro en modo exprés.

   VertexAiMemoryBankService es un wrapper del ADK alrededor de Memory Bank que se define con BaseMemoryService del ADK y usa una interfaz diferente a la del SDK de Agent Engine. Puedes usar el SDK de Agent Engine para realizar llamadas directas a la API de Memory Bank. La interfaz VertexAiMemoryBankService incluye lo siguiente:

   • memory_service.add_session_to_memory, que activa una solicitud GenerateMemories a Memory Bank con el adk.Session proporcionado como contenido fuente. El ejecutor del ADK no coordina las llamadas a este método. Si deseas automatizar la generación de recuerdos con el ADK, debes definir tus propias funciones de devolución de llamada.

   • memory_service.search_memory, que activa una solicitud de RetrieveMemories a Memory Bank para recuperar recuerdos relevantes para el user_id y el app_name actuales El ejecutor del ADK coordina las llamadas a este método cuando proporcionas una herramienta de memoria a tu agente.

3. Crea un entorno de ejecución del ADK, que organiza la ejecución de tus agentes, herramientas y devoluciones de llamada. La configuración del ADK Runner depende del entorno de implementación que uses:

adk.Runner

Por lo general, adk.Runner se usa en un entorno local, como Colab. La mayoría de las opciones de implementación, como Agent Engine Runtime, ofrecen su propio tiempo de ejecución para el ADK.

import asyncio

from google.adk.sessions import VertexAiSessionService
from google.genai import types

# You can use any ADK session service. This example uses Agent Engine Sessions.
session_service = VertexAiSessionService(
    project="PROJECT_ID",
    location="LOCATION",
    agent_engine_id=agent_engine_id
)

# For Express Mode users, ensure your environment variables are set and
# initialize VertexAiSessionService as follows:
#
# session_service = VertexAiSessionService(
#    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
)

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

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

Plantilla del ADK de Agent Engine

La plantilla del ADK de Agent Engine (AdkApp) se puede usar de forma local y para implementar un agente del ADK en el entorno de ejecución de Agent Engine. Cuando se implementa en el entorno de ejecución de Agent Engine, la plantilla del ADK de Agent Engine usa VertexAiMemoryBankService como servicio de memoria predeterminado, y utiliza la misma instancia de Agent Engine para Memory Bank que el entorno de ejecución de Agent Engine. En este caso, no es necesario que proporciones un servicio de memoria de forma explícita.

Consulta Cómo configurar Agent Engine para obtener más detalles sobre cómo configurar tu entorno de ejecución de Agent Engine, incluido cómo personalizar el comportamiento de tu banco de memoria.

Usa el siguiente código para implementar tu agente del ADK en el entorno de ejecución de Agent Engine:

Nota: Los usuarios del modo Express deben seguir las instrucciones para implementar desde archivos fuente para implementar su app del ADK.

import asyncio

import vertexai
from vertexai.agent_engines import AdkApp

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

adk_app = AdkApp(agent=agent)

# Create a new Agent Engine with your agent deployed to Agent Engine Runtime.
# The Agent Engine instance will also include an empty Memory Bank.
agent_engine = client.agent_engines.create(
      agent_engine=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"]
      }
)

# Alternatively, update an existing Agent Engine to deploy your agent to Agent Engine Runtime.
# Your agent will have access to the Agent Engine instance's existing memories.
agent_engine = client.agent_engines.update(
      name=agent_engine.api_resource.name,
      agent_engine=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"]
      }
)

async def call_agent(query, session_id, user_id):
    async for event in agent_engine.async_stream_query(
        user_id=user_id,
        session_id=session_id,
        message=query,
    ):
        print(event)

Reemplaza lo siguiente:

• PROJECT_ID: ID del proyecto
• LOCATION: Tu región. Consulta las regiones compatibles con Memory Bank.
• AGENT_ENGINE_ID: Es el ID del motor de Agent que se usará para Memory Bank. Por ejemplo, 456 en projects/my-project/locations/us-central1/reasoningEngines/456.
• STAGING_BUCKET: Es tu bucket de Cloud Storage que se usará para la etapa intermedia de tu Agent Engine Runtime.

Cuando se ejecuta de forma local, la plantilla del ADK usa InMemoryMemoryService como el servicio de memoria predeterminado. Sin embargo, puedes anular el servicio de memoria predeterminado para usar VertexAiMemoryBankService:

# For Google Cloud Project users:
def memory_bank_service_builder():
    return VertexAiMemoryBankService(
        project="PROJECT_ID",
        location="LOCATION",
        agent_engine_id="AGENT_ENGINE_ID"
    )
# For Express Mode users, ensure your environment variables are set.
#
# def memory_bank_service_builder():
#    return VertexAiMemoryBankService(
#        agent_engine_id="AGENT_ENGINE_ID"
#    )

adk_app = AdkApp(
      agent=adk_agent,
      # Override the default memory service.
      memory_service_builder=memory_bank_service_builder
)

async def call_agent(query, session_id, user_id):
  # adk_app is a local agent. If you want to deploy it to Agent Engine Runtime,
  # use `client.agent_engines.create(...)` or `client.agent_engines.update(...)`
  # and call the returned Agent Engine instance instead.
  async for event in adk_app.async_stream_query(
      user_id=user_id,
      session_id=session_id,
      message=query,
  ):
      print(event)

Reemplaza lo siguiente:

• PROJECT_ID: ID del proyecto
• LOCATION: Tu región. Consulta las regiones compatibles con Memory Bank.
• AGENT_ENGINE_ID: Es el ID de Agent Engine que se usará para Memory Bank. Por ejemplo, 456 en projects/my-project/locations/us-central1/reasoningEngines/456.

Interactúa con el agente

Después de definir tu agente y configurar Memory Bank, puedes interactuar con él.

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

   adk.Runner

   Cuando usas adk.Runner, puedes llamar directamente a los servicios de memoria y sesión del ADK.

   # Use `asyncio.run(session_service.create(...))` if you're running this
   # code as a standard Python script.
   session = await session_service.create_session(
       app_name="APP_NAME",
       user_id="USER_ID"
   )
   
   # Use `asyncio.run(call_agent(...))` if you're running this code as a
   # standard Python script.
   await call_agent(
       "Can you update the temperature to my preferred temperature?",
       session.id,
       "USER_ID"
   )
   # Agent response: "What is your preferred temperature?"
   
   # Use `asyncio.run(call_agent(...))` if you're running this code as a
   # standard Python script.
   await 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:

   • APP_NAME: Es el nombre de la app para tu runner.
   • 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"}.

   Plantilla del ADK de Agent Engine

   Cuando usas la plantilla del ADK de Agent Engine, puedes llamar a tu entorno de ejecución de Agent Engine para interactuar con la memoria y las sesiones.

   # Use `asyncio.run(agent_engine.async_create_session(...))` if you're
   # running this code as a standard Python script.
   session = await agent_engine.async_create_session(user_id="USER_ID")
   
   # Use `asyncio.run(call_agent(...))` if you're running this code as a
   # standard Python script.
   await call_agent(
       "Can you update the temperature to my preferred temperature?",
       session.get("id"),
       "USER_ID"
   )
   # Agent response: "What is your preferred temperature?"
   
   # Use `asyncio.run(call_agent(...))` if you're running this code as a
   # standard Python script.
   await call_agent("I like it at 71 degrees", session.get("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"}.

2. 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}.

   adk.Runner

   async def trigger_memory_generation(app_name, session):
       # Refresh your `session` object so that all of the session events locally available.
       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)
   
   # Use `asyncio.run(trigger_memory_generation(...))` if you're running this
   # code as a standard Python script.
   await trigger_memory_generation(app_name, session)
   

   Plantilla del ADK de Agent Engine

   Nota: Para usar async_add_session_to_memory, tu AdkApp debe haberse creado con la versión 1.110.0 de google-cloud-aiplatform o una posterior. De lo contrario, puedes activar la generación de memoria haciendo llamadas directas a Memory Bank.

   # Use `asyncio.run(agent_engine.async_add_session_to_memory(...))` if
   # you're running this code as a standard Python script.
   await agent_engine.async_add_session_to_memory(session=session)
   

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

   adk.Runner

   # Use `asyncio.run(session_service.create_session(...))` if you're running
   # this code as a standard Python script.
   session = await session_service.create_session(
       app_name=app_name,
       user_id="USER_ID"
   )
   
   # Use `asyncio.run(call_agent(...))` if you're running this code as a
   # standard Python script.
   await call_agent("Fix the temperature!", session.id, "USER_ID")
   # Agent Response:  Setting temperature to 71 degrees.  Is that correct?
   

   También puedes usar memory_service.search_memory para recuperar recuerdos directamente:

   # Use `asyncio.run(memory_service.search_memory(...))` if you're running
   # this code as a standard Python script.
   await memory_service.search_memory(
       app_name="APP_NAME",
       user_id="USER_ID",
       query="Fix the temperature!",
   )
   

   Plantilla del ADK de Agent Engine

   # Use `asyncio.run(agent_engine.async_add_session_to_memory(...))` if
   # you're running this code as a standard Python script.
   session = await agent_engine.async_create_session(user_id="USER_ID")
   
   # Use `asyncio.run(call_agent(...))` if you're running this code as a
   # standard Python script.
   await call_agent("Fix the temperature!", session.get("id"), "USER_ID")
   # Agent Response:  Setting temperature to 71 degrees.  Is that correct?
   

   También puedes usar agent_engine.async_search_memory para recuperar recuerdos directamente: Nota: Para usar async_search_memory, tu AdkApp debe haberse creado con la versión 1.110.0 o posterior de google-cloud-aiplatform. De lo contrario, puedes recuperar recuerdos haciendo llamadas directas a Memory Bank.

   # Use `asyncio.run(agent_engine.async_search_memory(...))` if you're
   # running this code as a standard Python script.
   await agent_engine.async_search_memory(
       user_id="USER_ID",
       query="Fix the temperature!",
   )
   

Realiza una limpieza

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:

1. Usa el siguiente muestra de código para borrar la instancia de Vertex AI Agent Engine, lo que también borrará las sesiones o memorias que pertenezcan a ese Vertex AI Agent Engine.

   agent_engine.delete(force=True)
   

2. Borra los archivos creados de forma local.

¿Qué sigue?

• Guía de inicio rápido con el SDK de Agent Engine