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 crear un agente de IA que use herramientas.

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

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

Requisitos previos

• Conocimientos de Python y las interfaces de línea de comandos
• Un proyecto de Google Cloud con facturación habilitada.
• Herramientas de la CLI instaladas: gcloud, gsutil, uv.

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 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 no 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 te permite centrarte en tu código en lugar de gestionar 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 debes preocuparte 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:

• Cloud Run es compatible con cualquier lenguaje, como Python, Go, Node.js, Java o .NET, siempre y cuando la aplicación funcione dentro de un contenedor de Linux.

Paga por lo que usas:

• Facturación basada en solicitudes: Se factura por solicitud más tiempo de procesamiento (hasta 100 ms).
• Facturación basada en instancias: Se factura por la vida útil completa de la instancia (sin cargos por solicitud).

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 laboral o educativa.

Es posible que las cuentas laborales y educativas tengan restricciones que te impidan habilitar las APIs necesarias para este lab.

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.

Algunas notas:

• Completar este lab debería costar menos de USD 1 en recursos de Cloud.
• Puedes seguir los pasos que se indican al final de este lab para borrar los 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 del día, haz clic en Autorizar para continuar.
3. Si la terminal no aparece en la parte inferior de la pantalla, ábrela:
   • Haz clic en Ver.
   • Haz clic en Terminal.

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

   Si no recuerdas el ID de tu proyecto, puedes enumerar todos tus IDs de proyecto con el siguiente comando: gcloud projects list

   
2. Deberías ver el siguiente mensaje:

   Updated property [core/project].
   

   Si ves un WARNING y se te pregunta Do you want to continue (Y/n)?, es probable que hayas ingresado el ID del proyecto de forma incorrecta. Presiona n, presiona Enter y vuelve a intentar ejecutar el comando gcloud config set project.

6. Habilita las APIs

Para usar Cloud Run, Artifact Registry, Cloud Build, Gemini Enterprise Agent Platform 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. Se encarga de la infraestructura para implementar y escalar tus aplicaciones alojadas 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 en 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 Gemini Enterprise Agent Platform (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 redes y procesamiento.

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

   Si la terminal desaparece cuando haces esto, puedes volver a abrirla haciendo clic en Ver y, luego, en Terminal en el menú superior.

   CRITICAL: Cuando abres un nuevo espacio de trabajo, se restablece el editor de Cloud Shell y se reinicia tu sesión de terminal. Debes asegurarte de volver a abrir la terminal, verificar que te encuentres en el directorio correcto ~/zoo_guide_agent (ejecuta pwd y cd ~/zoo_guide_agent si es necesario) y que tu proyecto de gcloud siga seleccionado (ejecuta gcloud config set project [PROJECT_ID] si es necesario).

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 que acabas de crear:

   google-adk==2.4.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
   

   Nota: Si se actualiza tu sesión de Cloud Shell o abres una nueva pestaña de la terminal, es posible que debas reactivar el entorno virtual ejecutando source .venv/bin/activate.

4. Instala los paquetes necesarios en tu entorno virtual en la terminal.

   uv pip install -r requirements.txt
   

Crea una cuenta de servicio y configura los permisos de IAM

Antes de compilar el agente, debes crear una cuenta de servicio y configurar los permisos necesarios. Esto garantiza que tu agente pueda llamar a los modelos de Gemini Enterprise Agent Platform y que Cloud Build pueda implementar tu aplicación correctamente.

1. En la terminal, crea una cuenta de servicio dedicada para tu servicio de Cloud Run:

   SA_NAME=lab-service-account
   PROJECT_ID=$(gcloud config get-value project)
   gcloud iam service-accounts create ${SA_NAME} \
       --display-name="Service Account for Zoo Agent"
   

2. Otorga a la cuenta de servicio el rol de Usuario de Gemini Enterprise Agent Platform para que tu agente pueda llamar a Gemini:

   gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/aiplatform.user"
   

3. Configura los permisos de Cloud Build. Dado que los proyectos modernos de Google Cloud restringen los permisos de las cuentas de servicio predeterminadas, debes otorgar a la cuenta de servicio predeterminada de Compute Engine los roles necesarios para compilar e implementar tu contenedor. Ejecuta los siguientes comandos en la terminal:

   PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
   
   # Grant Artifact Registry Writer role
   gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
     --role="roles/artifactregistry.writer"
   
   # Grant Storage Object Viewer role
   gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
     --role="roles/storage.objectViewer"
   
   # Grant Logs Writer role
   gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
     --role="roles/logging.logWriter"
   

Configura variables de entorno

Ahora, crearás un archivo .env que contendrá las variables de entorno que usan el agente y la secuencia de comandos de implementación.

1. Como ya definiste las variables en tu sesión de terminal durante el paso anterior, puedes crear el archivo .env directamente:

   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-3.5-flash"
   EOF
   

   Verifica el archivo .env y asegúrate de que se hayan asignado valores a PROJECT_ID, PROJECT_NUMBER y SERVICE_ACCOUNT. Si faltan los detalles del proyecto, ejecute gcloud projects list para encontrarlos. Para verificar que la cuenta de servicio existe, ejecuta gcloud iam service-accounts list.

8. Crea el flujo de trabajo del agente

Crea el 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. Para crear el archivo agent.py principal, pega 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
   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 ---
   
   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
   api_wrapper = WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=1000)
   api_wrapper.wiki_client.set_user_agent("ZooTourGuideAgent/1.0")
   wikipedia_tool = LangchainTool(
       tool=WikipediaQueryRun(api_wrapper=api_wrapper)
   )
   

   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?", la herramienta guarda esa pregunta específica en la memoria del agente para que los otros agentes del flujo de trabajo sepan qué investigar.
     Funcionamiento: Es una función de Python que escribe la instrucción del visitante en el diccionario compartido tool_context.state. El contexto de la herramienta representa la memoria a corto plazo del agente para una sola conversación. Los datos que guarda el agente 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?", la herramienta permite que el agente busque la respuesta en Wikipedia. (Puedes obtener más información para configurar y llamar a la herramienta de Wikipedia en la guía Uso de la herramienta de Wikipedia).
     Funcionamiento: Actúa como un adaptador, lo que permite que nuestro agente use la herramienta creada previamente WikipediaQueryRun de la biblioteca LangChain.
     
     
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 pasaron a través de State) y usa las habilidades lingüísticas del LLM para transformarlos en una respuesta amigable y en tono conversacional.
     
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.
   Funcionamiento: 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 función principal es organizar el proceso general. Actúa como el controlador inicial y administra el primer turno de la conversación.
   

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

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
api_wrapper = WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=1000)
api_wrapper.wiki_client.set_user_agent("ZooTourGuideAgent/1.0")
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=api_wrapper)
)

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

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

Verifica la estructura final

Antes de la implementación, verifica que el directorio de tu 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 .gcloudignore y carga variables de entorno

1. Crea un archivo .gcloudignore en el directorio zoo_guide_agent para evitar subir tu entorno virtual (.venv/) y otros archivos innecesarios a Google Cloud:

   cloudshell edit .gcloudignore
   

2. Agrega el siguiente contenido a .gcloudignore:

   .gcloudignore
   .git
   .gitignore
   .venv/
   venv/
   __pycache__/
   .env
   

3. Carga las variables de entorno en la sesión de la terminal:

   source .env
   

   Nota: Si se actualiza tu sesión de Cloud Shell o abres una nueva pestaña de la terminal, debes volver a ejecutar source .env para volver a cargar estas variables antes de implementar.

10. 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==2.4.0 \
   adk deploy cloud_run \
     --project=$PROJECT_ID \
     --region=europe-west1 \
     --service_name=zoo-tour-guide \
     --with_ui \
     . \
     -- \
     --allow-unauthenticated \
     --set-env-vars=MODEL=$MODEL,GOOGLE_GENAI_USE_ENTERPRISE=true,GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=global \
     --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.

   Nota: El siguiente comando de implementación tardará unos minutos en terminar de ejecutarse.

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

11. Prueba el agente implementado

Ahora que tu agente está activo en Cloud Run, realizará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 nueva conversación.
4. Observa el resultado. El agente debería responder rápidamente con su saludo, que será algo así:

   "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?
   

   

Explicación del flujo del agente

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

1. El agente de bienvenida del zoológico (la 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. Aprovecha 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 pule la redacción.
• 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 el 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 sobre el ADK
2. Cómo crear herramientas personalizadas para agentes del ADK

12. 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, las imágenes y los recursos de Cloud Run

Si deseas conservar el proyecto de Google Cloud, pero quitar los recursos específicos que se crearon en este lab, debes borrar el servicio en ejecución, el registro de imágenes de contenedor, el bucket de almacenamiento de origen temporal y la cuenta de servicio.

• 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
  gsutil rm -r gs://run-sources-${PROJECT_ID}-europe-west1
  gcloud iam service-accounts delete lab-service-account@${PROJECT_ID}.iam.gserviceaccount.com --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 todos los recursos (incluida la cuenta de servicio y los artefactos de compilación ocultos) se quiten por completo.

• En la terminal, ejecuta el siguiente comando (reemplaza [YOUR_PROJECT_ID] por el ID real de tu proyecto):

  gcloud projects delete $PROJECT_ID
  

  Borrar un proyecto es irreversible. Antes de continuar, asegúrate de que este proyecto no se use para ningún otro trabajo.

13. Felicitaciones

Compilaste e implementaste correctamente una aplicación de IA multiagente 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í puedes ver 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

14. Encuesta

Resultado:

¿Cómo usarás este instructivo?

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