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 tendrá la base de datos de hoteles y datos de muestra.
- Configura MCP Toolbox for Databases, que proporciona acceso a los datos.
- Diseña y desarrolla un agente con el Kit de desarrollo de agentes (ADK) que utilizará el kit de herramientas de MCP para responder las preguntas del usuario.
- Explora las opciones para probar Agent y MCP Toolbox for Databases de forma local y en Google Cloud a través del servicio de Cloud Run.
Actividades
- Diseñar, compilar y, luego, implementar un agente que responda las preguntas de los usuarios sobre hoteles en una ubicación o que busque hoteles por nombre
Qué aprenderás
- Aprovisionamiento y propagación de 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ñar y desarrollar un agente con el Kit de desarrollo de agentes (ADK) para responder las preguntas de los usuarios
- Prueba el agente y el kit de herramientas de MCP para bases de datos en el entorno local.
- De manera 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, y la capacidad básica de lectura de código será suficiente 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 autenticaste y que el proyecto se configuró con el ID de tu proyecto 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. Este proceso 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 que se muestra a continuación:
Operation "operations/..." finished successfully.
La alternativa al comando de gcloud es a través de la consola, buscando cada producto o usando este vínculo.
Si olvidas 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, administrar y controlar tus 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 \
--tier db-g1-small \
--region=us-central1 \
--edition=ENTERPRISE \
--root-password=postgres
Este comando tarda entre 3 y 5 minutos en ejecutarse. Una vez que el comando se ejecute correctamente, deberías ver un resultado que indique que el comando finalizó, 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
Ahora, nuestra tarea 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 que hoteldb-instance está 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 te daremos algunos comandos SQL. Selecciona postgres para la opción Database y, para User y Password, el valor que se debe usar es postgres. Haz clic en AUTHENTICATE.
Primero, creemos la tabla de hoteles según el siguiente esquema. En uno de los paneles del editor de Cloud SQL Studio, ejecuta el siguiente código 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 de hoteles con datos de muestra. Ejecuta el siguiente SQL:
INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked)
VALUES
(1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-20', '2024-04-22', 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-05', '2024-04-24', B'0'),
(5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-01', '2024-04-23', B'0'),
(6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'),
(7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-02', '2024-04-27', B'0'),
(8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-09', '2024-04-24', 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, ejecuta un SQL de SELECT como se muestra a continuación:
SELECT * FROM hotels;
Deberías ver varios registros en la tabla de 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 for Databases
MCP Toolbox for Databases es un servidor de MCP de código abierto para bases de datos. Se diseñó teniendo en cuenta la calidad de producción y el nivel empresarial. Te permite desarrollar herramientas de forma más fácil, rápida y segura, ya que se encarga de las complejidades, como la agrupación de conexiones, la autenticación y mucho más.
La caja de herramientas te ayuda a crear herramientas de IA generativa que permiten que tus agentes accedan a los datos de tu base de datos. Toolbox proporciona lo siguiente:
- Desarrollo simplificado: Integra herramientas a tu agente con menos de 10 líneas de código, reutiliza herramientas entre varios agentes o frameworks y, luego, 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 registros 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 necesidad de volver a implementar tu aplicación.
Puedes ver que una de las bases de datos compatibles con MCP Toolbox for Databases es Cloud SQL, que 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 for Databases con la secuencia de comandos que se indica a continuación. El siguiente comando es para Linux, pero, si usas Mac o Windows, asegúrate de descargar el objeto binario correcto. Consulta la página de versiones para tu sistema operativo y arquitectura y descarga el objeto binario correcto.
export VERSION=0.13.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 otras configuraciones.
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 de 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. Result is sorted by price from least to most expensive.
parameters:
- name: location
type: string
description: The location of the hotel.
statement: |
SELECT *
FROM hotels
WHERE location ILIKE '%' || $1 || '%'
ORDER BY
CASE price_tier
WHEN 'Midscale' THEN 1
WHEN 'Upper Midscale' THEN 2
WHEN 'Upscale' THEN 3
WHEN 'Upper Upscale' THEN 4
WHEN 'Luxury' THEN 5
ELSE 99 -- Handle any unexpected values, place them at the end
END;
toolsets:
my_first_toolset:
- search-hotels-by-name
- search-hotels-by-location
A continuación, se describe el archivo de forma breve:
Sourcesrepresentan las diferentes fuentes de datos con las que puede interactuar una herramienta. Un objeto Source 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, la configuración de una fuente contendrá toda la información necesaria para conectarse con la base de datos y para 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 de Fuentes.Toolsdefinen 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 SQL. Puedes definirToolscomo un mapa en la sección de herramientas de tu archivo tools.yaml. Por lo general, una herramienta requerirá una fuente para actuar. En nuestro caso, definimos dos herramientas:search-hotels-by-nameysearch-hotels-by-location, y especificamos la fuente sobre 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 juntas. Esto puede ser útil para definir diferentes grupos según el agente o la aplicación. En nuestro caso, tenemos un solo conjunto de herramientas llamadomy_first_toolset, que contiene las dos herramientas que definimos.
Sigue estos pasos para guardar el archivo tools.yaml en el editor nano:
- Presiona
Ctrl + O(el comando "Escribir"). - Se te pedirá que confirmes el "Nombre de archivo para escribir". Solo presiona
Enter. - Ahora, presiona
Ctrl + Xpara salir.
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"
Lo ideal sería que vieras un resultado que indique que el servidor pudo conectarse a nuestras fuentes de datos y cargó el conjunto de herramientas y las herramientas. A continuación, se muestra un ejemplo de resultado:
2025-09-05T12:56:28.490964335Z INFO "Initialized 1 sources."
2025-09-05T12:56:28.491127294Z INFO "Initialized 0 authServices."
2025-09-05T12:56:28.491184521Z INFO "Initialized 2 tools."
2025-09-05T12:56:28.491223782Z INFO "Initialized 2 toolsets."
2025-09-05T12:56:28.497457533Z INFO "Server ready to serve!"
El servidor de MCP Toolbox se ejecuta de forma predeterminada en el puerto 5000. Si ves que el puerto 5000 ya está en uso, puedes usar otro puerto (por ejemplo, 7000) según el comando que se muestra a continuación. En su lugar, usa 7000 en lugar del puerto 5000 en los comandos posteriores.
./toolbox --tools-file "tools.yaml" --port 7000
Usemos Cloud Shell para probarlo.
Haz clic en Vista previa en la Web en Cloud Shell, como se muestra a continuación:
Haz clic en Cambiar puerto, establece el puerto en 5000 como se muestra a continuación y haz clic en Cambiar y obtener vista previa.
Esto debería generar el siguiente resultado:
En la URL del navegador, agrega lo siguiente al final:
/api/toolset
Esto debería mostrar las herramientas configuradas actualmente. A continuación, se muestra un ejemplo del resultado:
{
"serverVersion": "0.13.0+binary.linux.amd64.1a6dfe8d37d0f42fb3fd3f75c50988534dbc1b85",
"tools": {
"search-hotels-by-location": {
"description": "Search for hotels based on location. Result is sorted by price from least to most expensive.",
"parameters": [
{
"name": "location",
"type": "string",
"required": true,
"description": "The location of the hotel.",
"authSources": []
}
],
"authRequired": []
},
"search-hotels-by-name": {
"description": "Search for hotels based on name.",
"parameters": [
{
"name": "name",
"type": "string",
"required": true,
"description": "The name of the hotel.",
"authSources": []
}
],
"authRequired": []
}
}
}
Cómo probar las herramientas a través de la IU de MCP Toolbox for Databases
Toolbox proporciona una interfaz visual (IU de Toolbox) para interactuar directamente con las herramientas modificando parámetros, administrando encabezados y ejecutando llamadas, todo dentro de una IU web simple.
Si quieres probarlo, puedes ejecutar el comando anterior que usamos para iniciar el servidor de Toolbox con una opción --ui.
Para ello, cierra la instancia anterior del servidor de MCP Toolbox for Databases que se esté ejecutando y ejecuta el siguiente comando:
./toolbox --tools-file "tools.yaml" --ui
Lo ideal sería que vieras un resultado que indique que el servidor pudo conectarse a nuestras fuentes de datos y cargó el conjunto de herramientas y las herramientas. A continuación, se muestra un ejemplo del resultado. Notarás que se menciona que la IU de Toolbox está en funcionamiento.
2025-09-08T02:44:11.561572538Z INFO "Initialized 1 sources."
2025-09-08T02:44:11.561966395Z INFO "Initialized 0 authServices."
2025-09-08T02:44:11.562060934Z INFO "Initialized 2 tools."
2025-09-08T02:44:11.562105678Z INFO "Initialized 2 toolsets."
2025-09-08T02:44:11.568209923Z INFO "Server ready to serve!"
2025-09-08T02:44:11.568259411Z INFO "Toolbox UI is up and running at: http://localhost:5000/ui"
Haz clic en la URL de la IU y asegúrate de tener /ui al final de la URL. Se mostrará una IU como la que se muestra a continuación:
Haz clic en la opción Herramientas a la izquierda para ver las herramientas que se configuraron. En nuestro caso, deberían ser dos, es decir, search-hotels-by-name y search-hotels-by-location, como se muestra a continuación:
Solo tienes que hacer clic en una de las herramientas (search-hotels-by-location) para que se abra una página en la que puedas probarla. Para ello, proporciona los valores de los parámetros obligatorios y, luego, haz clic en Ejecutar herramienta para ver el resultado. A continuación, se muestra un ejemplo de ejecución:
El MCP Toolkit for Databases también describe una forma pythonica para que valides y pruebes las herramientas, que se documenta aquí.
Si volvemos al diagrama anterior (como se muestra a continuación), ya completamos la configuración de la base de datos y el servidor de MCP, y tenemos dos rutas frente a nosotros:
- Para comprender cómo puedes configurar el servidor de MCP en un IDE o terminal asistido por IA, ve al paso 6. En este artículo, se explica cómo integramos nuestro servidor de MCP Toolbox en la CLI de Gemini.
- Para comprender cómo usar el Kit de desarrollo de agentes (ADK) con Python, escribir tus propios agentes que puedan utilizar el kit de herramientas del servidor de MCP como herramienta y responder preguntas relacionadas con el conjunto de datos, consulta los pasos 7 y 8.
6. Integración de MCP Toolbox en la CLI de Gemini
La CLI de Gemini es un agente de IA de código abierto que lleva el poder de Gemini directamente a tu terminal. Puedes usarlo para tareas de programación y no programación. Se integra con varias herramientas y es compatible con los servidores de MCP.
Dado que tenemos un servidor de MCP en funcionamiento, nuestro objetivo en esta sección será configurar el servidor de MCP Toolbox for Databases en la CLI de Gemini y, luego, usar la CLI de Gemini para comunicarnos con nuestros datos.
El primer paso será confirmar si la caja de herramientas está en funcionamiento en una de las terminales de Cloud Shell. Suponiendo que lo ejecutas en el puerto predeterminado 5000, la interfaz del servidor de MCP está disponible en el siguiente extremo: http://localhost:5000/mcp.
Abre una terminal nueva y crea una carpeta llamada my-gemini-cli-project de la siguiente manera. Navega también a la carpeta my-gemini-cli-project.
mkdir my-gemini-cli-project
cd my-gemini-cli-project
Ejecuta el siguiente comando para agregar el servidor de MCP a la lista de servidores de MCP configurados en la CLI de Gemini.
gemini mcp add --scope="project" --transport="http" "MCPToolbox" "http://localhost:5000/mcp"
Puedes verificar la lista actual de servidores de MCP configurados en la CLI de Gemini con el siguiente comando:
gemini mcp list
Lo ideal sería que vieras el MCPToolbox que configuramos con una marca de verificación verde junto a él, lo que indica que la CLI de Gemini pudo conectarse al servidor de MCP.
Configured MCP servers:
✓ MCPToolbox: http://localhost:5000/mcp (http) - Connected
Desde la misma terminal, asegúrate de estar en la carpeta my-gemini-cli-project. Ejecuta Gemini CLI con el comando gemini.
Aparecerá la interfaz de la CLI de Gemini y verás que ahora tiene 1 servidor de MCP configurado. Puedes usar el comando /mcp list para ver la lista de servidores de MCP y las herramientas. Por ejemplo, aquí se muestra un resultado de muestra:
Ahora puedes dar cualquiera de las siguientes instrucciones:
- ¿Qué hoteles hay en Basilea?
- ¿Me puedes contar más sobre el Hyatt Regency?
Verás que las consultas anteriores harán que la CLI de Gemini seleccione la herramienta adecuada de MCPToolbox. Se te pedirá permiso para ejecutar la herramienta. Otorga el permiso necesario y verás que los resultados se devuelven desde la base de datos.
7. Cómo escribir nuestro agente con el Kit de desarrollo de agentes (ADK)
Instala el Kit de desarrollo de agentes (ADK)
Abre una pestaña de terminal nueva 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 del ADK y de MCP Toolbox for Databases junto con la dependencia de LangChain 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:
--version Show the version and exit.
--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.
Cómo crear nuestra primera aplicación de agente
Ahora, usaremos adk para crear un andamiaje para nuestra aplicación de agente de hoteles a través del comando adk create con el nombre de la 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 de tu proyecto de Google. Selecciona el valor predeterminado.
Choose a model for the root agent:
1. gemini-2.5-flash
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 [YOUR_PROJECT_ID]:
Enter Google Cloud region [us-central1]:
Agent created in <YOUR_HOME_FOLDER>/my-agents/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.
El primer archivo es .env. El 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 respectivos del 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 instrucción que importa el agente del 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.5-flash',
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. En la página de documentación del ADK, se define un agente como una unidad de ejecución autónoma diseñada para actuar de forma independiente y alcanzar objetivos específicos. Los agentes pueden realizar tareas, interactuar con los usuarios, utilizar herramientas externas y coordinarse con otros agentes.
Específicamente, un LLMAgent, comúnmente conocido como Agent, 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 los hace ideales para tareas flexibles y centradas en el lenguaje. Obtén más información sobre los agentes basados en 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.5-flash',
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 principal (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 [1478]
INFO: Waiting for application startup.
+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at http://127.0.0.1:8000. |
+-----------------------------------------------------------------------------+
INFO: Application startup complete.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
Haz clic en el último vínculo, y debería aparecer 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 esquina superior izquierda, se identificó el hotel-agent-app. Ahora puedes comenzar a conversar con el agente. Proporciona algunas instrucciones que consulten sobre ciudades. A continuación, se muestra un ejemplo de conversación:
Puedes detener el proceso que se ejecuta en la terminal de Cloud Shell (Ctrl + C).
Otra forma de probar el agente es con el comando adk run que 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.
8. 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 las herramientas. En el contexto del 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, equiparemos nuestro agente con las herramientas que configuramos en el MCP Toolbox for Databases.
Modifica el archivo agent.py con el siguiente código. Ten en cuenta que usamos el puerto predeterminado 5000 en el código, pero, si usas un número de puerto alternativo, usa ese.
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.5-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, que se configuró con MCP Toolbox for Databases.
Para ello, sigue esta secuencia:
En una terminal de Cloud Shell, inicia MCP Toolbox for Databases. Es posible que ya se esté ejecutando de forma local en el puerto 5000, como probamos antes. De lo contrario, ejecuta el siguiente comando (desde la carpeta mcp-toolbox) para iniciar el servidor:
./toolbox --tools_file "tools.yaml"
Lo ideal sería que vieras un resultado que indique que el servidor pudo conectarse a nuestras fuentes de datos y cargó el conjunto de herramientas y las herramientas. A continuación, se muestra un ejemplo de resultado:
2025-09-05T12:56:28.490964335Z INFO "Initialized 1 sources."
2025-09-05T12:56:28.491127294Z INFO "Initialized 0 authServices."
2025-09-05T12:56:28.491184521Z INFO "Initialized 2 tools."
2025-09-05T12:56:28.491223782Z INFO "Initialized 2 toolsets."
2025-09-05T12:56:28.497457533Z 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 utiliza las dos herramientas que configuramos en MCP Toolbox for Databases (search-hotels-by-name y search-hotels-by-location) y nos proporciona las opciones correctas. Luego, puede recuperar sin problemas los datos de la base de datos de la instancia de PostgreSQL y dar formato a la respuesta según corresponda.
Con esto, se 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.
9. (Opcional) Implementa MCP Toolbox for Databases and Agent en Cloud Run
En la sección anterior, usamos la terminal de Cloud Shell para iniciar el servidor de MCP Toolbox y probamos las herramientas con el agente. Esto 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.
Cómo alojar el servidor de MCP Toolbox en Cloud Run
Primero, podemos comenzar con el servidor de MCP Toolbox y alojarlo en Cloud Run. Esto nos proporcionaría un extremo público que podríamos integrar con cualquier otra aplicación o con las aplicaciones del agente. Las instrucciones para alojar esto en Cloud Run se proporcionan aquí. Ahora veremos 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 archivo 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 a tu ID del 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
Creemos 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 secreto y, como tenemos que instalar Toolbox en Cloud Run, usaremos la imagen de contenedor más reciente para Toolbox y la estableceremos 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. Debería mostrar el mensaje "Hello World" que vimos antes. Además, también 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, a la vez, conectarte al servicio de Cloud Run recién implementado, 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 estar en el entorno virtual de Python correcto que configuramos anteriormente.
Primero, creemos 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, establece 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 adk deploy cloud_run, como se indica a continuación. Si se te solicita que permitas invocaciones no autenticadas al servicio, proporciona "y" como valor por el momento.
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 del agente de hoteles en Cloud Run. Subirá las fuentes, las empaquetará en un contenedor de Docker, lo enviará a Artifact Registry y, luego, implementará el servicio en Cloud Run. Este proceso 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/20250905_132636
Copying agent source code...
Copying agent source code completed.
Creating Dockerfile...
Creating Dockerfile complete: /tmp/cloud_run_deploy_src/20250905_132636/Dockerfile
Deploying to Cloud Run...
Building using Dockerfile and deploying container to Cloud Run service [hotels-service] in project [YOUR_PROJECT_ID] region [us-central1]
- Building and deploying... Uploading sources.
- Uploading sources...
. Building Container...
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/d1f7e76b-0587-4bb6-b9c0-bb4360c07aa0?project=415
458962931]. f
OK Creating Revision...
OK Routing traffic...
Done.
Service [hotels-service] revision [hotels-service-00003-hrl] has been deployed and is serving 100 percent of traffic.
Service URL: <YOUR_CLOUDRUN_APP_URL>
INFO: Display format: "none"
Cleaning up the temp folder: /tmp/cloud_run_deploy_src/20250905_132636
Cuando la implementación se realice correctamente, se te proporcionará un valor para la URL del servicio, a la que podrás acceder en el navegador para ver la misma aplicación web que te permitió chatear con el agente de hoteles, como vimos anteriormente en la configuración local.
10. Limpieza
Para evitar que se apliquen cargos a tu cuenta de Google Cloud, es importante que borres los recursos que creamos durante este taller. Borraremos la instancia de Cloud SQL y, de manera opcional, si implementaste Toolbox y la app de Hoteles en Cloud Run, también borraremos esos servicios.
Asegúrate de que las siguientes variables de entorno estén configuradas correctamente según tu proyecto y región:
export PROJECT_ID="YOUR_PROJECT_ID"
export REGION="YOUR_REGION"
Los siguientes dos comandos borran los servicios de Cloud Run que implementamos:
gcloud run services delete toolbox --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet
gcloud run services delete hotels-service --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet
El siguiente comando borra la instancia de Cloud SQL:
gcloud sql instances delete hoteldb-instance
11. Felicitaciones
Felicitaciones, compilaste correctamente un agente con el Kit de desarrollo de agentes (ADK) que utiliza el kit de herramientas de MCP para bases de datos.