GSP1350

Descripción general

Este lab se enfoca en la implementación de un servicio de agente para clientes con el Kit de desarrollo de agentes (ADK) para crear un agente de IA que use herramientas remotas, como un servidor de MCP. El principio arquitectónico clave que se demuestra en este lab es la separación de responsabilidades, con una capa de razonamiento distinta (el agente) que se comunica con una capa de herramientas diferente (el servidor de MCP) a través de una API segura.

En este lab, se implementó previamente un servidor de MCP que proporciona datos sobre los animales en un zoológico ficticio a los LLM, por ejemplo, cuando se usa Gemini CLI. En el lab, crearás un agente guía, que consiste en una aplicación de Python, para el zoológico ficticio. El agente usará el servidor de MCP para acceder a detalles sobre los animales del zoológico y también usará Wikipedia para crear una experiencia óptima de guía.

Por último, implementarás el agente guía en Google Cloud Run para que todos los visitantes del zoológico puedan acceder a él en lugar de solo ejecutarse de forma local.

Requisitos previos

• Un servidor de MCP en ejecución en Cloud Run o su URL de servicio asociada
• Un proyecto de Google Cloud con la facturación habilitada

Qué aprenderás

En este lab, aprenderás a realizar las siguientes tareas:

• Estructurar un proyecto de Python para la implementación del ADK
• Implementar un agente que usa herramientas con google-adk
• Conectar un agente a un servidor de MCP remoto para acceder a su conjunto de herramientas
• Implementar una aplicación de Python como contenedor sin servidores en Cloud Run
• Configurar la autenticación segura de servicio a servicio con roles de IAM
• 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

¿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. Cloud Run se encarga 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 de Cloud Run

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.

Escalado automático

• Si 0 personas usan tu app, se ejecutan 0 instancias (pagas $0 cuando está inactiva).
• Si recibe 1,000 solicitudes, se inician tantas copias como sean necesarias.

Sin estado de forma predeterminada

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

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

• Se factura por solicitud más tiempo de procesamiento (hasta 100 ms).
• No pagas por recursos inactivos como con una VM tradicional.

Configuración y requisitos

Antes de hacer clic en el botón Comenzar lab

Lee estas instrucciones. Los labs cuentan con un temporizador que no se puede pausar. El temporizador, que comienza a funcionar cuando haces clic en Comenzar lab, indica por cuánto tiempo tendrás a tu disposición los recursos de Google Cloud.

Este lab práctico te permitirá realizar las actividades correspondientes en un entorno de nube real, no en uno de simulación o demostración. Para ello, se te proporcionan credenciales temporales nuevas que utilizarás para acceder a Google Cloud durante todo el lab.

Para completar este lab, necesitarás lo siguiente:

• Acceso a un navegador de Internet estándar. Se recomienda el navegador Chrome.

Nota: Usa una ventana del navegador privada o de incógnito (opción recomendada) para ejecutar el lab. Así evitarás conflictos entre tu cuenta personal y la cuenta de estudiante, lo que podría generar cargos adicionales en tu cuenta personal.

• Tiempo para completar el lab (recuerda que, una vez que comienzas un lab, no puedes pausarlo).

Nota: Usa solo la cuenta de estudiante para este lab. Si usas otra cuenta de Google Cloud, es posible que se apliquen cargos a esa cuenta.

Activa Cloud Shell

Cloud Shell es una máquina virtual que cuenta con herramientas para desarrolladores. Ofrece un directorio principal persistente de 5 GB y se ejecuta en Google Cloud. Cloud Shell proporciona acceso de línea de comandos a tus recursos de Google Cloud.

1. Haz clic en Activar Cloud Shell en la parte superior de la consola de Google Cloud.

2. Haz clic para avanzar por las siguientes ventanas:

   • Continúa en la ventana de información de Cloud Shell.
   • Autoriza a Cloud Shell para que use tus credenciales para realizar llamadas a la API de Google Cloud.

Cuando te conectes, habrás completado la autenticación, y el proyecto estará configurado con tu Project_ID, . El resultado contiene una línea que declara el Project_ID para esta sesión:

Your Cloud Platform project in this session is set to {{{project_0.project_id | "PROJECT_ID"}}}

gcloud es la herramienta de línea de comandos de Google Cloud. Viene preinstalada en Cloud Shell y es compatible con la función de autocompletado con tabulador.

3. Puedes solicitar el nombre de la cuenta activa con este comando (opcional):

gcloud auth list

4. Haz clic en Autorizar.

Resultado:

ACTIVE: * ACCOUNT: {{{user_0.username | "ACCOUNT"}}} To set the active account, run: $ gcloud config set account `ACCOUNT`

5. Puedes solicitar el ID del proyecto con este comando (opcional):

gcloud config list project

Resultado:

[core] project = {{{project_0.project_id | "PROJECT_ID"}}} Nota: Para obtener toda la documentación de gcloud, en Google Cloud, consulta la guía con la descripción general de gcloud CLI.

Tarea 1: Descarga e instala el ADK y crea una carpeta de proyecto

En esta tarea, habilitarás las APIs pertinentes y crearás una carpeta de proyecto para almacenar el código fuente de la implementación de tu proyecto de Python.

Habilita las APIs y establece las variables de entorno

1. En Cloud Shell, haz clic en Abrir editor para abrir el editor de Cloud Shell en tu directorio principal.
2. En la barra de acciones del editor de Cloud Shell, haz clic en Ver > Terminal.

Nota: Es posible que debas agrandar la ventana del navegador para encontrar la opción de menú Ver.

Usa esta ventana como tu IDE, con el editor de Cloud Shell (arriba) y la terminal de Cloud Shell (abajo), durante el resto de este lab.

Cierra cualquier instructivo adicional o panel de Gemini que aparezca en el lado derecho de la pantalla para tener más espacio en la ventana para tu editor de código.

3. En la terminal, ingresa el siguiente comando para configurar tu proyecto:

   gcloud config set project {{{project_0.project_id | filled in at lab start}}}

   Resultado esperado: Deberías obtener un mensaje de resultado que confirme la propiedad actualizada.

Nota: En caso de que Cloud Shell se reinicie o se agote su tiempo de espera, deberás volver a configurar el proyecto.

4. Ejecuta el siguiente comando para habilitar todos los servicios necesarios:

   gcloud services enable \ run.googleapis.com \ artifactregistry.googleapis.com \ cloudbuild.googleapis.com \ aiplatform.googleapis.com \ compute.googleapis.com

   Resultado esperado: Deberías obtener un mensaje de resultado que confirme que la operación se realizó correctamente.

Haz clic en Revisar mi progreso para verificar el objetivo. Habilitar las APIs

Crea los directorios del proyecto

1. Ejecuta el siguiente comando, que creará una carpeta principal en el lab para el código fuente del agente:

   mkdir zoo_guide_agent && cd zoo_guide_agent

2. Luego, ejecuta el siguiente comando para crear un entorno virtual:

   uv venv

3. Ejecuta el siguiente comando para activar el entorno virtual:

   source .venv/bin/activate

Ahora, ya tienes todo listo para crear el archivo requirements.txt. En este archivo, se encuentra una lista de las bibliotecas de Python que necesita tu agente de zoológico.

4. Ejecuta el siguiente comando para crear el archivo en el directorio zoo_guide_agent e implementarlo en el editor de Cloud Shell para que puedas editarlo:

   cloudshell edit requirements.txt

5. Agrega lo siguiente al archivo requirements.txt y presiona CTRL + S para guardar los cambios:

   google-adk==1.12.0 langchain-community wikipedia

6. Ejecuta el siguiente comando en la terminal para permitir que el administrador de paquetes uv instale tus paquetes de Python:

   uv pip install -r requirements.txt

7. Configura variables para tu proyecto, región y usuario actuales con estos comandos:

   export PROJECT_ID=$(gcloud config get-value project) export REGION=$(gcloud compute project-info describe \ --format="value(commonInstanceMetadata.items[google-compute-default-region])") export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)") export SERVICE_ACCOUNT="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"

Nota: En caso de que Cloud Shell se reinicie o se agote su tiempo de espera, deberás volver a inicializar las variables anteriores.

8. Crea y abre un archivo .env para autenticar el agente en el directorio zoo_guide_agent con el siguiente comando:

   cloudshell edit .env

Se abrirá el directorio que contiene el archivo .env en el editor de Cloud Shell.

9. Agrega lo siguiente al archivo .env y guarda los cambios:

   MODEL="{{{ project_0.startup_script.gemini_flash_model_id | filled in at lab start }}}" SERVICE_ACCOUNT="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"

Conéctate al endpoint seguro del servidor de MCP

En esta sección, establecerás una conexión con tu servidor de MCP remoto.

1. Vuelve a la terminal de Cloud Shell y ejecuta el siguiente comando para otorgarle permiso a la identidad de servicio de Cloud Run para llamar al servidor de MCP remoto:

   gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:$SERVICE_ACCOUNT" \ --role="roles/run.invoker"

2. Ejecuta el siguiente comando para guardar la URL del servidor de MCP en una variable de entorno:

   echo -e "\nMCP_SERVER_URL=https://zoo-mcp-server-${PROJECT_NUMBER}.${REGION}.run.app/mcp/" >> .env

3. Luego, crea el archivo __init__.py. Este archivo le indica a Python que el directorio zoo_guide_agent es un paquete:

   cloudshell edit __init__.py

4. En el editor de Cloud Shell que se abrirá, agrega el siguiente código a __init__.py y guarda los cambios:

   from . import agent

Tarea 2: Crea el flujo de trabajo del agente

En esta tarea, configurarás el flujo de trabajo del agente guía del zoológico. Primero, importarás las bibliotecas pertinentes para la configuración inicial. Luego, definirás las capacidades del agente del zoológico (qué herramientas usa) y los agentes especialistas. Luego, definirás el agente de flujo de trabajo y, por último, organizarás el flujo de trabajo principal.

Crea el archivo principal agent.py

• Vuelve a la terminal de Cloud Shell y ejecuta el siguiente comando para crear el archivo principal agent.py, que se abrirá en el editor de Cloud Shell para que puedas pegar el código completo de tu sistema de varios agentes en los pasos que siguen:

  cloudshell edit agent.py

Paso 1: Importa las bibliotecas y realiza la configuración inicial

Este primer bloque 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.

• Agrega el siguiente código al archivo agent.py:

  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.mcp_tool.mcp_toolset import MCPToolset, StreamableHTTPConnectionParams 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 # --- Configuración del registro y el entorno --- cloud_logging_client = google.cloud.logging.Client() cloud_logging_client.setup_logging() load_dotenv() model_name = os.getenv("MODEL")

Paso 2: Define las herramientas (las capacidades del agente)

La eficacia de un agente depende de las herramientas que puede usar. En esta sección, definirás todas las capacidades de tu agente, incluida una función personalizada para guardar datos, una herramienta de MCP que se conecta a tu servidor de MCP seguro y una herramienta de Wikipedia.

• Agrega el siguiente código a la parte inferior de agent.py:

  # Saluda al usuario y guarda su instrucción def add_prompt_to_state( tool_context: ToolContext, prompt: str ) -> dict[str, str]: """Guarda la instrucción inicial del usuario en el estado.""" tool_context.state["PROMPT"] = prompt logging.info(f"[State updated] Added to PROMPT: {prompt}") return {"status": "success"} # Configuración de la herramienta de MCP que se conectará al servidor de MCP del zoológico mcp_server_url = os.getenv("MCP_SERVER_URL") if not mcp_server_url: raise ValueError("The environment variable MCP_SERVER_URL is not set.") def get_id_token(): """Obtén un token de ID para realizar la autenticación con el servidor de MCP""" target_url = os.getenv("MCP_SERVER_URL") audience = target_url.split('/mcp/')[0] request = google.auth.transport.requests.Request() id_token = google.oauth2.id_token.fetch_id_token(request, audience) return id_token """ # Usa este código si utilizas el servidor de MCP público y marca como comentario el siguiente código que definemcp_tools mcp_tools = MCPToolset( connection_params=StreamableHTTPConnectionParams( url=mcp_server_url ) ) """ mcp_tools = MCPToolset( connection_params=StreamableHTTPConnectionParams( url=mcp_server_url, headers={ "Authorization": f"Bearer {get_id_token()}", }, ), ) # Configuración de la herramienta de Wikipedia wikipedia_tool = LangchainTool( tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper()) )

Explicación de las tres herramientas

• add_prompt_to_state: 📝 Esta herramienta recuerda lo que preguntan los visitantes 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.

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

• MCPToolset: 🦁 Se usa para conectar el agente guía al servidor de MCP del zoológico previamente implementado en este lab. Este servidor tiene herramientas especiales para buscar información específica sobre los animales del zoológico, como su nombre, edad y recinto.

  Funcionamiento: Se conecta de forma segura a la URL del servidor privado del zoológico. Usa get_id_token para obtener automáticamente una "tarjeta llave" segura (un token de ID de cuenta de servicio) con la que verificar tu identidad y obtener acceso.

• 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 tu agente use la herramienta precompilada WikipediaQueryRun de la biblioteca LangChain.

Recursos:

• MCPToolset
• Herramientas de funciones
• State

Paso 3: Define los agentes especialistas

En esta sección, definirás dos agentes especialistas: el agente investigador y el formateador de respuestas. El agente investigador es el "cerebro" de tu operación. Este agente toma la instrucción del usuario del State compartido, examina sus potentes herramientas (la herramienta del servidor de MCP del zoológico y la herramienta de Wikipedia) y decide cuáles usar para encontrar la respuesta.

El rol del agente formateador de respuestas es la presentación. No usa ninguna herramienta para encontrar información nueva. En cambio, 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.

• Agrega el siguiente código a la parte inferior de agent.py:

  # 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=""" Eres un asistente de investigación útil. Tu objetivo es responder por completo la INSTRUCCIÓN del usuario. Tienes acceso a dos herramientas: 1. Una herramienta para obtener datos específicos sobre los animales DE NUESTRO ZOOLÓGICO (nombres, edades, ubicaciones). 2. Una herramienta para buscar información general en Wikipedia (datos, esperanza de vida, dieta, hábitat). Primero, analiza la INSTRUCCIÓN del usuario. - Si la instrucción solo puede responderse con una herramienta, usa esa herramienta. - Si la instrucción es compleja y requiere información de la base de datos del zoológico Y Wikipedia, DEBES usar ambas herramientas para recopilar toda la información necesaria. - Sintetiza los resultados de las herramientas que usas en resultados de datos preliminares. PROMPT: {{ PROMPT }} """, tools=[ mcp_tools, wikipedia_tool ], output_key="research_data" # Una clave para almacenar los hallazgos combinados ) # 2. Response Formatter Agent response_formatter = Agent( name="response_formatter", model=model_name, description="Synthesizes all information into a friendly, readable response.", instruction=""" Eres la voz amigable del guía del zoológico. Tu tarea es tomar los RESEARCH_DATA y presentarlos al usuario en una respuesta completa y útil. - Primero, presenta la información específica del zoológico (como nombres de los animales, sus edades y dónde encontrarlos). - Luego, agrega los datos generales interesantes encontrados durante la investigación. - Si falta información, presenta la que tienes. - Usa un tono conversacional y atractivo. RESEARCH_DATA: {{ research_data }} """ )

Paso 4: Define el agente de flujo de trabajo

El agente de flujo de trabajo actúa como el encargado de la "oficina administrativa" del recorrido por el zoológico. Toma una solicitud de investigación y garantiza que los dos agentes que definiste en el paso 3 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 del zoológico.

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.

• Agrega el siguiente bloque de código a la parte inferior de agent.py:

  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, # Paso 1: Recopila todos los datos response_formatter, # Paso 2: Da formato a la respuesta final ] )

Paso 5: Organiza el flujo de trabajo principal

El flujo de trabajo principal se designa a través de root_agent, que es lo que el framework de ADK usa como punto de partida para todas las conversaciones nuevas. La función principal de este agente es organizar el proceso general. Actúa como el controlador inicial y administra el primer turno de la conversación.

• Agrega este último bloque de código a la parte inferior de agent.py y guarda los cambios:

  root_agent = Agent( name="greeter", model=model_name, description="The main entry point for the Zoo Tour Guide.", instruction=""" - Dile al usuario cómo lo ayudarás a obtener información sobre los animales que tenemos en el zoo. - Cuando el usuario responda, usa la herramienta "add_prompt_to_state" para guardar su respuesta. Después de usar la herramienta, transfiere el control al agente "tour_guide_workflow". """, tools=[add_prompt_to_state], sub_agents=[tour_guide_workflow] )

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. Ahora, pasemos a la implementación.

Tarea 3: Prepara la aplicación para la implementación

Con el entorno local listo, el siguiente paso es preparar tu proyecto de Google Cloud para la implementación del agente guía del zoológico.

Esto implica una verificación final de la estructura del archivo del agente para garantizar que sea compatible con el comando de implementación. Lo que es más importante, debes configurar un permiso de IAM fundamental que permite que tu servicio de Cloud Run implementado actúe en tu nombre y llame a los modelos de Vertex AI. Completar este paso garantiza que el entorno de nube esté listo para ejecutar tu agente correctamente.

1. Vuelve a la terminal de Cloud Shell y ejecuta el siguiente comando para cargar las variables en tu sesión de shell:

   source .env

2. Ejecuta el siguiente comando para otorgarle a la cuenta de servicio el rol de usuario de Vertex AI, que le da permiso para hacer predicciones y llamar a los modelos de Google:

   # Otorga el rol "usuario de Vertex AI" a tu cuenta de servicio gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:$SERVICE_ACCOUNT" \ --role="roles/aiplatform.user"

Tarea 4: 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.

En esta tarea, usarás el comando adk deploy cloud_run, que es 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 para que sea accesible en la Web.

Implementa el agente

1. Ejecuta el siguiente comando para implementar tu agente:

   # Ejecuta el comando de implementación adk deploy cloud_run \ --project=$PROJECT_ID \ --region=$REGION \ --service_name=zoo-tour-guide \ --with_ui \ .

2. Si se te pregunta si quieres continuar o permitir invocaciones sin autenticar a [zoo-tour-guide], escribe Y en cada caso y presiona INTRO.

Nota: Este comando de implementación puede tardar entre 5 y 10 minutos en finalizar su ejecución.

3. Ejecuta el siguiente comando para modificar los parámetros de configuración del servicio de Cloud Run existente:

   gcloud run services update zoo-tour-guide \ --region=$REGION \ --update-labels=dev-tutorial=codelab-adk

Obtén el vínculo de implementación

• Una vez que el agente se haya implementado correctamente en Cloud Run, presiona CTRL y haz clic en la URL del servicio en el resultado para abrirlo en una nueva pestaña del navegador.

  Debería parecerse al siguiente formato. Resultado de la URL del servicio:

  https://zoo-tour-guide-{{{project_0.startup_script.project_number | filled in at lab start}}}.{{{project_0.default_region | filled in at lab start}}}.run.app

Como usaste la marca --with_ui cuando realizaste la implementación en Cloud Run, deberías ver la IU para desarrolladores del ADK.

Nota: Cualquier persona que tenga la URL puede acceder a este agente, por lo que este enfoque es mejor usarlo exclusivamente para pruebas.

Haz clic en Revisar mi progreso para verificar el objetivo. Implementar el agente

Tarea 5: Prueba el agente implementado

Ahora que tu agente está activo en Cloud Run, en esta tarea harás una prueba para confirmar que la implementación se realizó correctamente y que el agente funciona como se espera. Deberás usar la URL pública del servicio 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 que se generó en la tarea anterior en el navegador web o haz clic en la URL en el resultado (debería abrirse en una nueva pestaña del navegador). Se abrirá la IU para desarrolladores del ADK.

2. Activa Transmisión de tokens en la parte superior derecha de la barra de herramientas del ADK.

Ahora puedes interactuar con el agente del zoológico.

3. Escribe hello en el cuadro de instrucción y presiona INTRO para comenzar una nueva conversación.

   Observa el resultado. El agente debería responder rápidamente con su saludo estándar:

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

4. Ahora, interactúa con el agente guía del zoológico. Ingresa la siguiente consulta para iniciar una nueva conversación:

   Where can I find penguins?

   Deberías recibir una respuesta similar a la siguiente:

   

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 potente capacidad de uso de herramientas del modelo de lenguaje para decidir si necesita lo siguiente:

• Datos internos de los registros del zoológico (a través del servidor de MCP)
• Información general de la Web (a través de la API de Wikipedia)
• O, para preguntas complejas, ambos tipos de datos

Su acción: Ejecuta las herramientas necesarias para recopilar todos los datos sin procesar requeridos. Por ejemplo, si se le pregunta: "¿Cuántos años tienen nuestros leones y qué comen en la naturaleza?", llamará al servidor de MCP para obtener las edades y a la herramienta de Wikipedia para obtener la información sobre la dieta.

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.

Próximos pasos y más información

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

• Documentos del ADK
• Cómo crear herramientas personalizadas para agentes del ADK

Tarea 6: Limpia el entorno

En esta tarea, borrarás los recursos de Cloud que creaste en el lab para evitar generar costos futuros.

• Vuelve a la pestaña de la terminal de Cloud Shell y ejecuta el siguiente comando:

  gcloud run services delete zoo-tour-guide --region=$REGION --quiet gcloud artifacts repositories delete cloud-run-source-deploy --location=$REGION --quiet

¡Felicitaciones!

En este lab, exploraste cómo estructurar un proyecto de Python para la implementación con la interfaz de línea de comandos del ADK, implementaste un flujo de trabajo de varios agentes, te conectaste a un servidor de MCP remoto para consumir sus herramientas, aumentaste los datos internos integrando herramientas externas como la API de Wikipedia y, por último, implementaste el agente como un contenedor sin servidores en Cloud Run.

Actualización más reciente del manual: 13 de octubre de 2025

Prueba más reciente del lab: 13 de octubre de 2025

Copyright 2026 Google LLC. All rights reserved. Google y el logotipo de Google son marcas de Google LLC. Los demás nombres de productos y empresas pueden ser marcas de las respectivas empresas a las que estén asociados.