Compila un agente de viajes con el kit de herramientas de MCP para bases de datos y el kit de desarrollo de agentes (ADK)
Acerca de este codelab
1. Introducción
En este codelab, compilarás un agente con el kit de desarrollo de agentes (ADK) que utiliza el kit de herramientas de MCP para bases de datos.
En el codelab, seguirás un enfoque paso a paso de la siguiente manera:
- Aprovisiona una base de datos de Cloud SQL para PostgreSQL que tenga la base de datos de hoteles y los datos de muestra.
- Configura MCP Toolbox para bases de datos, que proporciona acceso a los datos.
- Diseña y desarrolla un agente con el kit de desarrollo de agentes (ADK) que usará el kit de herramientas de MCP para responder las consultas del usuario.
- Explora opciones para probar el agente y MCP Toolbox for Databases de forma local y en Google Cloud a través del servicio de Cloud Run.
Actividades
- Diseña, compila y, luego, implementa un agente que responda las consultas de los usuarios sobre hoteles en una ubicación o que busque hoteles por nombre.
Qué aprenderás
- Aprovisionar y propagar una base de datos de Cloud SQL para PostgreSQL con datos de muestra
- Configura MCP Toolbox for Databases para la instancia de la base de datos de Cloud SQL para PostgreSQL.
- Diseña y desarrolla un agente con el Kit de desarrollo de agentes (ADK) para responder las consultas de los usuarios.
- Prueba el agente y MCP Toolbox para bases de datos en el entorno local.
- (Opcional) Implementa el agente y el kit de herramientas de MCP para bases de datos en Google Cloud.
Requisitos
- Navegador web Chrome
- Una cuenta de Gmail
- Un proyecto de Cloud con la facturación habilitada
Este codelab, diseñado para desarrolladores de todos los niveles (incluidos los principiantes), usa Python en su aplicación de ejemplo. Sin embargo, no se requiere conocimiento de Python para comprender los conceptos presentados.
2. Antes de comenzar
Crea un proyecto
- En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
- Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Obtén información para verificar si la facturación está habilitada en un proyecto .
- Usarás Cloud Shell, un entorno de línea de comandos que se ejecuta en Google Cloud y que viene precargado con bq. Haz clic en Activar Cloud Shell en la parte superior de la consola de Google Cloud.
- Una vez que te conectes a Cloud Shell, verifica que ya te hayas autenticado y que el proyecto esté configurado con tu ID con el siguiente comando:
gcloud auth list
- En Cloud Shell, ejecuta el siguiente comando para confirmar que el comando gcloud conoce tu proyecto.
gcloud config list project
- Si tu proyecto no está configurado, usa el siguiente comando para hacerlo:
gcloud config set project <YOUR_PROJECT_ID>
- Habilita las APIs requeridas con el siguiente comando. Esto puede tardar unos minutos, así que ten paciencia.
gcloud services enable cloudresourcemanager.googleapis.com \
servicenetworking.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
cloudfunctions.googleapis.com \
aiplatform.googleapis.com \
sqladmin.googleapis.com \
compute.googleapis.com
Si el comando se ejecuta correctamente, deberías ver un mensaje similar al siguiente:
Operation "operations/..." finished successfully.
La alternativa al comando gcloud es buscar cada producto en la consola o usar este vínculo.
Si falta alguna API, puedes habilitarla durante el transcurso de la implementación.
Consulta la documentación para ver los comandos y el uso de gcloud.
3. Cree una instancia de Cloud SQL
Usaremos una instancia de Google Cloud SQL para PostgreSQL para almacenar los datos de nuestros hoteles. Cloud SQL para PostgreSQL es un servicio de base de datos completamente administrado que te ayuda a configurar, mantener, controlar y administrar las bases de datos relacionales de PostgreSQL en Google Cloud Platform.
Ejecuta el siguiente comando en Cloud Shell para crear la instancia:
gcloud sql instances create hoteldb-instance \
--database-version=POSTGRES_15 \
--cpu=2 \
--memory=8GiB \
--region=us-central1 \
--edition=ENTERPRISE \
--root-password=postgres
Este comando tarda entre 3 y 5 minutos en ejecutarse. Una vez que se ejecute correctamente el comando, deberías ver un resultado que indique que se completó, junto con la información de tu instancia de Cloud SQL, como NAME, DATABASE_VERSION, LOCATION, etcétera.
4. Prepara la base de datos de hoteles
Nuestra tarea ahora será crear algunos datos de muestra para nuestro agente de hoteles.
Visita la página de Cloud SQL en la consola de Cloud.Deberías ver el hoteldb-instance listo y creado. Haz clic en el nombre de la instancia (hoteldb-instance) como se muestra a continuación:
En el menú de la izquierda de Cloud SQL, visita la opción de menú Cloud SQL Studio como se muestra a continuación:
Se te pedirá que accedas a Cloud SQL Studio, a través del cual daremos algunos comandos SQL. Selecciona postgres para la opción Base de datos y, para Usuario y Contraseña, el valor que se debe usar es postgres. Haz clic en AUTHENTICATE.
Primero, crearemos la tabla de hoteles según el esquema que se indica a continuación. En uno de los paneles del editor de Cloud SQL Studio, ejecuta la siguiente sentencia SQL:
CREATE TABLE hotels(
id INTEGER NOT NULL PRIMARY KEY,
name VARCHAR NOT NULL,
location VARCHAR NOT NULL,
price_tier VARCHAR NOT NULL,
checkin_date DATE NOT NULL,
checkout_date DATE NOT NULL,
booked BIT NOT NULL
);
Ahora, completemos la tabla hoteles con datos de muestra. Ejecuta el siguiente comando SQL:
INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked)
VALUES
(1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'),
(2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'),
(3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'),
(4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'),
(5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'),
(6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'),
(7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'),
(8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'),
(9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'),
(10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0');
Para validar los datos, ejecutemos una sentencia SELECT SQL como se muestra a continuación:
SELECT * FROM hotels;
Deberías ver una serie de registros en la tabla hoteles, como se muestra a continuación:
Completamos el proceso de configuración de una instancia de Cloud SQL y creamos nuestros datos de muestra. En la siguiente sección, configuraremos MCP Toolbox para bases de datos.
5. Configura MCP Toolbox para bases de datos
MCP Toolbox for Databases es un servidor de MCP de código abierto para bases de datos. Se diseñó teniendo en cuenta el nivel empresarial y la calidad de producción. Te permite desarrollar herramientas de forma más fácil, rápida y segura, ya que controla las complejidades, como el grupo de conexiones, la autenticación y mucho más.
Toolbox te ayuda a crear herramientas de IA generativa que permitan a tus agentes acceder a los datos de tu base de datos. Toolbox proporciona lo siguiente:
- Desarrollo simplificado: Integra herramientas a tu agente en menos de 10 líneas de código, reutiliza herramientas entre varios agentes o frameworks, y, además, implementa nuevas versiones de herramientas con mayor facilidad.
- Mejor rendimiento: prácticas recomendadas, como la agrupación de conexiones, la autenticación y mucho más
- Seguridad mejorada: Autenticación integrada para un acceso más seguro a tus datos
- Observabilidad de extremo a extremo: Métricas y seguimientos listos para usar con compatibilidad integrada para OpenTelemetry.
Toolbox se encuentra entre el framework de orquestación de tu aplicación y tu base de datos, y proporciona un plano de control que se usa para modificar, distribuir o invocar herramientas. Simplifica la administración de tus herramientas, ya que te proporciona una ubicación centralizada para almacenarlas y actualizarlas, lo que te permite compartirlas entre agentes y aplicaciones, y actualizarlas sin tener que volver a implementar la aplicación.
Puedes ver que una de las bases de datos compatibles con MCP Toolbox for Databases es Cloud SQL, y la aprovisionamos en la sección anterior.
Cómo instalar Toolbox
Abre la terminal de Cloud Shell y crea una carpeta llamada mcp-toolbox.
mkdir mcp-toolbox
Ve a la carpeta mcp-toolbox con el siguiente comando:
cd mcp-toolbox
Instala la versión binaria de MCP Toolbox para bases de datos con la siguiente secuencia de comandos:
export VERSION=0.3.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
Ahora tenemos la versión binaria de la caja de herramientas lista para usar. El siguiente paso es configurar la caja de herramientas con nuestras fuentes de datos y otros parámetros de configuración.
Cómo configurar tools.yaml
La forma principal de configurar Toolbox es a través del archivo tools.yaml. Crea un archivo llamado tools.yaml en la misma carpeta, es decir, mcp-toolbox, cuyo contenido se muestra a continuación.
Puedes usar el editor nano que está disponible en Cloud Shell. El comando nano es el siguiente: "nano tools.yaml".
Recuerda reemplazar el valor YOUR_PROJECT_ID por el ID de tu proyecto de Google Cloud.
sources:
my-cloud-sql-source:
kind: cloud-sql-postgres
project: YOUR_PROJECT_ID
region: us-central1
instance: hoteldb-instance
database: postgres
user: postgres
password: postgres
tools:
search-hotels-by-name:
kind: postgres-sql
source: my-cloud-sql-source
description: Search for hotels based on name.
parameters:
- name: name
type: string
description: The name of the hotel.
statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%';
search-hotels-by-location:
kind: postgres-sql
source: my-cloud-sql-source
description: Search for hotels based on location.
parameters:
- name: location
type: string
description: The location of the hotel.
statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%';
toolsets:
my_first_toolset:
- search-hotels-by-name
- search-hotels-by-location
Veamos el archivo en breve:
Sourcesrepresentan las diferentes fuentes de datos con las que puede interactuar una herramienta. Una fuente representa una fuente de datos con la que puede interactuar una herramienta. Puedes definirSourcescomo un mapa en la sección de fuentes de tu archivo tools.yaml. Por lo general, una configuración de fuente contiene toda la información necesaria para conectarse a la base de datos y, luego, interactuar con ella. En nuestro caso, configuramos una sola fuente que apunta a nuestra instancia de Cloud SQL para PostgreSQL con las credenciales. Para obtener más información, consulta la referencia Fuentes.Toolsdefine las acciones que puede realizar un agente, como leer y escribir en una fuente. Una herramienta representa una acción que puede realizar tu agente, como ejecutar una instrucción de SQL. Puedes definirToolscomo un mapa en la sección de herramientas de tu archivo tools.yaml. Por lo general, una herramienta requiere una fuente para actuar. En nuestro caso, definimos dos herramientas:search-hotels-by-nameysearch-hotels-by-location, y especificamos la fuente en la que actúa, junto con el SQL y los parámetros. Para obtener más información, consulta la referencia de Herramientas.- Por último, tenemos
Toolset, que te permite definir grupos de herramientas que deseas poder cargar juntos. Esto puede ser útil para definir diferentes grupos en función del agente o la aplicación. En nuestro caso, tenemos un solo conjunto de herramientas llamadomy_first_toolset, que contiene las dos herramientas que definimos.
Ejecuta el servidor de MCP Toolbox para bases de datos
Ejecuta el siguiente comando (desde la carpeta mcp-toolbox) para iniciar el servidor:
./toolbox --tools-file "tools.yaml"
Idealmente, deberías ver un resultado que indique que el servidor pudo conectarse a nuestras fuentes de datos y que cargó el conjunto de herramientas. A continuación, se muestra un resultado de muestra:
./toolbox --tools-file "tools.yaml"
2025-04-23T14:32:29.564903079Z INFO "Initialized 1 sources."
2025-04-23T14:32:29.565009291Z INFO "Initialized 0 authServices."
2025-04-23T14:32:29.565070176Z INFO "Initialized 2 tools."
2025-04-23T14:32:29.565120847Z INFO "Initialized 2 toolsets."
2025-04-23T14:32:29.565510068Z INFO "Server ready to serve!"
El servidor de MCP Toolbox se ejecuta de forma predeterminada en el puerto 5000. Usemos Cloud Shell para probar esto.
Haz clic en Vista previa web en Cloud Shell, como se muestra a continuación:
Haz clic en Cambiar puerto y establece el puerto en 5000, como se muestra a continuación, y haz clic en Cambiar y obtener vista previa.
Esto debería mostrar el siguiente resultado:
En la URL del navegador, agrega lo siguiente al final de la URL:
/api/toolset
Se deberían mostrar las herramientas que están configuradas actualmente. A continuación, se muestra un resultado de muestra:
{
"serverVersion": "0.3.0+container.12222fe27ae070f2689a0632d60fda45412d1f97",
"tools": {
"search-hotels-by-location": {
"description": "Search for hotels based on location.",
"parameters": [
{
"name": "location",
"type": "string",
"description": "The location of the hotel.",
"authSources": []
}
]
},
"search-hotels-by-name": {
"description": "Search for hotels based on name.",
"parameters": [
{
"name": "name",
"type": "string",
"description": "The name of the hotel.",
"authSources": []
}
]
}
}
}
En el kit de herramientas de MCP para bases de datos, se describe una forma de Python para validar y probar las herramientas, que se documenta aquí. Omitiremos eso y pasaremos directamente al kit de desarrollo de agentes (ADK) en la siguiente sección, que usará estas herramientas.
6. Cómo escribir nuestro agente con el kit de desarrollo de agentes (ADK)
Instala el kit de desarrollo de agentes (ADK)
Abre una nueva pestaña de la terminal en Cloud Shell y crea una carpeta llamada my-agents de la siguiente manera. Navega también a la carpeta my-agents.
mkdir my-agents
cd my-agents
Ahora, crearemos un entorno virtual de Python con venv de la siguiente manera:
python -m venv .venv
Activa el entorno virtual de la siguiente manera:
source .venv/bin/activate
Instala los paquetes de ADK y MCP Toolbox para bases de datos de la siguiente manera:
pip install google-adk toolbox-core
Ahora podrás invocar la utilidad adk de la siguiente manera.
adk
Se mostrará una lista de comandos.
$ adk
Usage: adk [OPTIONS] COMMAND [ARGS]...
Agent Development Kit CLI tools.
Options:
--help Show this message and exit.
Commands:
api_server Starts a FastAPI server for agents.
create Creates a new app in the current folder with prepopulated agent template.
deploy Deploys agent to hosted environments.
eval Evaluates an agent given the eval sets.
run Runs an interactive CLI for a certain agent.
web Starts a FastAPI server with Web UI for agents.
Creamos nuestra primera aplicación de agente
Ahora, usaremos adk para crear un andamiaje para nuestra aplicación de agente de hotel a través del comando adk create con un nombre de app **(hotel-agent-app)**, como se indica a continuación.
adk create hotel-agent-app
Sigue los pasos y selecciona lo siguiente:
- Modelo de Gemini para elegir un modelo para el agente raíz.
- Elige Vertex AI para el backend.
- Se mostrarán el ID y la región predeterminados del proyecto de Google. Selecciona la opción predeterminada.
Choose a model for the root agent:
1. gemini-2.0-flash-001
2. Other models (fill later)
Choose model (1, 2): 1
1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2
You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai
Enter Google Cloud project ID [gcp-experiments-349209]:
Enter Google Cloud region [us-central1]:
Agent created in /home/romin/hotel-agent-app:
- .env
- __init__.py
- agent.py
Observa la carpeta en la que se crearon una plantilla predeterminada y los archivos necesarios para el agente.
Primero, el archivo .env. cuyo contenido se muestra a continuación:
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION
Los valores indican que usaremos Gemini a través de Vertex AI junto con los valores correspondientes para el ID y la ubicación del proyecto de Google Cloud.
Luego, tenemos el archivo __init__.py que marca la carpeta como un módulo y tiene una sola sentencia que importa el agente desde el archivo agent.py.
from . import agent
Por último, veamos el archivo agent.py. El contenido se muestra a continuación:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.0-flash-001',
name='root_agent',
description='A helpful assistant for user questions.',
instruction='Answer user questions to the best of your knowledge',
)
Este es el agente más simple que puedes escribir con el ADK. Según la página de documentación del ADK, un agente es una unidad de ejecución independiente diseñada para actuar de forma autónoma y alcanzar objetivos específicos. Los agentes pueden realizar tareas, interactuar con los usuarios, usar herramientas externas y coordinarse con otros agentes.
Específicamente, un LLMAgent, que suele tener el alias de agente, utiliza modelos de lenguaje grandes (LLM) como su motor principal para comprender el lenguaje natural, razonar, planificar, generar respuestas y decidir de forma dinámica cómo proceder o qué herramientas usar, lo que lo hace ideal para tareas flexibles y centradas en el lenguaje. Obtén más información sobre los agentes de LLM aquí.
Modifiquemos el código de agent.py de la siguiente manera:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.0-flash-001',
name='hotel_agent',
description='A helpful assistant that answers questions about a specific city.',
instruction='Answer user questions about a specific city to the best of your knowledge. Do not answer questions outside of this.',
)
Prueba la app del agente de forma local
Desde la ventana de terminal existente, ingresa el siguiente comando. Asegúrate de estar en la carpeta superior (my-agents) que contiene la carpeta hotel-agent-app.
adk web
A continuación, se muestra una ejecución de muestra:
INFO: Started server process [5015]
INFO: Waiting for application startup.
+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at http://localhost:8000. |
+-----------------------------------------------------------------------------+
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
Haz clic en el último vínculo para que se abra una consola web para probar el agente. Deberías ver lo siguiente en el navegador, como se muestra a continuación:
Observa que, en la parte superior izquierda, se identificó hotel-agent-app. Ahora puedes comenzar a conversar con el agente. Proporciona algunas instrucciones para preguntar sobre las ciudades. A continuación, se muestra un ejemplo de conversación:
Puedes cerrar el proceso que se ejecuta en la terminal de Cloud Shell (Ctrl + C).
Una forma alternativa de probar el agente es mediante el comando adk run, como se indica a continuación, desde la carpeta my-agents.
adk run hotel-agent-app
Prueba el comando y podrás conversar con el agente a través de la línea de comandos (terminal). Escribe exit para cerrar la conversación.
7. Cómo conectar nuestro agente a las herramientas
Ahora que sabemos cómo escribir un agente y probarlo de forma local, Conectaremos este agente a Herramientas. En el contexto de ADK, una herramienta representa una capacidad específica que se proporciona a un agente de IA, lo que le permite realizar acciones e interactuar con el mundo más allá de sus capacidades principales de generación de texto y razonamiento.
En nuestro caso, ahora equiparemos a nuestro agente con las herramientas que configuramos en MCP Toolbox para bases de datos.
Modifica el archivo agent.py con el siguiente código:
from google.adk.agents import Agent
from toolbox_core import ToolboxSyncClient
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
# Load single tool
# tools = toolbox.load_tool('search-hotels-by-location')
# Load all the tools
tools = toolbox.load_toolset('my_first_toolset')
root_agent = Agent(
name="hotel_agent",
model="gemini-2.0-flash",
description=(
"Agent to answer questions about hotels in a city or hotels by name."
),
instruction=(
"You are a helpful agent who can answer user questions about the hotels in a specific city or hotels by name. Use the tools to answer the question"
),
tools=tools,
)
Ahora podemos probar el agente que recuperará datos reales de nuestra base de datos de PostgreSQL configurada con MCP Toolbox for Databases.
Para ello, sigue esta secuencia:
En una terminal de Cloud Shell, inicia MCP Toolbox para bases de datos. Es posible que ya lo tengas en ejecución de forma local en el puerto 5000, como lo probamos antes. De lo contrario, ejecuta el siguiente comando (desde la carpeta mcp-toolbox) para iniciar el servidor:
./toolbox --tools_file "tools.yaml"
Idealmente, deberías ver un resultado que indique que el servidor pudo conectarse a nuestras fuentes de datos y que cargó el conjunto de herramientas. A continuación, se muestra un resultado de muestra:
./toolbox --tools-file "tools.yaml"
2025-04-23T14:32:29.564903079Z INFO "Initialized 1 sources."
2025-04-23T14:32:29.565009291Z INFO "Initialized 0 authServices."
2025-04-23T14:32:29.565070176Z INFO "Initialized 2 tools."
2025-04-23T14:32:29.565120847Z INFO "Initialized 2 toolsets."
2025-04-23T14:32:29.565510068Z INFO "Server ready to serve!"
Una vez que el servidor de MCP se haya iniciado correctamente, en otra terminal, inicia el agente como lo hicimos antes con el comando adk run (de la carpeta my-agents) que se muestra a continuación. También puedes usar el comando adk web si lo deseas.
$ adk run hotel-agent-app/
Log setup complete: /tmp/agents_log/agent.20250423_170001.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
Running agent hotel_agent, type exit to exit.
user: what can you do for me?
[hotel_agent]: I can help you find hotels in a specific city or search for hotels by name.
user: I would like to search for hotels
[hotel_agent]: Great, do you have a specific city or hotel name in mind?
user: Yes a specific city
[hotel_agent]: Great, which city are you interested in?
user: Basel
[hotel_agent]: OK. I found three hotels in Basel: Hilton Basel, Hyatt Regency Basel, and Holiday Inn Basel.
Observa que el agente ahora usa las dos herramientas que configuramos en MCP Toolbox para bases de datos (search-hotels-by-name y search-hotels-by-location) y nos proporciona las opciones correctas. Luego, puede recuperar los datos de la base de datos de la instancia de PostgreSQL sin problemas y dar formato a la respuesta según corresponda.
Esto completa el desarrollo y las pruebas locales de nuestro agente de hoteles que compilamos con el kit de desarrollo de agentes (ADK) y que se ejecutó con las herramientas que configuramos en el kit de herramientas de MCP para bases de datos.
8. Implementación (opcional) de MCP Toolbox para bases de datos y agentes en Cloud Run
En la sección anterior, usamos la terminal de Cloud Shell para iniciar el servidor de MCP Toolbox y probar las herramientas con el agente. Se ejecutaba de forma local en el entorno de Cloud Shell.
Tienes la opción de implementar el servidor de MCP Toolbox y el agente en los servicios de Google Cloud que pueden alojar estas aplicaciones por nosotros.
Aloja el servidor de MCP Toolbox en Cloud Run
En primer lugar, podemos comenzar con el servidor de MCP Toolbox y alojarlo en Cloud Run. Esto nos proporcionaría un extremo público que podemos integrar con cualquier otra aplicación o con las aplicaciones del agente. Aquí encontrarás las instrucciones para alojarlo en Cloud Run. Ahora, repasaremos los pasos clave.
Inicia una nueva terminal de Cloud Shell o usa una existente. Ve a la carpeta mcp-toolbox, en la que se encuentran el binario toolbox y tools.yaml.
Ejecuta los siguientes comandos (se proporciona una explicación para cada uno):
Establece la variable PROJECT_ID para que apunte al ID de tu proyecto de Google Cloud.
export PROJECT_ID="YOUR_GOOGLE_CLOUD_PROJECT_ID"
A continuación, verifica que los siguientes servicios de Google Cloud estén habilitados en el proyecto.
gcloud services enable run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
iam.googleapis.com \
secretmanager.googleapis.com
Crear una cuenta de servicio independiente que actuará como la identidad del servicio de Toolbox que implementaremos en Google Cloud Run También nos aseguramos de que esta cuenta de servicio tenga los roles correctos, es decir, la capacidad de acceder a Secret Manager y comunicarse con Cloud SQL.
gcloud iam service-accounts create toolbox-identity
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
--role roles/secretmanager.secretAccessor
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
--role roles/cloudsql.client
Subiremos el archivo tools.yaml como un secreto y, como tenemos que instalar Toolbox en Cloud Run, usaremos la imagen de contenedor más reciente para la caja de herramientas y la configuraremos en la variable IMAGE.
gcloud secrets create tools --data-file=tools.yaml
export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest
El último paso del comando de implementación conocido en Cloud Run:
gcloud run deploy toolbox \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools:latest" \
--args="--tools_file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--allow-unauthenticated
Esto debería iniciar el proceso de implementación del servidor de Toolbox con nuestro tools.yaml configurado en Cloud Run. Si la implementación se realiza correctamente, deberías ver un mensaje similar al siguiente:
Deploying container to Cloud Run service [toolbox] in project [YOUR_PROJECT_ID] region [us-central1]
OK Deploying new service... Done.
OK Creating Revision...
OK Routing traffic...
OK Setting IAM Policy...
Done.
Service [toolbox] revision [toolbox-00001-zsk] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-<SOME_ID>.us-central1.run.app
Ahora puedes visitar el Service URL que se mencionó anteriormente en el navegador. Se debería mostrar el mensaje "Hello World" que vimos antes. Además, puedes visitar la siguiente URL para ver las herramientas disponibles:
SERVICE URL/api/toolset
También puedes visitar Cloud Run desde la consola de Google Cloud y verás el servicio de Toolbox disponible en la lista de servicios de Cloud Run.
Nota: Si deseas seguir ejecutando tu agente de hoteles de forma local y, al mismo tiempo, conectarte al servicio de Cloud Run que se implementó recientemente, solo debes realizar un cambio en el archivo my-agents/hotel-agent-app/agent.py.
En lugar de lo siguiente:
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
Cámbiala a la URL del servicio de Cloud Run como se indica a continuación:
toolbox = ToolboxSyncClient("CLOUD_RUN_SERVICE_URL")
Prueba la aplicación del agente con adk run o adk web, como vimos antes.
Implementa la app de Hotel Agent en Cloud Run
El primer paso es asegurarte de haber realizado el cambio en my-agents/hotel-agent-app/agent.py como se indicó anteriormente para que apunte a la URL del servicio de Toolbox que se ejecuta en Cloud Run y no en el host local.
En una nueva terminal de Cloud Shell o en una sesión de terminal existente, asegúrate de que estás en el entorno virtual de Python correcto que configuramos antes.
Primero, crearemos un archivo requirements.txt en la carpeta my-agents/hotel-agent-app, como se muestra a continuación:
google-adk
toolbox-core
Navega a la carpeta my-agents y, primero, configuremos las siguientes variables de entorno:
export GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_CLOUD_PROJECT_ID
export GOOGLE_CLOUD_LOCATION=us-central1
export AGENT_PATH="hotel-agent-app/"
export SERVICE_NAME="hotels-service"
export APP_NAME="hotels-app"
export GOOGLE_GENAI_USE_VERTEXAI=True
Por último, implementemos la aplicación del agente en Cloud Run con el comando cloud_run adk deploy como se indica a continuación. Si se te solicita que permitas invocaciones no autenticadas al servicio, proporciona "y" como valor por ahora.
adk deploy cloud_run \
--project=$GOOGLE_CLOUD_PROJECT \
--region=$GOOGLE_CLOUD_LOCATION \
--service_name=$SERVICE_NAME \
--app_name=$APP_NAME \
--with_ui \
$AGENT_PATH
Esto iniciará el proceso de implementación de la aplicación de Hotel Agent en Cloud Run. Subirá las fuentes, las empaquetará en un contenedor de Docker, las enviará a Artifact Registry y, luego, implementará el servicio en Cloud Run. Esto puede tardar unos minutos, así que ten paciencia.
Deberías ver un mensaje similar al siguiente:
Start generating Cloud Run source files in /tmp/cloud_run_deploy_src/20250424_045623
Copying agent source code...
Copying agent source code complete.
Creating Dockerfile...
Creating Dockerfile complete: /tmp/cloud_run_deploy_src/20250424_045623/Dockerfile
Deploying to Cloud Run...
Building using Dockerfile and deploying container to Cloud Run service [hotels-service] in project [YOUR_GOOGLE_CLOUD_PROJECT] region [us-central1]
| Building and deploying... Uploading sources.
| Uploading sources...
OK Building and deploying... Done.
OK Uploading sources...
OK Building Container... Logs are available at [https://console.cloud.google.com/cloud-build/builds;region=us-central1/b02f5a74-6da6-4367-aaba-0c8aa098edf5?project=415458962931].
OK Creating Revision...
OK Routing traffic...
Done.
Service [hotels-service] revision [hotels-service-00002-cpm] has been deployed and is serving 100 percent of traffic.
Service URL: https://hotels-service-<SOME_ID>.us-central1.run.app
Cleaning up the temp folder: /tmp/cloud_run_deploy_src/20250424_045623
Si la implementación se realiza correctamente, se te proporcionará un valor para la URL del servicio, al que podrás acceder en el navegador para ver la misma aplicación web que te permitió chatear con el agente del hotel, como vimos antes en la configuración local.
9. Felicitaciones
Felicitaciones, compilaste correctamente un agente con el kit de desarrollo de agentes (ADK) que usa el kit de herramientas de MCP para bases de datos.