Base de datos como herramienta: RAG agente con ADK, MCP Toolbox y Cloud SQL

1. Introducción

Los agentes de IA solo son tan útiles como los datos a los que pueden acceder. La mayoría de los datos del mundo real se encuentran en bases de datos, y conectar agentes a bases de datos suele significar escribir la administración de conexiones, la lógica de consultas y las canalizaciones de incorporación dentro del código del agente. Cada agente que necesita acceso a la base de datos repite este trabajo, y cada cambio en la consulta requiere que se vuelva a implementar el agente.

En este codelab, se muestra un enfoque diferente. Declaras tus herramientas de base de datos en un archivo YAML (consultas de SQL estándar, búsqueda de similitud de vectores y hasta generación automática de embeddings), y MCP Toolbox for Databases controla todas las operaciones de la base de datos como un servidor de MCP. El código del agente sigue siendo mínimo: carga las herramientas y deja que Gemini decida a cuál llamar.

Qué compilarás

Un asistente inteligente de bolsa de trabajo para "TechJobs", un agente del ADK potenciado por Gemini que ayuda a los desarrolladores a explorar las ofertas de empleo en tecnología con filtros estándar (rol, pila de tecnología) y a descubrir trabajos a través de descripciones en lenguaje natural, como "Quiero un trabajo remoto en chatbots de IA". El agente lee y escribe en una base de datos de Cloud SQL PostgreSQL por completo a través de MCP Toolbox for Databases, que controla todo el acceso a la base de datos, incluida la generación automática de incorporaciones para la búsqueda de vectores. Al final, tanto la caja de herramientas como el agente se ejecutarán en Cloud Run.

Qué aprenderás

• Cómo el MCP (Protocolo de contexto del modelo) estandariza el acceso a las herramientas para los agentes de IA y cómo MCP Toolbox para bases de datos aplica esto a las operaciones de bases de datos
• Configura MCP Toolbox for Databases como middleware entre un agente de ADK y Cloud SQL PostgreSQL
• Define herramientas de bases de datos de forma declarativa en tools.yaml: no hay código de base de datos en tu agente
• Compila un agente del ADK que cargue herramientas desde un servidor de Toolbox en ejecución con ToolboxToolset
• Genera embeddings de vectores con la función embedding() integrada de Cloud SQL y habilita la búsqueda semántica con pgvector
• Usa la función valueFromParam para la incorporación automática de vectores en las operaciones de escritura
• Implementa el servidor de Toolbox y el agente del ADK en Cloud Run

Requisitos previos

• Una cuenta de Google Cloud con una cuenta de facturación de prueba
• Conocimientos básicos de Python y SQL
• No se requiere experiencia previa con el ADK, MCP Toolbox ni pgvector.

2. Configura tu entorno

NOTAS IMPORTANTES:

En este instructivo, se requiere un proyecto de Google Cloud con una cuenta de facturación activa. Si aún no tienes una, sigue los pasos que se indican a continuación para obtener una cuenta de facturación de prueba que se pueda usar para este instructivo:

1. Abrir ventana de incógnito
2. Si te unes a una sesión de taller, la URL del portal de canje suele proporcionarse en la sesión. De lo contrario, puedes navegar a este portal de canje de la cuenta de facturación de prueba.
3. Accede con tu cuenta personal de Gmail ( no funcionarán las cuentas de Google Workspace ni otros correos electrónicos). ).
4. Sigue las instrucciones de canje paso a paso para crear un proyecto nuevo de Google Cloud que esté vinculado a la cuenta de facturación de prueba reclamada anteriormente para este instructivo.

En este paso, se prepara tu entorno de Cloud Shell, se configura tu proyecto de Google Cloud y se clona el repositorio de referencia.

Abra Cloud Shell

Abre Cloud Shell en tu navegador. Cloud Shell proporciona un entorno preconfigurado con todas las herramientas que necesitas para este codelab. Haz clic en Autorizar cuando se te solicite

Abrir Cloud Shell

Luego, haz clic en "Ver" -> "Terminal" para abrir la terminal.Tu interfaz debería verse similar a esta:

Esta será nuestra interfaz principal, con el IDE en la parte superior y la terminal en la parte inferior.

Configura tu directorio de trabajo

Crea tu directorio de trabajo. Todo el código que escribas en este codelab se encontrará aquí:

mkdir -p ~/build-agent-adk-toolbox-cloudsql
cloudshell workspace ~/build-agent-adk-toolbox-cloudsql && cd ~/build-agent-adk-toolbox-cloudsql

Configura el proyecto de Google Cloud

Crea el archivo .env con las variables de ubicación:

# For Vertex AI / Gemini API calls
echo "GOOGLE_CLOUD_LOCATION=global" > .env
# For Cloud SQL, Cloud Run, Artifact Registry
echo "REGION=us-central1" >> .env

Descarga la secuencia de comandos de configuración del proyecto en tu directorio de trabajo:

curl -sL https://raw.githubusercontent.com/alphinside/cloud-trial-project-setup/main/setup_verify_trial_project.sh -o setup_verify_trial_project.sh

Ejecuta la secuencia de comandos. Verifica tu cuenta de facturación de prueba, crea un proyecto nuevo (o valida uno existente), guarda el ID del proyecto en un archivo .env en el directorio actual y establece el proyecto activo en gcloud.

bash setup_verify_trial_project.sh && source .env

La secuencia de comandos hará lo siguiente:

1. Verifica que tengas una cuenta de facturación de prueba activa
2. Verifica si existe un proyecto en .env (si corresponde)
3. Crea un proyecto nuevo o reutiliza el existente
4. Vincula la cuenta de facturación de prueba a tu proyecto
5. Guarda el ID del proyecto en .env.
6. Configura el proyecto como el proyecto gcloud activo

IMPORTANTE: Si ya tienes un proyecto configurado en .env, la secuencia de comandos validará que esté vinculado a una cuenta de facturación de prueba. Si todo está bien, se omite la creación del proyecto.

Verifica que el proyecto esté configurado correctamente. Para ello, consulta el texto amarillo junto a tu directorio de trabajo en el mensaje de la terminal de Cloud Shell. Debería mostrar el ID de tu proyecto.

NOTA: Si tu sesión de Cloud Shell se restablece en algún momento durante este codelab, vuelve a tu directorio de trabajo y vuelve a ejecutar bash setup_verify_trial_project.sh && source .env para restablecer la configuración de tu proyecto. Confirma que el texto amarillo del ID del proyecto vuelva a aparecer en el mensaje de la terminal.

Si tu sesión de Cloud Shell se restablece en algún momento durante este codelab, vuelve a tu directorio de trabajo y vuelve a ejecutar bash setup_verify_trial_project.sh && source .env para restablecer la configuración de tu proyecto. Confirma que el texto amarillo del ID del proyecto vuelva a aparecer en el mensaje de la terminal.

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

• API de Vertex AI (aiplatform.googleapis.com): Tu agente usa modelos de Gemini, y Toolbox usa la API de Embedding para la búsqueda vectorial.
• API de Cloud SQL Admin (sqladmin.googleapis.com): Aprovisionas y administras una instancia de PostgreSQL.
• API de Compute Engine (compute.googleapis.com): Se requiere para crear instancias de Cloud SQL.
• Cloud Run, Cloud Build y Artifact Registry: Se usan en el paso de implementación más adelante en este codelab.

Nota: Habilitar las APIs puede tardar un momento. Solo debes hacerlo una vez por proyecto.

3. Crea la instancia de base de datos

En este paso, se configura la creación de la instancia de Cloud SQL en segundo plano, y se aprovisiona mientras continúas con el instructivo.

Inicia la creación de la instancia

Agrega la contraseña de la base de datos a tu archivo .env y vuelve a cargarlo:

echo "DB_PASSWORD=techjobs-pwd-2025" >> .env
source .env

IMPORTANTE: La contraseña codificada anterior es solo para fines del instructivo. En un entorno de producción, almacena las credenciales de forma segura con un servicio como Secret Manager y haz referencia a ellas en el tiempo de ejecución. Nunca confirmes secretos de texto sin formato en el control de código fuente.

Inicia la creación de la instancia de Cloud SQL. Este proceso se ejecuta en segundo plano para que puedas seguir trabajando:

gcloud sql instances create jobs-instance \
  --database-version=POSTGRES_17 \
  --tier=db-custom-1-3840 \
  --edition=ENTERPRISE \
  --region=$REGION \
  --root-password=$DB_PASSWORD \
  --enable-google-ml-integration \
  --database-flags cloudsql.enable_google_ml_integration=on \
  --quiet &

• db-custom-1-3840 es el nivel de Cloud SQL de núcleos dedicados más pequeño (1 CPU virtual, 3.75 GB de RAM) en la edición ENTERPRISE. Puedes obtener más información aquí. Se requiere un núcleo dedicado para la integración de AA de Vertex AI. Los niveles de núcleos compartidos (db-f1-micro, db-g1-small) no son compatibles con esta integración.
• --root-password establece la contraseña para el usuario postgres predeterminado.
• --enable-google-ml-integration habilita la integración integrada de Cloud SQL con Vertex AI, lo que te permite llamar a modelos de embedding directamente desde SQL con la función embedding().
• El comando & se ejecuta en segundo plano.

Se ejecutará en segundo plano. A continuación, descargaremos el objeto binario de MCP Toolbox. Puedes hacerlo en la misma terminal.

Descarga el objeto binario de Toolbox

En este instructivo, utilizaremos MCP Toolbox, que, afortunadamente, incluye un objeto binario compilado previamente que está listo para usarse en el entorno de Linux. Descarguémoslo en segundo plano, ya que tardará bastante.

cd ~/build-agent-adk-toolbox-cloudsql
curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/linux/amd64/toolbox &

Permite que este proceso se ejecute en la pestaña actual (ya lo ejecutamos en segundo plano, pero el resultado se seguirá mostrando). Abramos una pestaña de terminal nueva en Cloud Shell (haz clic en el ícono +) para que podamos concentrarnos más.

Vuelve a tu directorio de trabajo y activa el proyecto con la secuencia de comandos de configuración anterior.

cd ~/build-agent-adk-toolbox-cloudsql
bash setup_verify_trial_project.sh && source .env

En este paso, se configura el proyecto de Python, se instalan las dependencias y se crea el directorio del agente del ADK.

4. Inicializa el proyecto del agente

Configura el proyecto de Python

uv es un administrador de paquetes y proyectos de Python rápido escrito en Rust ( documentación de uv). Este codelab lo usa por su velocidad y simplicidad.

Inicializa un proyecto de Python y agrega las dependencias necesarias:

uv init
uv add google-adk==1.25.0 toolbox-adk==0.6.0

• google-adk: Kit de desarrollo de agentes de Google, incluido el SDK de Gemini
• toolbox-adk: Integración del ADK para MCP Toolbox para bases de datos.

Crea la estructura de directorios del agente

El ADK espera un diseño de carpeta específico: un directorio con el nombre de tu agente que contenga __init__.py, agent.py y .env. Para ayudarte con esto, tiene un comando integrado para establecer rápidamente la estructura:

uv run adk create jobs_agent \
    --model gemini-2.5-flash \
    --project ${GOOGLE_CLOUD_PROJECT} \
    --region ${GOOGLE_CLOUD_LOCATION}

Ahora, tu directorio debería verse así:

build-agent-adk-toolbox-cloudsql/
├── jobs_agent/
│   ├── __init__.py
│   ├── agent.py
│   └── .env
├── pyproject.toml
├── .env              (project setup — already exists)
└── .venv/

5. Propaga la base de datos de fichas de empleos

En este paso, se escriben los datos de inicialización, se espera a que finalice el aprovisionamiento de la instancia de Cloud SQL y se carga la tabla jobs con 15 ofertas de empleo y su incorporación de descripción.

Escribe el código SQL de inicialización

Crearemos un archivo llamado seed.sql en el editor de Cloud Shell con el contenido de la lista de trabajos. Esto crea la tabla jobs con compatibilidad con pgvector y, luego, inserta 15 listas de trabajo en empresas de tecnología.

Nota importante: Estas ofertas de empleo son completamente ficticias y se crearon solo con fines didácticos. Los nombres de las empresas se usan para brindar contexto ilustrativo. Los cargos, los salarios y las descripciones no reflejan vacantes reales.

Primero, crea el archivo seed.sql con el siguiente comando:

cloudshell edit seed.sql

Luego, copia estas secuencias de comandos en el archivo.

-- seed.sql
-- DISCLAIMER: These job listings are entirely fictional and created for tutorial
-- purposes only. Company names are used for illustrative context — the positions,
-- salaries, and descriptions do not reflect real openings.

CREATE EXTENSION IF NOT EXISTS google_ml_integration;
CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE IF NOT EXISTS jobs (
    id SERIAL PRIMARY KEY,
    title VARCHAR NOT NULL,
    company VARCHAR NOT NULL,
    role VARCHAR NOT NULL,
    tech_stack VARCHAR NOT NULL,
    salary_range VARCHAR NOT NULL,
    location VARCHAR NOT NULL,
    openings INTEGER NOT NULL,
    description TEXT NOT NULL,
    description_embedding vector(3072)
);

INSERT INTO jobs (title, company, role, tech_stack, salary_range, location, openings, description) VALUES
('Senior Backend Engineer', 'Stripe', 'Backend', 'Go, PostgreSQL, gRPC, Kubernetes', '$180-250K/year', 'San Francisco, Hybrid', 3,
 'Design and build high-throughput microservices powering payment infrastructure for millions of businesses. Optimize Go services for sub-100ms latency at scale, work with PostgreSQL and Redis for data persistence, and deploy on Kubernetes clusters handling billions of API calls.'),

('Machine Learning Engineer', 'Spotify', 'Data/AI', 'Python, TensorFlow, BigQuery, Vertex AI', '$170-230K/year', 'Stockholm, Remote', 2,
 'Build and deploy ML models for music recommendation and personalization systems serving hundreds of millions of listeners. Design feature pipelines in BigQuery, train models using distributed computing, and serve predictions through real-time APIs processing thousands of requests per second.'),

('Frontend Engineer', 'Vercel', 'Frontend', 'React, TypeScript, Next.js', '$140-190K/year', 'Remote', 4,
 'Build developer-facing dashboard interfaces and deployment tools used by millions of developers worldwide. Create responsive, accessible React components for project management, analytics, and real-time deployment monitoring with a focus on developer experience.'),

('DevOps Engineer', 'Datadog', 'DevOps', 'Terraform, GCP, Docker, Kubernetes, ArgoCD', '$160-220K/year', 'New York, Hybrid', 2,
 'Manage cloud infrastructure powering an observability platform used by thousands of engineering teams. Automate deployment pipelines with ArgoCD, manage multi-cloud Kubernetes clusters, and implement infrastructure-as-code with Terraform across production environments.'),

('Mobile Engineer (Android)', 'Grab', 'Mobile', 'Kotlin, Jetpack Compose, GraphQL', '$120-170K/year', 'Singapore, Hybrid', 3,
 'Develop features for a super-app serving millions of users across Southeast Asia. Build modern Android UIs with Jetpack Compose, integrate GraphQL APIs, and optimize app performance for diverse device capabilities and network conditions.'),

('Data Engineer', 'Airbnb', 'Data', 'Python, Apache Spark, Airflow, BigQuery', '$160-210K/year', 'San Francisco, Hybrid', 2,
 'Build data pipelines that process booking, search, and pricing data for a global travel marketplace. Design ETL workflows with Apache Spark and Airflow, maintain data warehouses in BigQuery, and ensure data quality for analytics and machine learning teams.'),

('Full Stack Engineer', 'Revolut', 'Full Stack', 'TypeScript, Node.js, React, PostgreSQL', '$130-180K/year', 'London, Remote', 5,
 'Build the next generation of financial products making banking accessible to millions of users across 35 countries. Develop real-time trading interfaces with React and WebSockets, build Node.js APIs handling market data streams, and design PostgreSQL schemas for financial transactions.'),

('Site Reliability Engineer', 'Cloudflare', 'SRE', 'Go, Prometheus, Grafana, GCP, Terraform', '$170-230K/year', 'Austin, Hybrid', 2,
 'Ensure 99.99% uptime for a global network handling millions of requests per second. Define SLOs, build monitoring dashboards with Prometheus and Grafana, manage incident response, and automate infrastructure scaling across 300+ data centers worldwide.'),

('Cloud Architect', 'Google Cloud', 'Cloud', 'GCP, Terraform, Kubernetes, Python', '$200-280K/year', 'Seattle, Hybrid', 1,
 'Help enterprises modernize their infrastructure on Google Cloud. Design multi-region architectures, lead migration projects from on-premises to GKE, and build reference implementations using Terraform and Cloud Foundation Toolkit.'),

('Backend Engineer (Payments)', 'Square', 'Backend', 'Java, Spring Boot, PostgreSQL, Kafka', '$160-220K/year', 'San Francisco, Hybrid', 3,
 'Build payment processing systems handling millions of transactions for businesses of all sizes. Design event-driven architectures using Kafka, implement idempotent payment flows with Spring Boot, and ensure PCI-DSS compliance across all services.'),

('AI Engineer', 'Hugging Face', 'Data/AI', 'Python, LangChain, Vertex AI, FastAPI, PostgreSQL', '$150-210K/year', 'Paris, Remote', 2,
 'Build AI-powered tools for the largest open-source ML community. Develop RAG pipelines that index and search model documentation, create conversational agents using LangChain, and deploy AI services with FastAPI on cloud infrastructure.'),

('Platform Engineer', 'Coinbase', 'Platform', 'Rust, Kubernetes, AWS, Terraform', '$180-250K/year', 'Remote', 0,
 'Build the infrastructure platform for a leading cryptocurrency exchange. Develop high-performance matching engines in Rust, manage Kubernetes clusters for microservices, and design CI/CD pipelines that enable rapid feature deployment with zero downtime.'),

('QA Automation Engineer', 'Shopify', 'QA', 'Python, Selenium, Cypress, Jenkins', '$110-160K/year', 'Toronto, Hybrid', 3,
 'Design and maintain automated test suites for a commerce platform powering millions of merchants. Build end-to-end test frameworks with Cypress and Selenium, integrate tests into Jenkins CI pipelines, and establish quality gates that prevent regressions in checkout and payment flows.'),

('Security Engineer', 'CrowdStrike', 'Security', 'Python, SIEM, Kubernetes, Penetration Testing', '$170-240K/year', 'Austin, On-site', 1,
 'Protect enterprise customers from cyber threats on a leading endpoint security platform. Conduct penetration testing, design security monitoring with SIEM tools, implement zero-trust networking in Kubernetes environments, and lead incident response for security events.'),

('Product Engineer', 'GitLab', 'Full Stack', 'Go, React, PostgreSQL, Redis, GCP', '$140-200K/year', 'Remote', 4,
 'Own features end-to-end for an all-in-one DevSecOps platform used by millions of developers. Build Go microservices for CI/CD pipelines, create React frontends for code review and project management, and collaborate with product managers to iterate on user-facing features using data-driven development.');

La secuencia de comandos de inicialización instala dos extensiones de PostgreSQL:

• google_ml_integration: Proporciona la función embedding() SQL, que llama a los modelos de incorporación de Vertex AI directamente desde SQL. Esta es una extensión a nivel de la base de datos que hace que las funciones de AA estén disponibles dentro de jobs_db. La marca a nivel de la instancia (--enable-google-ml-integration) que estableces durante la creación de la instancia permite que la VM de Cloud SQL llegue a Vertex AI. La extensión hace que las funciones de SQL estén disponibles dentro de esta base de datos específica.
• vector (pgvector): Agrega el tipo de datos vector y los operadores de distancia para almacenar y consultar incorporaciones.

La columna description_embedding es vector(3072), una columna pgvector que almacena vectores de 3,072 dimensiones. Por ahora, es NULL. Generarás y propagarás los embeddings en el próximo paso con la función embedding().

Finaliza la configuración de la base de datos

Es posible que la creación de la instancia de Cloud SQL que iniciaste en el paso anterior aún se esté ejecutando y no haya finalizado. Verifica que la instancia esté lista:

gcloud sql instances describe jobs-instance --format="value(state)"

Deberías ver el siguiente resultado:

RUNNABLE

Nota importante: Si no ves este estado RUNNABLE, ten paciencia y vuelve a intentarlo en unos minutos.

A continuación, otorga permiso a la cuenta de servicio de la instancia de Cloud SQL para llamar a Vertex AI. Esto es necesario para la función embedding() integrada que usarás en el siguiente paso:

SERVICE_ACCOUNT=$(gcloud sql instances describe jobs-instance --format="value(serviceAccountEmailAddress)")

gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user" \
  --quiet

Luego, crea una base de datos exclusiva para las ofertas de empleo:

gcloud sql databases create jobs_db --instance=jobs-instance

Deberías ver un resultado que confirme que se creó la base de datos:

Creating Cloud SQL database...done.                                                                         
Created database [jobs_db].
instance: jobs-instance
name: jobs_db
project: workshop-xxxxxxx

Conecta y completa la base de datos

Inicia el proxy de Cloud SQL Auth (cloud-sql-proxy está preinstalado en Cloud Shell). Esto proporciona una conexión autenticada y segura desde Cloud Shell a tu instancia de Cloud SQL:

cloud-sql-proxy ${GOOGLE_CLOUD_PROJECT}:${REGION}:jobs-instance --port 5432 &

Error de navegación: Si, de alguna manera, te encuentras con un error que dice port 5432 is already in use, ejecuta este comando para detener el proceso anterior y volver a ejecutar el comando anterior.

fuser -k 5432/tcp

Si se inicia el proxy, deberías ver este resultado en la terminal:

... Authorizing with Application Default Credentials
... [workshop-xxxxxx:your-location:jobs-instance] Listening on 127.0.0.1:5432
... The proxy has started successfully and is ready for new connections!

Notas: El proxy de Cloud SQL Auth solo es necesario para el acceso directo a la base de datos (inicialización, ejecución de secuencias de comandos). La caja de herramientas que configurarás en el siguiente paso controla su propia conexión a Cloud SQL de forma interna.

Ahora, la terminal actual genera el registro del proxy de Cloud SQL de forma continua. Abramos una pestaña de terminal nueva en Cloud Shell (haz clic en el ícono +) para que podamos concentrarnos más.

Vuelve a tu directorio de trabajo y activa el proyecto con la secuencia de comandos de configuración anterior.

cd ~/build-agent-adk-toolbox-cloudsql
bash setup_verify_trial_project.sh && source .env

Luego, ejecuta la secuencia de comandos de inicialización.

psql "host=127.0.0.1 port=5432 dbname=jobs_db user=postgres password=$DB_PASSWORD" -f seed.sql

Verás un resultado de la terminal como este

CREATE EXTENSION
CREATE EXTENSION
CREATE TABLE
INSERT 0 15

Verifiquemos los datos

psql "host=127.0.0.1 port=5432 dbname=jobs_db user=postgres password=$DB_PASSWORD" \
  -c "SELECT title, company, role, openings FROM jobs ORDER BY role, title;"

Deberías ver 15 ofertas de empleo en varios roles:

             title              |    company     |   role    | openings
---------------------------------+----------------+-----------+----------
 Senior Backend Engineer         | Stripe         | Backend   |        3
 Backend Engineer (Payments)     | Square         | Backend   |        3
 Cloud Architect                 | Google Cloud   | Cloud     |        1
 ...
(15 rows)

Sugerencia: Si el resultado se abre en un paginador (ves un mensaje : en la parte inferior), presiona q para salir y volver a la terminal.

Genera embeddings para las descripciones de empleos

Actualmente, la columna description_embedding de la tabla jobs es NULL. La extensión google_ml_integration integrada de Cloud SQL proporciona una función embedding() que llama a Vertex AI directamente desde SQL, sin necesidad de una secuencia de comandos de Python ni un SDK externo.

Inicia la generación de embeddings en segundo plano. Esto llama a Vertex AI para generar un vector de 3,072 dimensiones con el modelo gemini-embedding-001 para cada una de las 15 descripciones de trabajo:

psql "host=127.0.0.1 port=5432 dbname=jobs_db user=postgres password=$DB_PASSWORD" \
  -c "UPDATE jobs SET description_embedding = embedding('gemini-embedding-001', description)::vector;" &

Esto es lo que hace la secuencia de comandos:

• embedding('gemini-embedding-001', description): Llama al modelo de embedding de Gemini de Vertex AI directamente desde SQL y pasa el texto description de cada trabajo. Esta es la extensión google_ml_integration que instalaste en la secuencia de comandos inicial.
• ::vector: Convierte el array de números de punto flotante devuelto al tipo vector de pgvector para que se pueda almacenar y consultar con operadores de distancia.
• El UPDATE se ejecuta en las 15 filas y genera una incorporación de 3, 072 dimensiones por descripción del empleo.
• El comando & se ejecuta en segundo plano para que puedas seguir trabajando mientras Vertex AI procesa las incorporaciones.

Nota: ¿No conoces los conceptos de embedding? Haz clic aquí para obtener más información.

Nota importante: Este proceso tardará un poco. Podemos continuar con el siguiente paso mientras esperamos que finalice.

Al igual que con la ejecución de procesos en segundo plano anterior, la terminal actual mostrará el registro del proceso. Abramos una pestaña de terminal nueva en Cloud Shell (haz clic en el ícono +) para que podamos concentrarnos más.

Vuelve a tu directorio de trabajo y activa el proyecto con la secuencia de comandos de configuración anterior.

cd ~/build-agent-adk-toolbox-cloudsql
bash setup_verify_trial_project.sh && source .env

Luego, podemos continuar con el siguiente proceso.

6. Configura MCP Toolbox para bases de datos

En este paso, se presenta MCP Toolbox for Databases, se configura para que se conecte a tu instancia de Cloud SQL y se definen dos herramientas de consultas SQL estándar.

¿Qué es el MCP y por qué usar Toolbox?

El MCP (Protocolo de contexto del modelo) es un protocolo abierto que estandariza la forma en que los agentes de IA descubren herramientas externas y cómo interactúan con ellas. Define un modelo cliente-servidor: el agente aloja un cliente de MCP y los servidores de MCP exponen las herramientas. Cualquier cliente compatible con MCP puede usar cualquier servidor compatible con MCP. El agente no necesita código de integración personalizado para cada herramienta.

MCP Toolbox for Databases es un servidor de MCP de código abierto creado específicamente para el acceso a bases de datos. Sin él, escribirías funciones de Python que abren conexiones de bases de datos, administran grupos de conexiones, construyen consultas parametrizadas para evitar la inyección de SQL, controlan errores y, luego, incorporan todo ese código dentro de tu agente. Cada agente que necesita acceso a la base de datos repite este trabajo. Cambiar una pregunta significa volver a implementar el agente.

Con Toolbox, escribes un archivo YAML. Cada herramienta se asigna a una instrucción SQL con parámetros. Toolbox controla la reducción de conexiones, las consultas parametrizadas, la autenticación y la observabilidad. Las herramientas están desacopladas del agente: actualiza una búsqueda editando tools.yaml y reiniciando Toolbox, sin tocar el código del agente. Las mismas herramientas funcionan en ADK, LangGraph, LlamaIndex o cualquier framework compatible con MCP.

Escribe la configuración de las herramientas

Ahora, debemos crear un archivo llamado tools.yaml en el editor de Cloud Shell para configurar nuestras herramientas.

cloudshell edit tools.yaml

El archivo usa YAML de varios documentos: cada bloque separado por --- es un recurso independiente. Cada recurso tiene un kind que declara qué es (sources para las conexiones de bases de datos, tools para las acciones que pueden llamar a agentes) y un type que especifica el backend (cloud-sql-postgres para la fuente, postgres-sql para las herramientas basadas en SQL). Una herramienta hace referencia a su fuente por medio de name, que es la forma en que Toolbox sabe con qué grupo de conexiones debe ejecutar la herramienta. Las variables de entorno usan la sintaxis de ${VAR_NAME} y se resuelven en el inicio.

Sugerencia: Toolbox admite más de 50 fuentes de datos (AlloyDB, Spanner, BigQuery, Firestore, MySQL y muchas más) y tipos de herramientas prediseñadas más allá de SQL personalizado. Consulta la documentación de Resources para obtener la lista completa de los valores de kind y type disponibles.

Ahora, primero copiemos las siguientes secuencias de comandos en el archivo tools.yaml.

# tools.yaml

# --- Data Source ---
kind: sources
name: jobs-db
type: cloud-sql-postgres
project: ${GOOGLE_CLOUD_PROJECT}
region: ${REGION}
instance: jobs-instance
database: jobs_db
user: postgres
password: ${DB_PASSWORD}

---

Esta secuencia de comandos define el siguiente recurso:

• Fuente (jobs-db): Indica a Toolbox cómo conectarse a tu instancia de Cloud SQL para PostgreSQL. El tipo cloud-sql-postgres usa el conector de Cloud SQL de forma interna, lo que controla la autenticación y las conexiones seguras de forma automática. Los marcadores de posición ${GOOGLE_CLOUD_PROJECT} , ${REGION} y ${DB_PASSWORD} se resuelven a partir de las variables de entorno durante el inicio.

A continuación, agrega la siguiente secuencia de comandos debajo del símbolo --- en tools.yaml.

# --- Tool 1: Search jobs by role and/or tech stack ---
kind: tools
name: search-jobs
type: postgres-sql
source: jobs-db
description: >-
  Search for job listings by role category and/or tech stack.
  Use this tool when the developer wants to browse listings
  by role (e.g., Backend, Frontend, Data) or find jobs
  using a specific technology. Both parameters accept an
  empty string to match all values.
statement: |
  SELECT title, company, role, tech_stack, salary_range, location, openings
  FROM jobs
  WHERE ($1 = '' OR LOWER(role) = LOWER($1))
  AND ($2 = '' OR LOWER(tech_stack) LIKE '%' || LOWER($2) || '%')
  ORDER BY title
  LIMIT 10
parameters:
  - name: role
    type: string
    description: "The role category to filter by (e.g., 'Backend', 'Frontend', 'Data/AI', 'DevOps'). Use empty string for all roles."
  - name: tech_stack
    type: string
    description: "A technology to search for in the tech stack (partial match, e.g., 'Python', 'Kubernetes'). Use empty string for all tech stacks."

---

# --- Tool 2: Get full details for a specific job ---
kind: tools
name: get-job-details
type: postgres-sql
source: jobs-db
description: >-
  Get full details for a specific job listing including its description,
  salary range, location, and number of openings. Use this tool when the
  developer asks about a particular job by title or company.
statement: |
  SELECT title, company, role, tech_stack, salary_range, location, openings, description
  FROM jobs
  WHERE LOWER(title) LIKE '%' || LOWER($1) || '%'
  OR LOWER(company) LIKE '%' || LOWER($1) || '%'
parameters:
  - name: search_term
    type: string
    description: "The job title or company name to look up (partial match supported)."

---

Esta secuencia de comandos define el siguiente recurso:

• Herramientas 1 y 2 (search-jobs, get-job-details): Herramientas de consultas de SQL estándar. Cada uno asigna un nombre de herramienta (lo que ve el agente) a una instrucción SQL parametrizada (lo que ejecuta la base de datos). Los parámetros usan marcadores de posición posicionales $1 y $2. Toolbox ejecuta estas instrucciones como instrucciones preparadas, lo que evita la inyección de SQL.

Continuemos. Agrega la siguiente secuencia de comandos debajo del símbolo --- en tools.yaml.

# --- Embedding Model ---
kind: embeddingModels
name: gemini-embedding
type: gemini
model: gemini-embedding-001
dimension: 3072

---

Esta secuencia de comandos define el siguiente recurso:

• Modelo de embedding (gemini-embedding): Configura Toolbox para llamar al modelo gemini-embedding-001 de Gemini y generar embeddings de texto de 3,072 dimensiones. Toolbox usa las credenciales predeterminadas de la aplicación (ADC) para la autenticación. No se necesita una clave de API en Cloud Shell ni en Cloud Run. Indica que este dimension configurado aquí debe ser el mismo que configuramos anteriormente para inicializar la base de datos.

Continuemos. Agrega la siguiente secuencia de comandos debajo del símbolo --- en tools.yaml.

# --- Tool 3: Semantic search by description ---
kind: tools
name: search-jobs-by-description
type: postgres-sql
source: jobs-db
description: >-
  Find jobs that match a natural language description of what the developer
  is looking for. Use this tool when the developer describes their ideal job
  using interests, work style, career goals, or project type rather than a
  specific role or tech stack. Examples: "I want to work on AI chatbots,"
  "a remote job at a fintech startup," "something involving infrastructure
  and reliability."
statement: |
  SELECT title, company, role, tech_stack, salary_range, location, description
  FROM jobs
  WHERE description_embedding IS NOT NULL
  ORDER BY description_embedding <=> $1
  LIMIT 5
parameters:
  - name: search_query
    type: string
    description: "A natural language description of the kind of job the developer is looking for."
    embeddedBy: gemini-embedding

---

Esta secuencia de comandos define el siguiente recurso:

• Herramienta 3 (search-jobs-by-description): Es una herramienta de búsqueda de vectores. El parámetro search_query tiene embeddedBy: gemini-embedding, que le indica a Toolbox que intercepte el texto sin procesar, lo envíe al modelo de embedding y use el vector resultante en la sentencia SQL. El operador <=> es la distancia del coseno de pgvector. Los valores más pequeños significan descripciones más similares.

Por último, agrega la última herramienta debajo del símbolo --- en tools.yaml.

# --- Tool 4: Add a new job listing with automatic embedding ---
kind: tools
name: add-job
type: postgres-sql
source: jobs-db
description: >-
  Add a new job listing to the platform. Use this tool when a user asks
  to post a job that is not currently listed.
statement: |
  INSERT INTO jobs (title, company, role, tech_stack, salary_range, location, openings, description, description_embedding)
  VALUES ($1, $2, $3, $4, $5, $6, CAST($7 AS INTEGER), $8, $9)
  RETURNING title, company
parameters:
  - name: title
    type: string
    description: "The job title (e.g., 'Senior Backend Engineer')."
  - name: company
    type: string
    description: "The company name (e.g., 'Stripe', 'Spotify')."
  - name: role
    type: string
    description: "The role category (e.g., 'Backend', 'Frontend', 'Data/AI', 'DevOps')."
  - name: tech_stack
    type: string
    description: "Comma-separated list of technologies (e.g., 'Python, FastAPI, GCP')."
  - name: salary_range
    type: string
    description: "The salary range (e.g., '$150-200K/year')."
  - name: location
    type: string
    description: "Work location and arrangement (e.g., 'Remote')."
  - name: openings
    type: string
    description: "The number of open positions."
  - name: description
    type: string
    description: "A short description of the job (2-3 sentences)."
  - name: description_vector
    type: string
    description: "Auto-generated embedding vector for the job description."
    valueFromParam: description
    embeddedBy: gemini-embedding

Esta secuencia de comandos define el siguiente recurso:

• Tool 4 (add-job): Demuestra la transferencia de vectores. El parámetro description_vector tiene dos campos especiales:
• valueFromParam: description: Toolbox copia el valor del parámetro description en este. El LLM nunca ve este parámetro.
• embeddedBy: gemini-embedding: La Caja de herramientas incorpora el texto copiado en un vector antes de pasarlo a SQL.

El resultado es que una llamada a la herramienta almacena tanto el texto de la descripción sin procesar como su incorporación de vector, sin que el agente sepa nada sobre las incorporaciones.

El formato YAML de varios documentos separa cada recurso con ---. Cada documento tiene campos kind, name y type que definen qué es. En resumen, ya configuramos todo lo siguiente:

• Define la base de datos de origen
• Define herramientas ( herramienta 1 y 2) para consultar la base de datos con un filtro estándar
• Define el modelo de embedding
• Define la herramienta para realizar la búsqueda de vectores ( herramienta 3) en la base de datos.
• Define la herramienta para transferir datos vectoriales ( herramienta 4) a la base de datos

Verifica las incorporaciones

Antes de iniciar Toolbox, confirma que se haya completado la generación de la incorporación en segundo plano. Verifica que todos los trabajos ahora tengan incorporaciones:

psql "host=127.0.0.1 port=5432 dbname=jobs_db user=postgres password=$DB_PASSWORD" \
  -c "SELECT title, (description_embedding IS NOT NULL) AS has_embedding FROM jobs ORDER BY title;"

Cada fila debe mostrar t (verdadero) en la columna has_embedding. De lo contrario, puedes esperar hasta que finalice todo el proceso de creación de la incorporación de filas.

Nota: Si algunas filas aún muestran f, es posible que el proceso en segundo plano aún se esté ejecutando. Espera a que finalice. Deberías ver UPDATE 15 en el resultado de la terminal en la que ejecutas el comando cuando se complete.

           title            | has_embedding 
-----------------------------+---------------
 AI Engineer                 | t
 Backend Engineer (Payments) | t
 Cloud Architect             | t
 Data Engineer               | t
 DevOps Engineer             | t
 Frontend Engineer           | t
 Full Stack Engineer         | t

Sugerencia: Si el resultado se abre en un paginador (ves un mensaje : en la parte inferior), presiona q para salir y volver a la terminal.

Inicia el servidor de Toolbox

En el paso de configuración, ya descargamos el ejecutable toolbox. Asegúrate de que este archivo binario exista y se haya descargado correctamente. Si no es así, descárgalo y espera a que finalice el proceso.

cd ~/build-agent-adk-toolbox-cloudsql
if [ ! -f toolbox ]; then
  curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/linux/amd64/toolbox
fi
chmod +x toolbox

Exporta las variables de entorno necesarias y, luego, inicia Toolbox. Las variables GOOGLE_CLOUD_LOCATION y GOOGLE_GENAI_USE_VERTEXAI son obligatorias porque la configuración incluye un modelo de embeddings: GOOGLE_GENAI_USE_VERTEXAI le indica al SDK de Gemini que debe enrutar a través de Vertex AI (en lugar de la API de Gemini para consumidores) y GOOGLE_CLOUD_LOCATION le indica qué endpoint regional debe usar.

export GOOGLE_CLOUD_PROJECT=$GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=$GOOGLE_CLOUD_LOCATION
export GOOGLE_GENAI_USE_VERTEXAI=true
export DB_PASSWORD=$DB_PASSWORD
export REGION=$REGION
./toolbox --tools-file tools.yaml &

Deberías ver un resultado que confirme que el servidor está listo, como se muestra a continuación:

... INFO "Initialized 0 authServices: " 
... INFO "Initialized 1 embeddingModels: gemini-embedding" 
... INFO "Initialized 4 tools: add-job, search-jobs, get-job-details, search-jobs-by-description" 
...
... INFO "Server ready to serve!"

Al igual que en el paso anterior, esto generará otro proceso y mostrará resultados. Abramos una pestaña de terminal nueva en Cloud Shell (haz clic en el ícono +) para que podamos concentrarnos más.

Vuelve a tu directorio de trabajo y activa el proyecto con la secuencia de comandos de configuración anterior.

cd ~/build-agent-adk-toolbox-cloudsql
bash setup_verify_trial_project.sh && source .env

Verifica las herramientas

Consulta la API de Toolbox para enumerar todas las herramientas registradas:

curl -s http://localhost:5000/api/toolset | python3 -m json.tool

Deberías ver las herramientas con sus descripciones y parámetros. Como se muestra a continuación

...
       

"search-jobs-by-description": {
            "description": "Find jobs that match a natural language description of what the developer is looking for. Use this tool when the developer describes their ideal job using interests, work style, career goals, or project type rather than a specific role or tech stack. Examples: \"I want to work on AI chatbots,\" \"a remote job at a fintech startup,\" \"something involving infrastructure and reliability.\"",
            "parameters": [
                {
                    "name": "search_query",
                    "type": "string",
                    "required": true,
                    "description": "A natural language description of the kind of job the developer is looking for.",
                    "authSources": []
                }
            ],
            "authRequired": []
        }
...

Prueba la herramienta de search-jobs directamente:

curl -s -X POST http://localhost:5000/api/tool/search-jobs/invoke \
  -H "Content-Type: application/json" \
  -d '{"role": "Backend", "tech_stack": ""}' | jq '.result | fromjson'

La respuesta debe contener los dos trabajos de ingeniería de backend de tus datos iniciales.

[
  {
    "title": "Backend Engineer (Payments)",
    "company": "Square",
    "role": "Backend",
    "tech_stack": "Java, Spring Boot, PostgreSQL, Kafka",
    "salary_range": "$160-220K/year",
    "location": "San Francisco, Hybrid",
    "openings": 3
  },
  {
    "title": "Senior Backend Engineer",
    "company": "Stripe",
    "role": "Backend",
    "tech_stack": "Go, PostgreSQL, gRPC, Kubernetes",
    "salary_range": "$180-250K/year",
    "location": "San Francisco, Hybrid",
    "openings": 3
  }
]

7. Compila el agente del ADK

En este paso, se conecta el agente del ADK al servidor de Toolbox en ejecución y se prueban las cuatro herramientas: consultas estándar, búsqueda semántica y transferencia de vectores. El código del agente es mínimo: toda la lógica de la base de datos reside en tools.yaml.

Configura el entorno del agente

El ADK lee GOOGLE_GENAI_USE_VERTEXAI, GOOGLE_CLOUD_PROJECT y GOOGLE_CLOUD_LOCATION del entorno de shell, que ya configuraste en un paso anterior. La única variable específica del agente es TOOLBOX_URL. Agrégala al archivo .env del agente:

echo -e "\nTOOLBOX_URL=http://127.0.0.1:5000" >> jobs_agent/.env

Actualiza el módulo del agente

Abre jobs_agent/agent.py en el editor de Cloud Shell.

cloudshell edit jobs_agent/agent.py

y reemplaza el contenido con el siguiente código:

# jobs_agent/agent.py
import os

from google.adk.agents import LlmAgent
from toolbox_adk import ToolboxToolset

TOOLBOX_URL = os.environ.get("TOOLBOX_URL", "http://127.0.0.1:5000")

toolbox = ToolboxToolset(TOOLBOX_URL)

root_agent = LlmAgent(
    name="jobs_agent",
    model="gemini-2.5-flash",
    instruction="""You are a helpful assistant at "TechJobs," a tech job listing platform.

Your job:
- Help developers browse job listings by role or tech stack.
- Provide full details about specific positions, including salary range and number of openings.
- Recommend jobs based on natural language descriptions of what the developer is looking for.
- Add new job listings to the platform when asked.

When a developer asks about a specific job by title or company, use the get-job-details tool.
When a developer asks for a specific role category or tech stack, use the search-jobs tool.
When a developer describes what kind of job they want — by interest area, work style,
career goals, or project type — use the search-jobs-by-description tool for semantic search.
When in doubt between search-jobs and search-jobs-by-description, prefer
search-jobs-by-description — it searches job descriptions and finds more relevant matches.

If a position has no openings (openings is 0), let the developer know
and suggest similar alternatives from the search results.

Be conversational, knowledgeable, and concise.""",
    tools=[toolbox],
)

Observa que aquí no hay código de base de datos: ToolboxToolset se conecta al servidor de Toolbox en el inicio y carga todas las herramientas disponibles. El agente llama a las herramientas por su nombre. Toolbox traduce esas llamadas en consultas SQL contra Cloud SQL.

La variable de entorno TOOLBOX_URL tiene el valor predeterminado http://127.0.0.1:5000 para el desarrollo local. Cuando realices la implementación en Cloud Run más adelante, anularás este valor con la URL de Cloud Run del servicio de Toolbox. No se necesitan cambios en el código.

Actualmente, la instrucción solo hace referencia a las dos herramientas estándar (search-jobs y get-job-details). La expandirás en el siguiente paso cuando agregues herramientas de búsqueda semántica y de transferencia.

Prueba el agente

Inicia la IU de desarrollo del ADK:

cd ~/build-agent-adk-toolbox-cloudsql
uv run adk web

Abre la URL que se muestra en la terminal (por lo general, http://localhost:8000) con la función Vista previa web de Cloud Shell o Ctrl + clic en la URL que se muestra en la terminal. Selecciona jobs_agent en el menú desplegable de agentes en la esquina superior izquierda.

Sugerencia: Para usar la vista previa en la Web en Cloud Shell, haz clic en el botón Vista previa en la Web (el ícono cuadrado con un ojo) en la barra de herramientas de Cloud Shell y, luego, selecciona Vista previa en el puerto 8000.

Prueba búsquedas estándar

Prueba estas instrucciones para verificar las herramientas de SQL estándar:

What backend engineering jobs do you have?

Inspeccionar: El agente llama a search-jobs con role="Backend" y devuelve las dos posiciones de backend (Stripe y Square).

Any jobs using Kubernetes?

Inspeccionar: El agente llama a search-jobs con tech_stack="Kubernetes" y encuentra posiciones coincidentes en varios roles.

Tell me about the Cloud Architect position

Inspeccionar: El agente llama a get-job-details y devuelve la descripción completa, el rango salarial, la ubicación y la cantidad de vacantes.

Cómo probar la búsqueda semántica

Prueba con descripciones en lenguaje natural que no se asignen a un rol o una pila de tecnología específicos:

I want a remote job where I can work on AI and machine learning

Inspeccionar: El agente llama a search-jobs-by-description y devuelve trabajos como "Ingeniero de aprendizaje automático" en Spotify y "Ingeniero de IA" en Hugging Face.

Find me something in fintech with good work-life balance

Inspeccionar: Devuelve empleos en Revolut, Stripe y Square, empresas que manejan productos financieros.

I'm interested in infrastructure and reliability engineering

Inspect: Devuelve el rol de SRE en Cloudflare y DevOps en Datadog.

El agente intentará elegir la herramienta adecuada según el tipo de búsqueda: los filtros estructurados pasan por search-jobs y las descripciones en lenguaje natural pasan por search-jobs-by-description.

Transferencia de vectores de prueba

Pídele al agente que agregue un trabajo nuevo:

Add a new job: 'Robotics Software Engineer' at Boston Dynamics, role Robotics, tech stack: Python, C++, ROS, Computer Vision, salary $160-230K/year, location Waltham MA, Hybrid, 2 openings. Description: Design and implement autonomous navigation and manipulation algorithms for next-generation robots. Work on perception pipelines using computer vision and lidar, develop motion planning software in C++ and Python, and test systems on real hardware in warehouse and logistics environments.

Inspeccionar: El agente llama a add-job. Toolbox copia la descripción, genera su incorporación con gemini-embedding-001 y almacena ambos elementos en la base de datos, todo en una sola operación.

Ahora intenta buscarlo:

Find me jobs involving autonomous systems and working with physical hardware

Inspeccionar: El agente llama a search-jobs-by-description y "Ingeniero de software de robótica" aparece en los resultados.

La incorporación se generó automáticamente durante la operación INSERT, por lo que no se necesita ningún paso independiente.

Ahora ya tienes una aplicación de RAG agentic completamente funcional que utiliza ADK, MCP Toolbox y Cloud SQL. ¡Felicitaciones! Demos un paso más y, luego, implementemos estas apps en Cloud Run.

Ahora, detengamos la IU de desarrollo. Para ello, presiona Ctrl + C dos veces antes de continuar.

8. Implementa en Cloud Run

El agente y la Caja de herramientas funcionan de forma local. En este paso, se implementan ambos como servicios de Cloud Run para que se pueda acceder a ellos a través de Internet. El servicio de Toolbox se ejecuta como un servidor de MCP en Cloud Run, y el servicio de agente se conecta a él.

Prepara la caja de herramientas para la implementación

Crea un directorio de implementación para el servicio de Toolbox:

cd ~/build-agent-adk-toolbox-cloudsql
mkdir -p deploy-toolbox
cp toolbox tools.yaml deploy-toolbox/

Crea el Dockerfile para la caja de herramientas. Abre deploy-toolbox/Dockerfile en el editor de Cloud Shell:

cloudshell edit deploy-toolbox/Dockerfile

Copia la siguiente secuencia de comandos en él

# deploy-toolbox/Dockerfile
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY toolbox tools.yaml ./
RUN chmod +x toolbox
EXPOSE 8080
CMD ["./toolbox", "--tools-file", "tools.yaml", "--address", "0.0.0.0", "--port", "8080"]

El objeto binario de Toolbox y tools.yaml se empaquetan en una imagen mínima de Debian. Cloud Run enruta el tráfico al puerto 8080.

Implementa el servicio de Toolbox

cd ~/build-agent-adk-toolbox-cloudsql
gcloud run deploy toolbox-service \
  --source deploy-toolbox/ \
  --region $REGION \
  --set-env-vars "DB_PASSWORD=$DB_PASSWORD,GOOGLE_CLOUD_PROJECT=$GOOGLE_CLOUD_PROJECT,REGION=$REGION,GOOGLE_CLOUD_LOCATION=$GOOGLE_CLOUD_LOCATION,GOOGLE_GENAI_USE_VERTEXAI=true" \
  --allow-unauthenticated \
  --quiet

Importante: --allow-unauthenticated hace que la Toolbox sea accesible de forma pública, lo que está bien para este codelab. En la producción, omite este paso y autentica las llamadas entre servicios. Consulta Aloja servidores de MCP en Cloud Run para obtener más detalles.

Este comando envía el código fuente a Cloud Build, compila una imagen de contenedor, la envía a Artifact Registry y la implementa en Cloud Run. Esto tardará unos minutos. Mientras tanto, abramos una pestaña de terminal nueva en Cloud Shell (haz clic en el ícono +) para que podamos concentrarnos mejor.

Vuelve a tu directorio de trabajo y activa el proyecto con la secuencia de comandos de configuración anterior.

cd ~/build-agent-adk-toolbox-cloudsql
bash setup_verify_trial_project.sh && source .env

Prepara el agente para la implementación

Mientras se compila Toolbox, configura los archivos de implementación del agente.

Crea un Dockerfile en la raíz del proyecto. Abre Dockerfile en el editor de Cloud Shell:

cloudshell edit Dockerfile

Luego, copia el siguiente contenido

# Dockerfile
FROM ghcr.io/astral-sh/uv:python3.12-trixie-slim
WORKDIR /app
COPY pyproject.toml ./
COPY uv.lock ./
RUN uv sync --no-dev
COPY jobs_agent/ jobs_agent/
EXPOSE 8080
CMD ["uv", "run", "adk", "web", "--host", "0.0.0.0", "--port", "8080"]

Este Dockerfile usa ghcr.io/astral-sh/uv como imagen base, que incluye Python y uv preinstalados. No es necesario instalar uv por separado a través de pip.

Nota: Este Dockerfile usa adk web para entregar la IU de desarrollo, lo que resulta conveniente para las pruebas. En su lugar, las implementaciones de producción deben usar adk api_server.

Crea un archivo .dockerignore para excluir los archivos innecesarios de la imagen de contenedor:

cloudshell edit .dockerignore

Luego, copia la siguiente secuencia de comandos en él.

# .dockerignore
.venv/
__pycache__/
*.pyc
.env
jobs_agent/.env
toolbox
tools.yaml
seed.sql
deploy-toolbox/

Implementa el servicio del agente

Espera a que se complete la implementación de la Caja de herramientas. Recupera su URL de Cloud Run con el siguiente comando:

TOOLBOX_URL=$(gcloud run services describe toolbox-service \
  --region=$REGION \
  --format='value(status.url)')
echo "Toolbox URL: $TOOLBOX_URL"

Verás un resultado similar al siguiente:

Toolbox URL: https://toolbox-service-xxxxxx-xx.a.run.app

Luego, verifiquemos que la Caja de herramientas implementada funcione:

curl -s "$TOOLBOX_URL/api/toolset" | python3 -m json.tool | head -5

Si el resultado se muestra como en este ejemplo, la implementación ya se realizó correctamente.

{
    "serverVersion": "0.27.0+binary.linux.amd64.c5524d3",
    "tools": {
        "add-job": {
            "description": "Add a new job listing to the platform. Use this tool when a user asks to post a job that is not currently listed.",

A continuación, implementemos el agente y pasemos la URL de Toolbox como una variable de entorno:

cd ~/build-agent-adk-toolbox-cloudsql
gcloud run deploy jobs-agent \
  --source . \
  --region $REGION \
  --set-env-vars "TOOLBOX_URL=$TOOLBOX_URL,GOOGLE_CLOUD_PROJECT=$GOOGLE_CLOUD_PROJECT,GOOGLE_CLOUD_LOCATION=$GOOGLE_CLOUD_LOCATION,GOOGLE_GENAI_USE_VERTEXAI=TRUE" \
  --allow-unauthenticated \
  --quiet

El código del agente lee TOOLBOX_URL del entorno (ya configuraste esto). De forma local, apunta a http://127.0.0.1:5000; en Cloud Run, apunta a la URL del servicio de Toolbox. No es necesario realizar cambios en el código.

Prueba el agente implementado

Recupera la URL de Cloud Run del agente:

AGENT_URL=$(gcloud run services describe jobs-agent \
  --region=$REGION \
  --format='value(status.url)')
echo "Agent URL: $AGENT_URL"

Abre la URL en tu navegador. Se carga la IU para desarrolladores del ADK, la misma interfaz que usaste de forma local, pero ahora se ejecuta en Cloud Run.

Selecciona jobs_agent en el menú desplegable y realiza la prueba:

What backend engineering jobs do you have?

Inspeccionar: Consulta estándar a través de search-jobs

I want a remote job working on AI and machine learning

Inspeccionar: Búsqueda semántica a través de search-jobs-by-description

Ambas consultas funcionan a través de los servicios implementados: el agente en Cloud Run llama a la Caja de herramientas en Cloud Run, que consulta Cloud SQL.

9. Felicitaciones y limpieza

Compilaste y, luego, implementaste un asistente inteligente para la bolsa de trabajo que usa MCP Toolbox for Databases para conectar un agente de ADK y Cloud SQL PostgreSQL, con búsquedas de vectores semánticos y consultas de SQL estándar.

Qué aprendiste

• Cómo MCP estandariza el acceso a las herramientas para los agentes de IA y cómo MCP Toolbox for Databases aplica esto específicamente a las operaciones de bases de datos, reemplazando el código de bases de datos personalizado por una configuración declarativa de YAML
• Cómo configurar Cloud SQL PostgreSQL como fuente de datos de Toolbox con el tipo de fuente cloud-sql-postgres
• Cómo definir herramientas de consultas en SQL estándar con instrucciones parametrizadas que evitan la inyección de SQL
• Cómo habilitar la búsqueda de vectores con pgvector y gemini-embedding-001, con el parámetro embeddedBy para la incorporación automática de consultas
• Cómo valueFromParam permite la incorporación automática de vectores: El LLM proporciona una descripción de texto y Toolbox copia, incorpora y almacena el vector junto con el texto de forma silenciosa.
• Cómo ToolboxToolset del ADK carga herramientas desde un servidor de Toolbox en ejecución, lo que mantiene el código del agente al mínimo y la lógica de la base de datos completamente desacoplada
• Cómo implementar el servidor de MCP de Toolbox y el agente de ADK en Cloud Run como servicios independientes

Realiza una limpieza

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos creados en este codelab, puedes borrar los recursos individuales o todo el proyecto.

Opción 1: Borra el proyecto (recomendada)

La manera más fácil de realizar una limpieza es borrar el proyecto. Esto quita todos los recursos asociados con el proyecto.

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Importante: Puedes deshacer esta operación de eliminación durante un período limitado con este comando gcloud projects undelete ${GOOGLE_CLOUD_PROJECT}

Opción 2: Borra los recursos individuales

Si deseas conservar el proyecto, pero quitar solo los recursos creados en este codelab, haz lo siguiente:

gcloud run services delete jobs-agent --region=$REGION --quiet
gcloud run services delete toolbox-service --region=$REGION --quiet
gcloud sql instances delete jobs-instance --quiet
gcloud artifacts repositories delete cloud-run-source-deploy --location=$REGION --quiet 2>/dev/null