Compila e implementa un agente de ADK en Cloud Run

1. Introducción

Este lab se enfoca en la implementación de un servicio de agente para clientes. Usarás el Kit de desarrollo de agentes (ADK) para compilar un agente de IA que use herramientas.

En este lab, crearemos un agente de zoológico que usa Wikipedia para responder preguntas sobre animales.

De izquierda a derecha, un león, dos pingüinos, una persona con un sombrero de safari, un elefante y un oso están de pie de espaldas al espectador, mirando un gran cohete rojo y blanco que se lanza hacia un cielo azul con nubes blancas. También se ven dos cohetes más pequeños que se lanzan a la distancia. La escena se desarrolla dentro de un recinto del zoológico con una cerca de madera y acantilados rocosos.

Por último, implementaremos el agente guía en Google Cloud Run, en lugar de solo ejecutarlo de forma local.

Requisitos previos

  • Un proyecto de Google Cloud con facturación habilitada.

Qué aprenderás

  • Cómo estructurar un proyecto de Python para la implementación del ADK
  • Cómo implementar un agente que usa herramientas con google-adk
  • Cómo implementar una aplicación de Python como un contenedor sin servidores en Cloud Run
  • Cómo configurar la autenticación segura de servicio a servicio con roles de IAM
  • Cómo borrar los recursos de Cloud para evitar generar costos futuros

Requisitos

  • Una cuenta de Google Cloud y un proyecto de Google Cloud
  • Un navegador web, como Chrome

2. ¿Por qué realizar la implementación en Cloud Run?

Cloud Run es una excelente opción para alojar agentes del ADK porque es una plataforma sin servidores, lo que significa que puedes enfocarte en tu código y no en administrar la infraestructura subyacente. Nos encargamos del trabajo operativo por ti.

Imagínalo como una tienda temporal: solo abre y usa recursos cuando llegan clientes (solicitudes). Cuando no hay clientes, cierra por completo y no pagas por una tienda vacía.

Funciones clave

Ejecuta contenedores en cualquier lugar:

  • Usas un contenedor (imagen de Docker) que contiene tu app.
  • Cloud Run lo ejecuta en la infraestructura de Google.
  • No hay que preocuparse por aplicar parches al SO, configurar VMs o escalar la app.

Ajuste de escala automático:

  • Si 0 personas usan tu app, se ejecutan 0 instancias (se reduce a cero instancias, lo que resulta rentable).
  • Si recibe 1,000 solicitudes, se inician tantas copias como sean necesarias.

Sin estado de forma predeterminada:

  • Cada solicitud podría ir a una instancia diferente.
  • Si necesitas almacenar el estado, usa un servicio externo como Cloud SQL, Firestore o Memorystore.

Admite cualquier lenguaje o framework:

  • Siempre que se ejecute en un contenedor de Linux, a Cloud Run no le importa si el lenguaje es Python, Go, Node.js, Java o .NET.

Paga por lo que usas:

3. Configura el proyecto

Cuenta de Google

Si aún no tienes una Cuenta de Google personal, debes crear una.

Usa una cuenta personal en lugar de una cuenta de trabajo o de institución educativa.

Accede a la consola de Google Cloud

Accede a la consola de Google Cloud con una Cuenta de Google personal.

Habilitar facturación

Configura una cuenta de facturación personal

Si configuraste la facturación con créditos de Google Cloud, puedes omitir este paso.

Para configurar una cuenta de facturación personal, ve aquí para habilitar la facturación en la consola de Cloud.

Notas:

  • Completar este lab debería costar menos de USD 1 en recursos de Cloud.
  • Puedes seguir los pasos al final de este lab para borrar recursos y evitar cargos adicionales.
  • Los usuarios nuevos pueden acceder a la prueba gratuita de USD 300.

Crear un proyecto (opcional)

Si no tienes un proyecto actual que quieras usar para este lab, crea uno nuevo aquí.

4. Abre el editor de Cloud Shell

  1. Haz clic en este vínculo para navegar directamente al editor de Cloud Shell.
  2. Si se te solicita autorización en algún momento, haz clic en Autorizar para continuar.Haz clic para autorizar Cloud Shell
  3. Si la terminal no aparece en la parte inferior de la pantalla, ábrela:
    • Haz clic en Ver.
    • Haz clic en Terminal.Abre una terminal nueva en el editor de Cloud Shell

5. Habilita las APIs

Para usar Cloud Run, Artifact Registry, Cloud Build, Vertex AI y Compute Engine, debes habilitar sus respectivas APIs en tu proyecto de Google Cloud.

  • En la terminal, habilita las APIs:
    gcloud services enable \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  aiplatform.googleapis.com \
  compute.googleapis.com
    Cuando finalice la ejecución, deberías ver un resultado como el siguiente:
    Operation "operations/acat.p2-[GUID]" finished successfully.

Presentamos las APIs

  • La API de Cloud Run Admin (run.googleapis.com) te permite ejecutar servicios de frontend y backend, trabajos por lotes o sitios web en un entorno completamente administrado. Maneja la infraestructura para implementar y escalar tus aplicaciones en contenedores.
  • La API de Artifact Registry (artifactregistry.googleapis.com) proporciona un repositorio privado y seguro para almacenar tus imágenes de contenedor. Es la evolución de Container Registry y se integra perfectamente con Cloud Run y Cloud Build.
  • La API de Cloud Build (cloudbuild.googleapis.com) es una plataforma de CI/CD sin servidores que ejecuta tus compilaciones en la infraestructura de Google Cloud. Se usa para compilar tu imagen de contenedor en la nube a partir de tu Dockerfile.
  • La API de Vertex AI (aiplatform.googleapis.com) permite que tu aplicación implementada se comunique con los modelos de Gemini para realizar tareas básicas de IA. Proporciona la API unificada para todos los servicios de IA de Google Cloud.
  • La API de Compute Engine (compute.googleapis.com) proporciona máquinas virtuales seguras y personalizables que se ejecutan en la infraestructura de Google. Si bien Cloud Run es administrado, la API de Compute Engine suele ser necesaria como dependencia fundamental para varios recursos de procesamiento y redes.

6. Prepara tu entorno de desarrollo

Crea el directorio

  1. En la terminal, crea el directorio del proyecto y los subdirectorios necesarios:
    cd && mkdir zoo_guide_agent && cd zoo_guide_agent
  2. En la terminal, ejecuta el siguiente comando para abrir el directorio zoo_guide_agent en el explorador del Editor de Cloud Shell:
    cloudshell open-workspace ~/zoo_guide_agent
  3. Se actualizará el panel del explorador de la izquierda. Ahora deberías ver el directorio que creaste.
    Captura de pantalla del nuevo directorio en el panel lateral del explorador

Configura tu proyecto

  1. En la terminal, configura tu proyecto con este comando:
    gcloud config set project [PROJECT_ID]
    Ejemplo: gcloud config set project lab-project-id-example Establece el ID del proyecto en la terminal del editor de Cloud Shell
  2. Deberías ver el siguiente mensaje:
    Updated property [core/project].

Requisitos de instalación

  1. Ejecuta el siguiente comando en la terminal para crear el archivo requirements.txt.
    cloudshell edit requirements.txt
  2. Agrega lo siguiente al archivo requirements.txt recién creado
    google-adk==1.14.0
langchain-community==0.3.27
wikipedia==1.4.0
  3. En la terminal, crea y activa un entorno virtual con uv. Esto garantiza que las dependencias de tu proyecto no entren en conflicto con el Python del sistema.
    uv venv
source .venv/bin/activate
  4. Instala los paquetes necesarios en tu entorno virtual en la terminal.
    uv pip install -r requirements.txt

Configura variables de entorno

  • Usa el siguiente comando en la terminal para crear el archivo .env.
    # 1. Set the variables in your terminal first
PROJECT_ID=$(gcloud config get-value project)
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
SA_NAME=lab2-cr-service

# 2. Create the .env file using those variables
cat <<EOF > .env
PROJECT_ID=$PROJECT_ID
PROJECT_NUMBER=$PROJECT_NUMBER
SA_NAME=$SA_NAME
SERVICE_ACCOUNT=${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com
MODEL="gemini-2.5-flash"
EOF

7. Crea el flujo de trabajo del agente

Crea un archivo __init__.py

  1. Crea el archivo init.py ejecutando lo siguiente en la terminal:
    cloudshell edit __init__.py
    Este archivo le indica a Python que el directorio zoo_guide_agent es un paquete.
  2. Agrega el siguiente código al nuevo archivo __init__.py:
    from . import agent

Crea el archivo agent.py

  1. Crea el archivo agent.py principal pegando el siguiente comando en la terminal.
    cloudshell edit agent.py
  2. Importaciones y configuración inicial: Agrega el siguiente código a tu archivo agent.py actualmente vacío:
    import os
import logging
import google.cloud.logging
from dotenv import load_dotenv

from google.adk import Agent
from google.adk.agents import SequentialAgent
from google.adk.tools.tool_context import ToolContext
from google.adk.tools.langchain_tool import LangchainTool

from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

import google.auth
import google.auth.transport.requests
import google.oauth2.id_token

# --- Setup Logging and Environment ---

cloud_logging_client = google.cloud.logging.Client()
cloud_logging_client.setup_logging()

load_dotenv()

model_name = os.getenv("MODEL")
    Este primer bloque del archivo agent.py incorpora todas las bibliotecas necesarias del ADK y Google Cloud. También configura el registro y carga las variables de entorno desde tu archivo .env, lo que es fundamental para acceder a tu modelo y a la URL del servidor.
  3. Define las herramientas: La eficacia de un agente depende de las herramientas que puede usar. Agrega el siguiente código a la parte inferior de agent.py para definir las herramientas:
    # Greet user and save their prompt

def add_prompt_to_state(
    tool_context: ToolContext, prompt: str
) -> dict[str, str]:
    """Saves the user's initial prompt to the state."""
    tool_context.state["PROMPT"] = prompt
    logging.info(f"[State updated] Added to PROMPT: {prompt}")
    return {"status": "success"}

# Configuring the Wikipedia Tool
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())
)
    Explicación de las herramientas
    • add_prompt_to_state 📝: Esta herramienta recuerda lo que pregunta un visitante del zoológico. Cuando un visitante pregunta: "¿Dónde están los leones?", esta herramienta guarda esa pregunta específica en la memoria del agente para que los otros agentes del flujo de trabajo sepan qué investigar.
      Cómo: Es una función de Python que escribe la instrucción del visitante en el diccionario compartido tool_context.state. Este contexto de la herramienta representa la memoria a corto plazo del agente para una sola conversación. Los datos que un agente guarda en el estado pueden ser leídos por el siguiente agente en el flujo de trabajo.
    • LangchainTool 🌍: Le proporciona al agente guía conocimientos generales del mundo. Cuando un visitante hace una pregunta que no está en la base de datos del zoológico, como "¿Qué comen los leones en la naturaleza?", esta herramienta permite que el agente busque la respuesta en Wikipedia.
      Funcionamiento: Actúa como un adaptador, lo que permite que nuestro agente use la herramienta precompilada WikipediaQueryRun de la biblioteca LangChain.
      El robot de aspecto amigable sostiene un bloc de notas con dibujos de animales y un globo de diálogo de un león, mientras habla con un hombre y un niño con una mochila. En el fondo, se ven jirafas y otros elementos del zoológico, con palmeras que enmarcan la entrada.
  4. Define los agentes especialistas: Agrega el siguiente código a la parte inferior de agent.py para definir los agentes comprehensive_researcher y response_formatter:
    # 1. Researcher Agent
comprehensive_researcher = Agent(
    name="comprehensive_researcher",
    model=model_name,
    description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.",
    instruction="""
    You are a helpful research assistant. Your goal is to fully answer the user's PROMPT.
    You have access to two tools:
    1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations).
    2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat).

    First, analyze the user's PROMPT.
    - If the prompt can be answered by only one tool, use that tool.
    - If the prompt is complex and requires information from both the zoo's database AND Wikipedia,
      you MUST use both tools to gather all necessary information.
    - Synthesize the results from the tool(s) you use into preliminary data outputs.

    PROMPT:
    { PROMPT }
    """,
    tools=[
        wikipedia_tool
    ],
    output_key="research_data" # A key to store the combined findings
)

# 2. Response Formatter Agent
response_formatter = Agent(
    name="response_formatter",
    model=model_name,
    description="Synthesizes all information into a friendly, readable response.",
    instruction="""
    You are the friendly voice of the Zoo Tour Guide. Your task is to take the
    RESEARCH_DATA and present it to the user in a complete and helpful answer.

    - First, present the specific information from the zoo (like names, ages, and where to find them).
    - Then, add the interesting general facts from the research.
    - If some information is missing, just present the information you have.
    - Be conversational and engaging.

    RESEARCH_DATA:
    { research_data }
    """
)
    • El agente comprehensive_researcher es el "cerebro" de nuestra operación. Toma la instrucción del usuario del State compartido, examina la herramienta de Wikipedia y decide cuáles usar para encontrar la respuesta.
    • El rol del agente response_formatter es la presentación. Toma los datos sin procesar que recopila el agente investigador (que se pasan a través de State) y usa las habilidades lingüísticas del LLM para transformarlos en una respuesta amigable y de tono conversacional.
      El robot, con ojos azules brillantes, se sienta frente a un gran monitor curvo que muestra MCP ZOO SERVER a la izquierda y una página de Wikipedia de ZOO a la derecha. Los íconos de animales son visibles en la interfaz del servidor. El escritorio tiene varios paneles táctiles azules brillantes. En el fondo, se ve el horizonte de una ciudad a través de grandes ventanas.
  5. Define el agente de flujo de trabajo: Agrega este bloque de código a la parte inferior de agent.py para definir el agente secuencial tour_guide_workflow:
    tour_guide_workflow = SequentialAgent(
    name="tour_guide_workflow",
    description="The main workflow for handling a user's request about an animal.",
    sub_agents=[
        comprehensive_researcher, # Step 1: Gather all data
        response_formatter,       # Step 2: Format the final response
    ]
)
    El agente de flujo de trabajo actúa como el encargado de la "oficina administrativa" del recorrido por el zoológico. Toma la solicitud de investigación y garantiza que los dos agentes que definimos anteriormente realicen sus trabajos en el orden correcto: primero investigar y, luego, dar formato. Con esto, se crea un proceso predecible y confiable para responder las preguntas de los visitantes.
    Cómo: Es un SequentialAgent, un tipo especial de agente que no piensa por sí mismo. Su único trabajo es ejecutar una lista de sub_agents (el investigador y el formateador) en una secuencia fija y pasar automáticamente la memoria compartida de uno a otro.
  6. Organiza el flujo de trabajo principal: Agrega este último bloque de código a la parte inferior de agent.py para definir el root_agent:
    root_agent = Agent(
    name="greeter",
    model=model_name,
    description="The main entry point for the Zoo Tour Guide.",
    instruction="""
    - Let the user know you will help them learn about the animals we have in the zoo.
    - When the user responds, use the 'add_prompt_to_state' tool to save their response.
    After using the tool, transfer control to the 'tour_guide_workflow' agent.
    """,
    tools=[add_prompt_to_state],
    sub_agents=[tour_guide_workflow]
)
    El framework del ADK usa root_agent como punto de partida para todas las conversaciones nuevas. Su rol principal es coordinar el proceso general. Actúa como el controlador inicial y administra el primer turno de la conversación.
    Se representan tres robots: un Greeter-Bot a la izquierda escribe en un bloc de notas con una burbuja de pensamiento de un león, un Researcher-Bot en el centro está sentado en un escritorio con una computadora que muestra datos y una flecha de consulta que apunta hacia él, y un Presenter-Bot a la derecha sonríe mientras sostiene un gráfico etiquetado como Datos analizados, con una flecha que apunta hacia él desde el Researcher-Bot. En el fondo, se ven jirafas y elefantes, y la escena está enmarcada por palmeras.

El archivo agent.py completo

Tu archivo agent.py ya está completo. Si lo creas de esta manera, puedes ver cómo cada componente (herramientas, agentes de trabajadores y agentes de administradores) tiene un rol específico en la creación del sistema inteligente final.

El archivo completo debería verse de la siguiente manera:

import os
import logging
import google.cloud.logging
from dotenv import load_dotenv

from google.adk import Agent
from google.adk.agents import SequentialAgent
from google.adk.tools.tool_context import ToolContext
from google.adk.tools.langchain_tool import LangchainTool

from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

import google.auth
import google.auth.transport.requests
import google.oauth2.id_token

# --- Setup Logging and Environment ---

cloud_logging_client = google.cloud.logging.Client()
cloud_logging_client.setup_logging()

load_dotenv()

model_name = os.getenv("MODEL")

# Greet user and save their prompt

def add_prompt_to_state(
    tool_context: ToolContext, prompt: str
) -> dict[str, str]:
    """Saves the user's initial prompt to the state."""
    tool_context.state["PROMPT"] = prompt
    logging.info(f"[State updated] Added to PROMPT: {prompt}")
    return {"status": "success"}

# Configuring the Wikipedia Tool
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())
)

# 1. Researcher Agent
comprehensive_researcher = Agent(
    name="comprehensive_researcher",
    model=model_name,
    description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.",
    instruction="""
    You are a helpful research assistant. Your goal is to fully answer the user's PROMPT.
    You have access to two tools:
    1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations).
    2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat).

    First, analyze the user's PROMPT.
    - If the prompt can be answered by only one tool, use that tool.
    - If the prompt is complex and requires information from both the zoo's database AND Wikipedia,
        you MUST use both tools to gather all necessary information.
    - Synthesize the results from the tool(s) you use into preliminary data outputs.

    PROMPT:
    { PROMPT }
    """,
    tools=[
        wikipedia_tool
    ],
    output_key="research_data" # A key to store the combined findings
)

# 2. Response Formatter Agent
response_formatter = Agent(
    name="response_formatter",
    model=model_name,
    description="Synthesizes all information into a friendly, readable response.",
    instruction="""
    You are the friendly voice of the Zoo Tour Guide. Your task is to take the
    RESEARCH_DATA and present it to the user in a complete and helpful answer.

    - First, present the specific information from the zoo (like names, ages, and where to find them).
    - Then, add the interesting general facts from the research.
    - If some information is missing, just present the information you have.
    - Be conversational and engaging.

    RESEARCH_DATA:
    { research_data }
    """
)

tour_guide_workflow = SequentialAgent(
    name="tour_guide_workflow",
    description="The main workflow for handling a user's request about an animal.",
    sub_agents=[
        comprehensive_researcher, # Step 1: Gather all data
        response_formatter,       # Step 2: Format the final response
    ]
)

root_agent = Agent(
    name="greeter",
    model=model_name,
    description="The main entry point for the Zoo Tour Guide.",
    instruction="""
    - Let the user know you will help them learn about the animals we have in the zoo.
    - When the user responds, use the 'add_prompt_to_state' tool to save their response.
    After using the tool, transfer control to the 'tour_guide_workflow' agent.
    """,
    tools=[add_prompt_to_state],
    sub_agents=[tour_guide_workflow]
)

Ahora, pasemos a la implementación.

8. Prepara la aplicación para la implementación

Verifica la estructura final

Antes de implementar, verifica que tu directorio del proyecto contenga los archivos correctos.

  • Asegúrate de que tu carpeta zoo_guide_agent se vea así:
    zoo_guide_agent/
├── .env
├── __init__.py
├── agent.py
└── requirements.txt

Configura los permisos de IAM

Con el código local listo, el siguiente paso es configurar la identidad que usará tu agente en la nube.

  1. En la terminal, carga las variables en tu sesión de shell.
    source .env
  2. Crea una cuenta de servicio dedicada para tu servicio de Cloud Run, de modo que tenga su propio permiso específico. Pega lo siguiente en la terminal:
    gcloud iam service-accounts create ${SA_NAME} \
    --display-name="Service Account for lab 2 "
    Si creas una identidad dedicada para esta aplicación específica, te aseguras de que el agente solo tenga los permisos exactos que necesita, en lugar de usar una cuenta predeterminada con acceso demasiado amplio.
  3. Otorga a la cuenta de servicio el rol de usuario de Vertex AI, que le da permiso para llamar a los modelos de Google.
    # Grant the "Vertex AI User" role to your service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user"

9. Implementa el agente con la CLI del ADK

Con el código local listo y tu proyecto de Google Cloud preparado, es hora de implementar el agente. Usarás el comando adk deploy cloud_run, una herramienta conveniente que automatiza todo el flujo de trabajo de implementación. Este único comando empaqueta tu código, crea una imagen de contenedor, la envía a Artifact Registry y lanza el servicio en Cloud Run, lo que lo hace accesible en la Web.

  1. Ejecuta el siguiente comando en la terminal para implementar tu agente.
    # Run the deployment command
uvx --from google-adk \
adk deploy cloud_run \
  --project=$PROJECT_ID \
  --region=europe-west1 \
  --service_name=zoo-tour-guide \
  --with_ui \
  . \
  -- \
  --labels=dev-tutorial=codelab-adk \
  --service-account=$SERVICE_ACCOUNT
    El comando uvx te permite ejecutar herramientas de línea de comandos publicadas como paquetes de Python sin necesidad de una instalación global de esas herramientas.
  2. Si se te solicita lo siguiente:
    Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region 
[europe-west1] will be created.

Do you want to continue (Y/n)?
    Si es así, escribe Y y presiona INTRO.
  3. Si se te solicita lo siguiente:
    Allow unauthenticated invocations to [your-service-name] (y/N)?.
    Escribe y y presiona INTRO. Esto permite invocaciones no autenticadas para este lab y facilita las pruebas. Si la ejecución se realiza correctamente, el comando proporcionará la URL del servicio de Cloud Run implementado. (Se verá similar a https://zoo-tour-guide-123456789.europe-west1.run.app).
  4. Copia la URL del servicio de Cloud Run implementado para la siguiente tarea.

10. Prueba el agente implementado

Ahora que tu agente está activo en Cloud Run, harás una prueba para confirmar que la implementación se realizó correctamente y que el agente funciona como se espera. Usarás la URL del servicio público (algo como https://zoo-tour-guide-123456789.europe-west1.run.app/) para acceder a la interfaz web del ADK y, así, interactuar con el agente.

  1. Abre la URL pública del servicio de Cloud Run en tu navegador web. Como usaste --with_ui flag, deberías ver la IU para desarrolladores del ADK.
  2. Activa Token Streaming en la esquina superior derecha.
    Ahora puedes interactuar con el agente del zoológico.
  3. Escribe hello y presiona Intro para comenzar una conversación nueva.
  4. Observa el resultado. El agente debería responder rápidamente con su saludo, que será similar al siguiente:
    "Hello! I'm your Zoo Tour Guide. I can help you learn about the amazing animals we have here. What would you like to know or explore today?"
  5. Hazle preguntas al agente, como las siguientes:
    Where can I find the polar bears in the zoo and what is their diet?
    Captura de pantalla del agente de ADK que realiza una secuencia de acciones: add_prompt_to_state, transfer_to_agent, wikipedia y get_animals_by_species. La primera respuesta dice: &quot;No puedo decirte dónde encontrar a los osos polares dentro de este zoológico específico, pero puedo contarte sobre su dieta&quot;. La segunda respuesta dice: &quot;Los osos polares se encuentran en la exhibición del Ártico, en el sendero polar&quot;. No puedo recuperar información sobre su dieta con las herramientas disponibles&quot;. La tercera respuesta, la más completa, dice: &quot;¡Con gusto te contaré sobre nuestros osos polares! Puedes encontrar nuestros osos polares en la exhibición del Ártico en el sendero Polar. Aquí tenemos tres osos polares: Copito de Nieve, que tiene 7 años. Blizzard, que tiene 5 años. Iceberg, que tiene 9 años. En cuanto a su dieta, los osos polares son principalmente carnívoros. Se especializan en cazar focas, en particular, focas anilladas. También comen morsas, belugas y algunos animales terrestres&quot;.

Explicación del flujo del agente

Tu sistema funciona como un equipo inteligente de múltiples agentes. El proceso se administra con una secuencia clara para garantizar un flujo eficiente y fluido desde la pregunta de un usuario hasta la respuesta final y detallada.

1. El agente de bienvenida del zoológico (el mostrador de recepción)

El proceso comienza con el agente de bienvenida.

  • Su trabajo: Iniciar la conversación. Su instrucción es saludar al usuario y preguntarle sobre qué animal le gustaría aprender.
  • Su herramienta: Cuando el usuario responde, el agente de bienvenida usa su herramienta add_prompt_to_state para capturar las palabras exactas (p. ej., "cuéntame sobre los leones") y guardarlas en la memoria del sistema.
  • Siguiente eslabón del proceso: Después de guardar la instrucción, le pasa inmediatamente el control a su agente secundario, tour_guide_workflow.

2. El investigador integral (el superinvestigador)

Este es el primer paso en el flujo de trabajo principal y el "cerebro" de la operación. En lugar de un equipo grande, ahora tienes un solo agente altamente capacitado que puede acceder a toda la información disponible.

  • Su trabajo: Analizar la pregunta del usuario y crear un plan inteligente. Utiliza la capacidad de uso de herramientas del modelo de lenguaje para decidir si necesita lo siguiente:
    • Información general de la Web (a través de la API de Wikipedia)
    • O, para preguntas complejas, ambos tipos de datos

3. El formateador de respuestas (el presentador)

Una vez que el investigador integral haya recopilado todos los hechos, este es el agente final que se debe ejecutar.

  • Su trabajo: Actuar como la voz amigable del guía del zoológico. Toma los datos sin procesar (que podrían ser de una o ambas fuentes) y los pule.
  • Su acción: Sintetiza toda la información en una respuesta única, coherente y atractiva. Siguiendo sus instrucciones, primero presenta la información específica del zoológico y, luego, agrega los datos generales interesantes.
  • El resultado final: El texto generado por este agente es la respuesta completa y detallada que el usuario ve en la ventana de chat.

Si te interesa obtener más información sobre la creación de agentes, consulta los siguientes recursos:

  1. Documentos del ADK
  2. Cómo crear herramientas personalizadas para agentes del ADK

11. Limpia el entorno

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos usados en este instructivo, borra el proyecto que contiene los recursos o conserva el proyecto y borra los recursos individuales.

Borra los servicios y las imágenes de Cloud Run

Si deseas conservar el proyecto de Google Cloud, pero quitar los recursos específicos que creaste en este lab, debes borrar el servicio en ejecución y la imagen del contenedor almacenada en el registro.

  • Ejecuta los siguientes comandos en la terminal:
    gcloud run services delete zoo-tour-guide --region=europe-west1 --quiet
gcloud artifacts repositories delete cloud-run-source-deploy --location=europe-west1 --quiet

Borra el proyecto (opcional)

Si creaste un proyecto nuevo específicamente para este lab y no planeas volver a usarlo, la forma más fácil de realizar una limpieza es borrar todo el proyecto. Esto garantiza que se quiten por completo todos los recursos (incluida la cuenta de servicio y los artefactos de compilación ocultos).

  • En la terminal, ejecuta el siguiente comando (reemplaza [YOUR_PROJECT_ID] por el ID de tu proyecto real).
    gcloud projects delete $PROJECT_ID

12. Felicitaciones

Compilaste e implementaste correctamente una aplicación de IA de agentes múltiples en Google Cloud.

Resumen

En este lab, pasaste de un directorio vacío a un servicio de IA activo y de acceso público. Aquí tienes un vistazo de lo que creaste:

  • Creaste un equipo especializado: En lugar de una IA genérica, creaste un "Investigador" para encontrar hechos y un "Formateador" para pulir la respuesta.
  • Les proporcionaste herramientas: Conectaste tus agentes al mundo exterior con la API de Wikipedia.
  • Ya lo implementaste: Tomaste tu código de Python local y lo implementaste como un contenedor sin servidores en Cloud Run, y lo protegiste con una cuenta de servicio dedicada.

Temas abordados

  • Cómo estructurar un proyecto de Python para la implementación con el ADK
  • Cómo implementar un flujo de trabajo multiagente con [SequentialAgent](https://google.github.io/adk-docs/agents/workflow-agents/sequential-agents/)
  • Cómo integrar herramientas externas, como la API de Wikipedia
  • Cómo implementar un agente en Cloud Run con el comando adk deploy

13. Encuesta

Resultado:

¿Cómo usarás este instructivo?

Solo lo leeré Lo leeré y completaré los ejercicios