Banco de dados como uma ferramenta: RAG agêntico com ADK, MCP Toolbox e Cloud SQL

1. Introdução

A utilidade dos agentes de IA depende dos dados que eles podem acessar. A maioria dos dados do mundo real está em bancos de dados. Conectar agentes a eles geralmente significa escrever gerenciamento de conexões, lógica de consultas e incorporar pipelines no código do agente. Cada agente que precisa de acesso ao banco de dados repete esse trabalho, e cada mudança de consulta exige a nova implantação do agente.

Este codelab mostra uma abordagem diferente. Você declara as ferramentas de banco de dados em um arquivo YAML (consultas SQL padrão, pesquisa de similaridade vetorial e até mesmo geração automática de embeddings), e a MCP Toolbox para bancos de dados processa todas as operações de banco de dados como um servidor MCP. O código do seu agente permanece mínimo: carregue as ferramentas e deixe o Gemini decidir qual chamar.

O que você vai criar

Um assistente de quadro de empregos inteligente para "TechJobs", um agente do ADK com tecnologia do Gemini que ajuda os desenvolvedores a navegar em listas de empregos de tecnologia usando filtros padrão (função, conjunto de tecnologias) e descobrir vagas com descrições em linguagem natural, como "Quero um emprego remoto trabalhando com chatbots de IA". O agente lê e grava em um banco de dados do Cloud SQL PostgreSQL totalmente pela MCP Toolbox for Databases, que processa todo o acesso ao banco de dados, incluindo a geração automática de embeddings para pesquisa vetorial. No final, a caixa de ferramentas e o agente serão executados no Cloud Run.

O que você vai aprender

Como o MCP (Protocolo de Contexto de Modelo) padroniza o acesso a ferramentas para agentes de IA e como a MCP Toolbox para bancos de dados aplica isso às operações de banco de dados
Configurar o MCP Toolbox for Databases como middleware entre um agente ADK e o Cloud SQL PostgreSQL
Defina ferramentas de banco de dados de forma declarativa em tools.yaml. Não é necessário código de banco de dados no seu agente.
Criar um agente do ADK que carrega ferramentas de um servidor da caixa de ferramentas em execução usando ToolboxToolset
Gerar embeddings de vetores usando a função embedding() integrada do Cloud SQL e ativar a pesquisa semântica com pgvector
Usar o recurso valueFromParam para ingestão automática de vetores em operações de gravação
Implantar o servidor da caixa de ferramentas e o agente do ADK no Cloud Run

Pré-requisitos

Uma conta do Google Cloud com uma conta de faturamento de teste
Conhecimento básico de Python e SQL
Experiência prévia com o Cloud Database e o ADK é útil

2. Configuração de seu ambiente

Esta etapa prepara seu ambiente do Cloud Shell, configura seu projeto do Google Cloud e clona o repositório de referência.

Abra o Cloud Shell

Abra o Cloud Shell no navegador. O Cloud Shell oferece um ambiente pré-configurado com todas as ferramentas necessárias para este codelab. Clique em Autorizar quando solicitado a

Em seguida, clique em Visualizar -> Terminal para abrir o terminal.Sua interface vai ficar parecida com esta:

Essa será nossa interface principal, com o IDE na parte de cima e o terminal na parte de baixo.

Configurar seu diretório de trabalho

Crie o diretório de trabalho. Todo o código que você escrever neste codelab vai ficar aqui:

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

Depois disso, vamos preparar vários diretórios para gerenciar itens como scripts de propagação e registros.

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

Configuração no projeto do Google Cloud

Crie o arquivo .env com as variáveis de local:

# 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 a configuração do projeto no terminal, baixe este script de configuração no diretório de trabalho:

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

Execute o script. Ele verifica sua conta de faturamento de teste, cria um novo projeto (ou valida um existente), salva o ID do projeto em um arquivo .env no diretório atual e define o projeto ativo em gcloud.

bash setup_verify_trial_project.sh && source .env

O script faz o seguinte:

Verifique se você tem uma conta de faturamento de teste ativa
Verifique se há um projeto em .env (se houver).
Crie um novo projeto ou reutilize o atual
Vincular a conta de faturamento de teste ao projeto
Salve o ID do projeto em .env
Defina o projeto como o projeto gcloud ativo

Verifique se o projeto está definido corretamente conferindo o texto amarelo ao lado do diretório de trabalho no prompt do terminal do Cloud Shell. Ele vai mostrar o ID do projeto.

Ativar a API necessária

Em seguida, precisamos ativar várias APIs para o produto com que vamos interagir:

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

API Vertex AI (aiplatform.googleapis.com): seu agente usa modelos do Gemini, e a caixa de ferramentas usa a API Embedding para pesquisa vetorial.
API Cloud SQL Admin (sqladmin.googleapis.com): você provisiona e gerencia uma instância do PostgreSQL.
API Compute Engine (compute.googleapis.com): necessária para criar instâncias do Cloud SQL.
Cloud Run, Cloud Build, Artifact Registry: usados na etapa de implantação mais adiante neste codelab.

3. Como preparar scripts para inicialização de banco de dados

Esta etapa inicia a criação da instância do Cloud SQL e executa um script de configuração automatizado que aguarda a instância ficar pronta, cria o banco de dados, o preenche com anúncios de emprego e gera incorporações, tudo em uma única operação.

Primeiro, adicione a senha do banco de dados ao arquivo .env e recarregue-o:

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

Como criar um script Bash para criação de instâncias e bancos de dados

Em seguida, crie o script scripts/setup_database.sh com o seguinte comando:

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

Em seguida, copie o código abaixo no arquivo 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 ""

Como criar um script Python para propagação de dados

Depois disso, crie o arquivo Python do script de propagação scripts/setup_jobs_db.py usando o comando abaixo:

cloudshell edit scripts/setup_jobs_db.py

Em seguida, copie o código abaixo no arquivo 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()

Agora, vamos para a próxima etapa

4. Criar e inicializar o banco de dados

Agora nossos scripts estão prontos para serem executados. Vamos precisar do Python para executar o script preparado. Então, vamos preparar isso primeiro.

Configurar o projeto Python

uv é um gerenciador de projetos e pacotes Python rápido escrito em Rust ( documentações do uv). Este codelab o usa para agilidade e simplicidade na manutenção do projeto Python.

Inicialize um projeto Python e adicione as dependências necessárias:

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

Estamos usando o SDK do Python cloud-sql-python-connector para inicializar uma conexão segura com a instância do banco de dados, que é autenticada usando o Application Default Credentials.

Execute o script de configuração

Agora, podemos executar o script de configuração em segundo plano e inspecionar a saída do console, que será gravada no arquivo logs/atabase_setup.log usando o seguinte comando. Você pode continuar para a próxima seção enquanto espera a conclusão.

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

Baixe o binário da caixa de ferramentas

Vamos usar a caixa de ferramentas do MCP neste tutorial. Felizmente, ela vem com um binário pré-criado pronto para ser usado no ambiente Linux. Agora, vamos fazer o download em segundo plano, já que isso leva um tempo. Execute o comando a seguir para fazer o download do binário e inspecionar o registro de saída no logs/toolbox_dl.log . Você pode continuar para a próxima seção enquanto espera a conclusão.

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 &

Como entender o script de configuração `scripts/setup_database.sh`

Agora vamos tentar entender o script de configuração que configuramos anteriormente. Ele faz o seguinte processo:

O primeiro comando que executamos é o gcloud sql instances create com a seguinte flag:

db-custom-1-3840 é o menor nível do Cloud SQL de núcleo dedicado (1 vCPU, 3,75 GB de RAM) na edição ENTERPRISE. Leia mais detalhes aqui. Um núcleo dedicado é necessário para a integração de ML da Vertex AI. Os níveis de núcleo compartilhado (db-f1-micro, db-g1-small) não oferecem suporte a ela.
--root-password define a senha do usuário postgres padrão.
O --enable-google-ml-integration ativa a integração integrada do Cloud SQL com a Vertex AI, permitindo que você chame modelos de embedding diretamente do SQL usando a função embedding().

Verifique se a instância já está no status RUNNABLE.
Conceda à conta de serviço da instância do Cloud SQL permissão para chamar a Vertex AI usando o comando gcloud projects add-iam-policy-binding. Isso é necessário para a função embedding() integrada que usaremos ao propagar o banco de dados.
Criar o banco de dados
Executar o script de inicialização setup_jobs_db.py

Como entender o script de inicialização `scripts/setup_jobs_db.py`

Agora, passando para o script de propagação, ele faz o seguinte:

Inicializar a conexão com a instância do banco de dados
Instala duas extensões do PostgreSQL:

google_ml_integration: fornece a função SQL embedding(), que chama modelos de embedding da Vertex AI diretamente do SQL. É uma extensão no nível do banco de dados que disponibiliza funções de ML no jobs_db. A flag no nível da instância (--enable-google-ml-integration) definida durante a criação da instância permite que a VM do Cloud SQL alcance a Vertex AI. A extensão disponibiliza as funções SQL nesse banco de dados específico.
vector (pgvector): adiciona o tipo de dados vector e operadores de distância para armazenar e consultar incorporações.

Crie a tabela. Observe que a coluna description_embedding é vector(3072), uma coluna pgvector que armazena vetores de 3.072 dimensões.
Propagar os dados iniciais de jobs
Gere os dados de embedding do campo description e preencha o description_embedding usando a integração do Vertex integrada pela função embedding().

embedding('gemini-embedding-001', description): chama o modelo de embedding do Gemini da Vertex AI diretamente do SQL, transmitindo o texto description de cada vaga. Essa é a extensão google_ml_integration que você instalou no script de inicialização.
::vector: converte a matriz de ponto flutuante retornada para o tipo vector do pgvector para que ela possa ser armazenada e consultada com operadores de distância.
O UPDATE é executado em todas as 15 linhas, gerando uma incorporação de 3.072 dimensões por descrição de vaga.

Isso vai preparar os dados iniciais que serão acessados pelo nosso agente.

5. Configurar a MCP Toolbox para bancos de dados

Esta etapa apresenta a caixa de ferramentas do MCP para bancos de dados, configura a conexão com sua instância do Cloud SQL e define duas ferramentas padrão de consulta SQL.

O que é o MCP e por que usar a Toolbox?

O MCP (Protocolo de Contexto de Modelo) é um protocolo aberto que padroniza como os agentes de IA descobrem e interagem com ferramentas externas. Ele define um modelo cliente-servidor: o agente hospeda um cliente MCP, e as ferramentas são expostas por servidores MCP. Qualquer cliente compatível com o MCP pode usar qualquer servidor compatível com o MCP. O agente não precisa de um código de integração personalizado para cada ferramenta.

O MCP Toolbox for Databases é um servidor MCP de código aberto criado especificamente para acesso a bancos de dados. Sem ele, você escreveria funções Python que abrem conexões de banco de dados, gerenciam pools de conexões, criam consultas parametrizadas para evitar injeção de SQL, processam erros e incorporam todo esse código no seu agente. Cada agente que precisa de acesso ao banco de dados repete esse trabalho. Mudar uma consulta significa reimplantação do agente.

Com a caixa de ferramentas, você escreve um arquivo YAML. Cada ferramenta é mapeada para uma instrução SQL parametrizada. A caixa de ferramentas processa o pooling de conexões, consultas parametrizadas, autenticação e capacidade de observação. As ferramentas são dissociadas do agente. Para atualizar uma consulta, edite tools.yaml e reinicie a caixa de ferramentas sem mexer no código do agente. As mesmas ferramentas funcionam no ADK, LangGraph, LlamaIndex ou qualquer framework compatível com o MCP.

Escreva a configuração das ferramentas

Agora, precisamos criar um arquivo chamado tools.yaml no editor do Cloud Shell para configurar a configuração das ferramentas.

cloudshell edit tools.yaml

O arquivo usa YAML de vários documentos. Cada bloco separado por --- é um recurso independente. Todo recurso tem um kind que declara o que ele é (sources para conexões de banco de dados, tools para ações chamáveis por agente) e um type que especifica o back-end (cloud-sql-postgres para a origem, postgres-sql para ferramentas baseadas em SQL). Uma ferramenta faz referência à fonte usando name, que é como a caixa de ferramentas sabe qual pool de conexões executar. As variáveis de ambiente usam a sintaxe ${VAR_NAME} e são resolvidas na inicialização.

Agora, vamos copiar os seguintes scripts primeiro no arquivo 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}

---