1. Introducción
Este lab se enfoca en la implementación y la implementación de un servicio de agente cliente. Usarás el kit de desarrollo de agentes (ADK) para compilar un agente de IA que use herramientas remotas, como el servidor de MCP creado en el lab 1. El principio arquitectónico clave que se demuestra es la separación de responsabilidades, con una capa de razonamiento distinta (el agente) que se comunica con una capa de herramientas distinta (el servidor de MCP) a través de una API segura.
En el lab 1, creaste un servidor de MCP que proporciona datos sobre los animales de un zoológico ficticio a los LLM, por ejemplo, cuando se usa la CLI de Gemini. En este lab, compilaremos un agente de guía turístico para el zoológico ficticio. El agente usará el mismo servidor de MCP del lab 1 para acceder a los detalles sobre los animales del zoo y también usará Wikipedia para crear la mejor experiencia de guía turística.
Por último, implementaremos el agente de guía turístico en Google Cloud Run para que todos los visitantes del zoológico puedan acceder a él en lugar de que solo se ejecute 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 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 conectar un agente a un servidor de MCP remoto para su conjunto de herramientas
- 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 recursos de Cloud para evitar costos futuros
Requisitos
- Una cuenta de Google Cloud y un proyecto de Google Cloud
- Un navegador web, como Chrome
2. ¿Por qué realizar implementaciones 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.
Piensa en ella como una tienda temporal: solo abre y usa recursos cuando llegan los clientes (solicitudes). Cuando no hay clientes, se cierra por completo y no pagas por una tienda vacía.
Características clave
Ejecuta contenedores en cualquier lugar:
- Aportas un contenedor (imagen de Docker) que tiene tu app dentro.
- Cloud Run lo ejecuta en la infraestructura de Google.
- No tendrás que preocuparte por aplicar parches al SO, configurar VMs ni escalar.
Ajuste de escala automático:
- Si 0 personas usan tu app → se ejecutan 0 instancias (pagas USD 0 cuando está inactiva).
- Si recibe 1,000 solicitudes, se activan tantas copias como sean necesarias.
Sin estado de forma predeterminada:
- Cada solicitud puede dirigirse 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 y cuando se ejecute en un contenedor de Linux, a Cloud Run no le importa si 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 los recursos inactivos, como con una VM tradicional.
3. Configuración y requisitos
Configuración del entorno de autoaprendizaje
- Accede a Google Cloud Console y crea un proyecto nuevo o reutiliza uno existente. Si aún no tienes una cuenta de Gmail o de Google Workspace, debes crear una.
- El Nombre del proyecto es el nombre visible de los participantes de este proyecto. Es una cadena de caracteres que no se utiliza en las APIs de Google. Puedes actualizarla cuando quieras.
- El ID del proyecto es único en todos los proyectos de Google Cloud y es inmutable (no se puede cambiar después de configurarlo). La consola de Cloud genera automáticamente una cadena única. Por lo general, no importa cuál sea. En la mayoría de los codelabs, deberás hacer referencia al ID de tu proyecto (suele identificarse como
PROJECT_ID). Si no te gusta el ID que se generó, podrías generar otro aleatorio. También puedes probar uno propio y ver si está disponible. No se puede cambiar después de este paso y se usa el mismo durante todo el proyecto. - Recuerda que hay un tercer valor, un número de proyecto, que usan algunas APIs. Obtén más información sobre estos tres valores en la documentación.
- A continuación, deberás habilitar la facturación en la consola de Cloud para usar las APIs o los recursos de Cloud. Ejecutar este codelab no costará mucho, tal vez nada. Para cerrar recursos y evitar que se generen cobros más allá de este instructivo, puedes borrar los recursos que creaste o borrar el proyecto. Los usuarios nuevos de Google Cloud son aptos para participar en el programa Prueba gratuita de $300.
Inicia Cloud Shell
Navega al Editor de Cloud Shell.
Si la terminal no aparece en la parte inferior de la pantalla, ábrela:
- Haz clic en Terminal.
- Haz clic en Terminal nueva.
En la terminal, configura tu proyecto con este comando. Si completaste el lab 1, asegúrate de usar el mismo ID del proyecto:
gcloud config set project [YOUR-PROJECT-ID]
Si no recuerdas el ID de tu proyecto, puedes enumerar todos tus IDs de proyecto con el siguiente comando:
gcloud projects list | awk '/PROJECT_ID/{print $2}'
4. Si se te solicita autorización, haz clic en Autorizar para continuar.
5. Deberías ver el siguiente mensaje:
Updated property [core/project].
If you see a `WARNING` and are asked `Do you want to continue (Y/n)?`,
then you have likely entered the project ID incorrectly. Press `n`,
press `Enter`, and try to run the `gcloud config set project` command again.
4. Antes de comenzar
Habilita las APIs y configura las variables de entorno
Habilita todos los servicios necesarios con el siguiente comando:
gcloud services enable \
run.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com \
aiplatform.googleapis.com \
compute.googleapis.com
Resultado esperado
Operation "operations/acat.p2-[GUID]" finished successfully.
Configura tu región predeterminada para usar los modelos de incorporación de Vertex AI. Obtén más información sobre las ubicaciones disponibles para Vertex AI. En el ejemplo, usamos la región europe-west1.
gcloud config set compute/region europe-west1
5. Descarga e instala el ADK, y crea la carpeta del proyecto
Crea los directorios del proyecto.
Este comando crea una carpeta principal para el lab del código fuente del agente.
cd && mkdir zoo_guide_agent && cd zoo_guide_agent
Crea un entorno virtual.
python3 -m venv .venv
Active el entorno virtual.
source .venv/bin/activate
Crea el archivo requirements.txt. En este archivo, se enumeran las bibliotecas de Python que necesita tu agente. El siguiente comando crea el archivo y lo completa.
cloudshell edit requirements.txt
google-adk==1.12.0
langchain-community
wikipedia
Debes ejecutar el comando desde el directorio principal del proyecto, zoo_guide_agent.
pip install -r requirements.txt
Configura variables para tu proyecto, región y usuario actuales. Esta es una forma más sólida de ejecutar estos comandos.
export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_REGION=$(gcloud config get-value compute/region)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export SERVICE_ACCOUNT="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"
Crea y abre un archivo .env para autenticar el agente en el directorio zoo_guide_agent.
cloudshell edit .env
El comando cloudshell edit abrirá el archivo .env en el editor que se encuentra sobre la terminal. Ingresa lo siguiente en el archivo .env y vuelve a la terminal.
MODEL="gemini-2.5-flash"
SERVICE_ACCOUNT="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"
Se agrega la URL del servidor de MCP. Si completaste el lab 1, sigue estos pasos para usar el servidor de MCP que creaste en ese lab:
- Otorga permiso a la identidad del 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"
- Guarda la URL del servidor de MCP del lab 1 en una variable de entorno.
echo -e "\nMCP_SERVER_URL=https://zoo-mcp-server-${PROJECT_NUMBER}.europe-west1.run.app/mcp/" >> .env
Si usas un vínculo público del servidor de MCP, ejecuta el siguiente comando y reemplaza PROJECT_NUMBER por lo que se proporciona.
echo -e "\nMCP_SERVER_URL=https://zoo-mcp-server-${PROJECT_NUMBER}.europe-west1.run.app/mcp/" >> .env
6. Crea un flujo de trabajo del agente
Crea el archivo init.py
Crea el archivo init.py. Este archivo le indica a Python que el directorio zoo_guide_agent es un paquete.
cloudshell edit __init__.py
El comando anterior abre el editor de código. Agrega el siguiente código a __init__.py:
from . import agent
Crea el archivo main agent.py
Crea el archivo principal agent.py. Este comando crea el archivo de Python y pega el código completo de tu sistema multiagente.
cloudshell edit agent.py
Paso 1: Importaciones y 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 la URL de tu modelo y servidor.
Agrega el siguiente código a tu 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
# --- Setup Logging and Environment ---
cloud_logging_client = google.cloud.logging.Client()
cloud_logging_client.setup_logging()
load_dotenv()
model_name = os.getenv("MODEL")
Paso 2: Definición de las herramientas (las capacidades del agente)
Un agente solo es tan bueno como las herramientas que puede usar. En esta sección, definimos todas las capacidades que tendrá nuestro agente, incluida una función personalizada para guardar datos, una herramienta de MCP que se conecta a nuestro servidor de MCP seguro y una herramienta de Wikipedia.
Agrega el siguiente código a la parte inferior de agent.py:
# 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 MCP Tool to connect to the Zoo MCP server
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():
"""Get an ID token to authenticate with the MCP server."""
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
"""
# Use this code if you are using the public MCP Server and comment out the code below defining mcp_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()}",
},
),
)
# Configuring the Wikipedia Tool
wikipedia_tool = LangchainTool(
tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())
)
Explicación de las tres 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 demás 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 tool_context.state compartido. Este contexto de la herramienta representa la memoria a corto plazo del agente para una sola conversación. Los datos que guarda un agente en el estado pueden ser leídos por el siguiente agente en el flujo de trabajo.
MCPToolset🦁
Se usa para conectar el agente de guía turística al servidor de MCP del zoo creado en el lab 1. Este servidor tiene herramientas especiales para buscar información específica sobre nuestros animales, como su nombre, edad y recinto.
Cómo: Se conecta de forma segura a la URL del servidor privado del zoo. Usa get_id_token para obtener automáticamente una "tarjeta de acceso" segura (un token de ID de cuenta de servicio) para demostrar su identidad y obtener acceso.
LangchainTool🌍
Esto le proporciona al agente de guía turística conocimiento general del mundo. Cuando un visitante hace una pregunta que no está en la base de datos del zoo, como "¿Qué comen los leones en la naturaleza?", esta herramienta le permite al agente buscar la respuesta en Wikipedia.
Cómo: Actúa como un adaptador, lo que permite que nuestro agente use la herramienta WikipediaQueryRun prediseñada de la biblioteca de LangChain.
Recursos:
Paso 3: Definir los agentes especialistas
A continuación, definiremos el agente de investigador y el agente de formato de respuesta. El agente de investigación es el "cerebro" de nuestra operación. Este agente toma la instrucción del usuario del State compartido, examina sus potentes herramientas (la herramienta del servidor de MCP de Zoo y la herramienta de Wikipedia) y decide cuáles usar para encontrar la respuesta.
El rol del agente de formato de respuestas es la presentación. No usa ninguna herramienta para encontrar información nueva. En cambio, toma los datos sin procesar recopilados por el agente de investigación (que se pasan a través del estado) y usa las habilidades lingüísticas del LLM para transformarlos en una respuesta amigable y conversacional.
Agrega el siguiente código al final 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="""
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=[
mcp_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 }}
"""
)
Paso 4: El agente de flujo de trabajo
El agente de flujo de trabajo actúa como el administrador de "back-office" del recorrido por el zoo. Toma la solicitud de investigación y garantiza que los dos agentes que definimos anteriormente realicen su trabajo en el orden correcto: primero la investigación y, luego, el formato. Esto 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, pasando automáticamente la memoria compartida de uno a otro.
Agrega este 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, # Step 1: Gather all data
response_formatter, # Step 2: Format the final response
]
)
Paso final: Ensambla el flujo de trabajo principal 
Este agente se designa como root_agent, que el framework del ADK usa como punto de partida para todas las conversaciones nuevas. Su función principal es coordinar el proceso general. Actúa como el controlador inicial y administra el primer turno de la conversación.
Agrega este bloque de código final al final de agent.py:
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]
)
Tu archivo agent.py ya está completo. Si lo construyes de esta manera, puedes ver cómo cada componente (herramientas, agentes trabajadores y agentes administradores) tiene un rol específico en la creación del sistema inteligente final. A continuación, la implementación.
7. Prepara la aplicación para la implementación
Con tu entorno local listo, el siguiente paso es preparar tu proyecto de Google Cloud para la implementación. Esto implica una verificación final de la estructura de archivos de tu agente para garantizar que sea compatible con el comando de implementación. Lo que es más importante, configuras un permiso de IAM crítico 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.
Carga las variables en tu sesión de shell ejecutando el comando source.
source .env
Otorga a la cuenta de servicio el rol de usuario de Vertex AI, que le otorga permiso para realizar predicciones y 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"
8. Implementa el agente con la CLI del ADK
Con tu 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, compila 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.
Crea un archivo .gcloudignore
Para reducir el tiempo de implementación, queremos crear un archivo .gcloudignore. Para ello, ejecuta los siguientes comandos.
cloudshell edit .gcloudignore
El comando cloudshell edit abrirá el archivo .gcloudignore en el editor que se encuentra sobre la terminal. Escribe lo siguiente en el archivo y guárdalo. Luego, vuelve a la terminal para ejecutar los comandos de implementación en la siguiente sección.
.venv/
Implementar
Ejecuta los siguientes comandos para implementar tu agente.
# Run the deployment command
adk deploy cloud_run \
--project=$PROJECT_ID \
--region=europe-west1 \
--service_name=zoo-tour-guide \
--with_ui \
.
gcloud run services update zoo-tour-guide \
--region=europe-west1 \
--update-labels=dev-tutorial=codelab-adk
Instrucciones de aceptación
Es posible que aparezca el siguiente mensaje:
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)?
Escribe Y y presiona INTRO.
Es posible que aparezca el siguiente mensaje:
Allow unauthenticated invocations to [your-service-name] (y/N)?.
Para este lab, queremos permitir invocaciones no autenticadas para facilitar las pruebas. Escribe y y presiona Intro.
Obtén el vínculo de implementación
Cuando la ejecución se realice 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). Copia esta URL para la siguiente tarea.
9. 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 según lo previsto. 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, luego, interactuar con el agente.
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.
Activa Token Streaming en la esquina superior derecha.
Ahora puedes interactuar con el agente del zoológico.
Escribe hello y presiona Intro para iniciar una conversación nueva.
Observa el resultado. El agente debería responder rápidamente con su saludo:
"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?"
Explicación del flujo del agente
Tu sistema funciona como un equipo inteligente de varios agentes. El proceso se administra mediante una secuencia clara para garantizar un flujo fluido y eficiente desde la pregunta de un usuario hasta la respuesta final y detallada.
1. El encargado de recepción del zoológico (el mostrador de bienvenida)
Todo 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 Greeter usa su herramienta add_prompt_to_state para capturar sus palabras exactas (p.ej., "Cuéntame sobre los leones") y guárdalos en la memoria del sistema.
La transferencia: Después de guardar la instrucción, se pasa el control de inmediato a su subagente, tour_guide_workflow.
2. El investigador integral (el superinvestigador)
Este es el primer paso del 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 formar 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 zoo (a través del servidor de MCP)
- Conocimiento general de la Web (a través de la API de Wikipedia)
- O, para preguntas complejas, ambas.
Su acción: Ejecuta las herramientas necesarias para recopilar todos los datos sin procesar requeridos. Por ejemplo, si se le pregunta: "¿Qué edad 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 información sobre la dieta.
3. El formateador de respuestas (el presentador)
Una vez que el Comprehensive Researcher recopiló todos los hechos, este es el agente final que se ejecuta.
Su trabajo: Actuar como la voz amigable del guía del tour por el zoológico. Toma los datos sin procesar (que podrían provenir de una o ambas fuentes) y los depura.
Su acción: Sintetiza toda la información en una sola respuesta coherente y atractiva. Siguiendo sus instrucciones, primero presenta la información específica del zoo y, luego, agrega los datos generales interesantes.
El resultado final: El texto que genera 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 para compilar agentes, consulta los siguientes recursos:
10. Limpia el entorno
gcloud run services delete zoo-tour-guide --region=europe-west1 --quiet
gcloud artifacts repositories delete cloud-run-source-deploy --location=europe-west1 --quiet
11. Felicitaciones
Felicitaciones por completar el codelab.
Temas abordados
- Cómo estructurar un proyecto de Python para la implementación con la interfaz de línea de comandos del ADK
- Cómo implementar un flujo de trabajo multiagente con SequentialAgent y ParallelAgent
- Cómo conectarse a un servidor de MCP remoto con MCPToolset para consumir sus herramientas
- Cómo aumentar los datos internos integrando herramientas externas, como la API de Wikipedia
- Cómo implementar un agente como un contenedor sin servidores en Cloud Run con el comando adk deploy
12. Encuesta
Resultado: