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 bases de datos en un archivo YAML (consultas en 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 para la bolsa de trabajo de "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 completamente 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 embeddings para la búsqueda de vectores. Al final, tanto la Toolbox 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
Cómo compilar un agente del ADK que carga 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 de 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
Será útil tener experiencia previa con Cloud Database y el ADK.

2. Configura tu entorno

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

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

Luego, preparemos varios directorios para administrar elementos como los registros y las secuencias de comandos de inicialización.

mkdir -p ~/build-agent-adk-toolbox-cloudsql/scripts
mkdir -p ~/build-agent-adk-toolbox-cloudsql/logs

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

Para simplificar la configuración del proyecto en tu terminal, descarga esta 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:

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

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.

Activa la API requerida

A continuación, debemos habilitar varias APIs para el producto con el que interactuaremos:

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.

3. Preparación de secuencias de comandos para la inicialización de la base de datos

En este paso, se inicia la creación de la instancia de Cloud SQL y se ejecuta una secuencia de comandos de configuración automatizada que espera a que la instancia esté lista, luego crea la base de datos, la inicializa con ofertas de empleo y genera incorporaciones, todo en una sola operación.

Primero, agreguemos la contraseña de la base de datos a tu archivo .env y vuelve a cargarlo:

echo "DB_PASSWORD=techjobs-pwd" >> .env
echo "DB_INSTANCE=jobs-instance" >> .env
echo "DB_NAME=jobs_db" >> .env
source .env

Crea una secuencia de comandos de Bash para la creación de instancias y bases de datos

Luego, crea el script scripts/setup_database.sh con el siguiente comando:

mkdir -p ~/build-agent-adk-toolbox-cloudsql/scripts
cloudshell edit scripts/setup_database.sh

Luego, copia el siguiente código en el archivo scripts/setup_database.sh.

#!/bin/bash
set -e
source .env

echo "================================================"
echo "Database Setup"
echo "================================================"
echo ""

# Step 1: Create Cloud SQL instance
echo "[1/5] Creating Cloud SQL instance..."

# Check if instance already exists
if gcloud sql instances describe "$DB_INSTANCE" --quiet >/dev/null 2>&1; then
    echo "      Instance already exists"
else
    echo "      Creating instance (takes 5-10 minutes)..."
    gcloud sql instances create "$DB_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
fi
echo "      ✓ Instance ready"
echo ""

# Step 2: Verify instance is ready
echo "[2/5] Verifying instance state..."

STATE=$(gcloud sql instances describe "$DB_INSTANCE" --format='value(state)')

if [ "$STATE" != "RUNNABLE" ]; then
    echo "ERROR: Instance not ready (state: $STATE)"
    exit 1
fi
echo "      ✓ Instance is RUNNABLE"
echo ""

# Step 3: Grant IAM permissions
echo "[3/5] Granting Vertex AI permissions..."

SERVICE_ACCOUNT=$(gcloud sql instances describe "$DB_INSTANCE" \
    --format='value(serviceAccountEmailAddress)')

if [ -z "$SERVICE_ACCOUNT" ]; then
    echo "ERROR: Could not retrieve service account"
    exit 1
fi

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

echo "      ✓ Permissions granted"
echo ""

# Step 4: Create database
echo "[4/5] Creating database..."

# Check if database already exists
if gcloud sql databases describe "$DB_NAME" \
    --instance="$DB_INSTANCE" --quiet >/dev/null 2>&1; then
    echo "      Database already exists"
else
    gcloud sql databases create "$DB_NAME" \
        --instance="$DB_INSTANCE" \
        --quiet
fi

echo "      ✓ Database '$DB_NAME' ready"
echo ""

# Step 5: Seed database and generate embeddings
echo "[5/5] Seeding database and generating embeddings..."

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SETUP_SCRIPT="${SCRIPT_DIR}/setup_jobs_db.py"

if [ ! -f "$SETUP_SCRIPT" ]; then
    echo "ERROR: Setup script not found: $SETUP_SCRIPT"
    exit 1
fi

uv run "$SETUP_SCRIPT"

echo ""
echo "================================================"
echo "Setup complete!"
echo "================================================"
echo ""

Cómo crear una secuencia de comandos de Python para la inicialización de datos

Después de eso, crea el archivo de Python de la secuencia de comandos de inicialización scripts/setup_jobs_db.py con el siguiente comando.

cloudshell edit scripts/setup_jobs_db.py

Luego, copia el siguiente código en el archivo scripts/setup_jobs_db.py.

import os
import sys
from pathlib import Path
from dotenv import load_dotenv
from google.cloud.sql.connector import Connector
import pg8000
import time

# Load environment variables from .env file
env_path = Path(__file__).parent.parent / '.env'
load_dotenv(env_path)
EMBEDDING_MODEL='gemini-embedding-001'

# Verify required environment variables
required_vars = ['GOOGLE_CLOUD_PROJECT', 'REGION', 'DB_PASSWORD']
missing_vars = [var for var in required_vars if not os.environ.get(var)]

if missing_vars:
    print(f"ERROR: Missing required environment variables: {', '.join(missing_vars)}", file=sys.stderr)
    print(f"", file=sys.stderr)
    print(f"Expected .env file location: {env_path}", file=sys.stderr)
    if not env_path.exists():
        print(f"✗ File not found at that location", file=sys.stderr)
    else:
        print(f"✓ File exists but is missing the variables above", file=sys.stderr)
    print(f"", file=sys.stderr)
    print(f"Make sure your .env file contains:", file=sys.stderr)
    for var in missing_vars:
        print(f"  {var}=<value>", file=sys.stderr)
    sys.exit(1)

# Job listings data (fictional, for tutorial purposes only)
JOBS = [
    ("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."),
]


def get_connection():
    """Create a connection to Cloud SQL using the connector."""
    project = os.environ['GOOGLE_CLOUD_PROJECT']
    region = os.environ['REGION']
    password = os.environ['DB_PASSWORD']
    instance = os.environ['DB_INSTANCE']
    database = os.environ['DB_NAME']

    connector = Connector()
    conn = connector.connect(
        f"{project}:{region}:{instance}",
        "pg8000",
        user="postgres",
        password=password,
        db=database
    )
    return conn, connector


def create_schema(cursor):
    """Create extensions and jobs table."""
    cursor.execute("CREATE EXTENSION IF NOT EXISTS google_ml_integration")
    cursor.execute("CREATE EXTENSION IF NOT EXISTS vector")
    cursor.execute("""
        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)
        )
    """)


def seed_jobs(cursor, conn):
    """Insert job listings."""
    cursor.execute("SELECT COUNT(*) FROM jobs")
    existing_count = cursor.fetchone()[0]

    if existing_count > 0:
        print(f"      {existing_count} jobs already exist, skipping seed")
        return 0

    cursor.executemany("""
        INSERT INTO jobs (title, company, role, tech_stack, salary_range, location, openings, description)
        VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
    """, JOBS)
    conn.commit()
    return len(JOBS)


def generate_embeddings(cursor, conn):
    """Generate embeddings using Cloud SQL's embedding() function."""
    cursor.execute("SELECT COUNT(*) FROM jobs WHERE description_embedding IS NULL")
    null_count = cursor.fetchone()[0]

    if null_count == 0:
        print("      All jobs already have embeddings")
        return 0

    cursor.execute(f"""
        UPDATE jobs
        SET description_embedding = embedding('{EMBEDDING_MODEL}', description)::vector
        WHERE description_embedding IS NULL
    """)
    rows_updated = cursor.rowcount
    conn.commit()
    return rows_updated


def main():
    conn, connector = get_connection()
    cursor = conn.cursor()

    try:
        create_schema(cursor)
        conn.commit()

        seeded = seed_jobs(cursor, conn)
        if seeded > 0:
            print(f"      ✓ Inserted {seeded} jobs")

        # Waiting for vertex role propagation
        time.sleep(60)
        embedded = generate_embeddings(cursor, conn)
        if embedded > 0:
            print(f"      ✓ Generated {embedded} embeddings")

    except Exception as e:
        print(f"ERROR: {e}", file=sys.stderr)
        sys.exit(1)
    finally:
        cursor.close()
        conn.close()
        connector.close()


if __name__ == "__main__":
    main()

Ahora, pasemos al siguiente paso.

4. Crea e inicializa la base de datos

Ahora nuestros secuencias de comandos están listos para ejecutarse. Necesitaremos Python para ejecutar nuestra secuencia de comandos preparada, así que primero prepararemos eso.

Configura el proyecto de Python

uv es un administrador de proyectos y paquetes de Python rápido escrito en Rust ( documentación de uv). Este codelab lo usa para mantener el proyecto de Python de forma rápida y sencilla.

Inicializa un proyecto de Python y agrega las dependencias necesarias:

uv init
uv add cloud-sql-python-connector --extra pg8000
uv add python-dotenv

Ten en cuenta que aquí usamos el SDK de Python de cloud-sql-python-connector para inicializar una conexión segura con nuestra instancia de base de datos, que se autentica con las credenciales predeterminadas de la aplicación.

Ejecuta la secuencia de comandos de configuración

Ahora, podemos ejecutar la secuencia de comandos de configuración en segundo plano y, luego, inspeccionar el resultado de la consola que se escribirá en el archivo logs/atabase_setup.log con el siguiente comando. Puedes continuar con la siguiente sección mientras esperas que finalice este proceso.

mkdir -p ~/build-agent-adk-toolbox-cloudsql/logs
bash scripts/setup_database.sh > logs/database_setup.log 2>&1 &

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. Ahora, descarguémoslo en segundo plano, ya que tardará un poco. Ejecuta el siguiente comando para descargar el objeto binario y, luego, inspecciona el registro de salida en logs/toolbox_dl.log . Puedes continuar con la siguiente sección mientras esperas que finalice este proceso.

cd ~/build-agent-adk-toolbox-cloudsql
curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/v1.0.0/linux/amd64/toolbox > logs/toolbox_dl.log 2>&1 &

Información sobre la secuencia de comandos de configuración `scripts/setup_database.sh`

Ahora, intentemos comprender la secuencia de comandos de configuración que configuramos anteriormente. Realiza el siguiente proceso:

El primer comando que ejecutamos allí es el comando gcloud sql instances create con la siguiente marca

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().

Verifica si la instancia ya está en estado RUNNABLE.
Otorga permiso a la cuenta de servicio de la instancia de Cloud SQL para llamar a Vertex AI con el comando gcloud projects add-iam-policy-binding. Esto es necesario para la función embedding() integrada que usaremos cuando inicialicemos la base de datos.
Crea la base de datos
Ejecuta la secuencia de comandos de inicialización setup_jobs_db.py

Información sobre la secuencia de comandos de inicialización `scripts/setup_jobs_db.py`

Ahora, pasando a la secuencia de comandos de inicialización, esta secuencia de comandos hace lo siguiente:

Inicializa la conexión a la instancia de la base de datos
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.

Crea la tabla y observa que la columna description_embedding es vector(3072), una columna pgvector que almacena vectores de 3,072 dimensiones.
Propaga los datos de los trabajos iniciales
Genera los datos de incorporación del campo description y completa el campo description_embedding con la integración de Vertex integrada a través de la función embedding().

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.

Esto preparará los datos iniciales a los que accederá nuestro agente.

5. 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 de 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 lo que es (sources para las conexiones de bases de datos, tools para las acciones que puede llamar el agente) 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.

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

# tools.yaml

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

---