Guía de inicio rápido de Agent Development Kit

Vista previa

Esta función está sujeta a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Servicios. Las funciones previas a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases de lanzamiento.

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

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

1. Crea tu agente y tu runner de ADK local. Los ejecutores del ADK conectan tu agente a servicios que proporcionan gestión de sesiones y memoria.

2. Interactúa con tu agente para generar de forma dinámica recuerdos a largo plazo a los que se pueda acceder en diferentes sesiones.

3. Liberar espacio.

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

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

Para ver un ejemplo de cómo usar Memory Bank con ADK, ejecuta el cuaderno "Get started with Memory Bank on ADK" (Empezar a usar Memory Bank en ADK) en uno de los siguientes entornos:

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

Antes de empezar

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

Nota: Si ya tienes un Google Cloud proyecto, puedes seguir la guía con su número y ubicación mediante las instrucciones de "Google Cloud Proyecto". Si es la primera vez que usas la función, 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, a continuación, seguir la guía con las instrucciones de "Modo Exprés de Vertex AI".

Google Cloud

Establece variables de entorno:

Para usar el ADK, define las 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"

Haz los cambios siguientes:

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

Modo Express de Vertex AI

import os

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

Haz los cambios siguientes:

• API_KEY: 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 mediante el registro en modo exprés.

Crear un agente de ADK

1. Cuando desarrolles tu agente de ADK, incluye una herramienta Memory que controle cuándo recupera el agente los recuerdos y cómo se incluyen en la petición. El agente de ejemplo usa PreloadMemoryTool, que siempre recupera recuerdos al principio de cada turno e incluye los recuerdos 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 tiempo de ejecución del ADK. Si quieres 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
   )
   

   Haz los cambios siguientes:

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

   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
   )
   

   Haz los cambios siguientes:

   • API_KEY: 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 mediante el registro en modo exprés.

   VertexAiMemoryBankService es un envoltorio de ADK para Memory Bank que se define mediante el BaseMemoryService de ADK y usa una interfaz diferente a la del SDK de Agent Engine. Puedes usar el SDK de Agent Engine para hacer 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 de origen. El ADK Runner no coordina las llamadas a este método. Si quieres automatizar la generación de recuerdos con el ADK, debes definir tus propias funciones de retrollamada.

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

3. Crea un tiempo de ejecución de ADK, que coordina la ejecución de tus agentes, herramientas y retrollamadas. La configuración de ADK Runner depende del entorno de implementación que utilices:

adk.Runner

adk.Runner se suele usar en un entorno local, como Colab. La mayoría de las opciones de implementación, como Entorno de ejecución de Agent Engine, ofrecen su propio entorno de ejecución para 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)

Haz los cambios siguientes:

• APP_NAME: el nombre de tu aplicación ADK.

Plantilla del ADK de Agent Engine

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

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

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

Nota: Los usuarios del modo Express deben seguir las instrucciones para implementar desde archivos de origen para implementar su aplicación 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)

Haz los cambios siguientes:

• PROJECT_ID: tu ID de proyecto.
• LOCATION: tu región. Consulta las regiones admitidas para Banco de recuerdos.
• AGENT_ENGINE_ID: ID de Agent Engine que se va a usar en Memory Bank. Por ejemplo, 456 en projects/my-project/locations/us-central1/reasoningEngines/456.
• STAGING_BUCKET: el segmento de Cloud Storage que se usará para organizar el tiempo de ejecución de Agent Engine.

Cuando se ejecuta de forma local, la plantilla del ADK usa InMemoryMemoryService como 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)

Haz los cambios siguientes:

• PROJECT_ID: tu ID de proyecto.
• LOCATION: tu región. Consulta las regiones admitidas para Banco de recuerdos.
• AGENT_ENGINE_ID: el ID de Agent Engine que se va a usar en Memory Bank. Por ejemplo, 456 en projects/my-project/locations/us-central1/reasoningEngines/456.

Interactuar con tu 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: Puede haber algunas variaciones en las respuestas del agente y del banco de memoria en función de los modelos que se utilicen.

   adk.Runner

   Cuando usas adk.Runner, puedes llamar directamente a los servicios de memoria y sesión de tu 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.
   

   Haz los cambios siguientes:

   • APP_NAME: nombre de la aplicación de tu runner.
   • USER_ID: identificador de tu usuario. Los recuerdos generados a partir de esta sesión se identifican con este identificador opaco. El ámbito 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 tiempo 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.
   

   Haz los cambios siguientes:

   • USER_ID: identificador de tu usuario. Los recuerdos generados a partir de esta sesión se identifican con este identificador opaco. El ámbito 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 ámbito {"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 has usado PreloadMemoryTool, el agente recupera recuerdos al principio de cada turno para acceder a las preferencias que el usuario le haya comunicado 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 de google-cloud-aiplatform o una posterior. 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!",
   )
   

Limpieza

Para limpiar todos los recursos usados 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 cualquier sesión o memoria que pertenezca a ese Vertex AI Agent Engine.

   agent_engine.delete(force=True)
   

2. Elimina los archivos creados localmente.

Siguientes pasos

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