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

Vista previa

Esta función está sujetas 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 del kit de desarrollo de agentes (ADK) para que use Memory Bank, tu agente orquesta 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 del ADK local.

2. Interactúa con tu agente para generar de forma dinámica recuerdos a largo plazo a los que se pueda acceder en todas las 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.

Antes de empezar

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

Establece variables de entorno:

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

Haz los cambios siguientes:

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

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

   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
   )
   

   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 el user_id y el app_name actuales. El ADK Runner 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.

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

# You can use any ADK session service.
session_service = VertexAiSessionService(
    project="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)

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:

import vertexai
from vertexai.preview.reasoning_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:

def memory_bank_service_builder():
    return VertexAiMemoryBankService(
        project="PROJECT_ID",
        location="LOCATION",
        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: 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.

   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.
   

   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 esta clave opaca. 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.

   session = await agent_engine.async_create_session(user_id="USER_ID")
   
   await call_agent(
       "Can you update the temperature to my preferred temperature?",
       session.get("id"),
       "USER_ID"
   )
   
   # Agent response: "What is your preferred temperature?"
   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 esta clave opaca. 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

   session = await session_service.get_session(
       app_name=app_name,
       user_id="USER_ID",
       session_id=session.id
   )
   memory_service.add_session_to_memory(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.

   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 ha comunicado anteriormente.

   adk.Runner

   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?
   

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

   await memory_service.search_memory(
       app_name="APP_NAME",
       user_id="USER_ID",
       query="Fix the temperature!",
   )
   

   Plantilla del ADK de Agent Engine

   session = await agent_engine.async_create_session(user_id="USER_ID")
   
   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.

   await agent_engine.async_search_memory(
       user_id="USER_ID",
       query="Fix the temperature!",
   )
   

Limpieza

Para limpiar todos los recursos utilizados 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