Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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, e conectar agentes a eles geralmente significa escrever gerenciamento de conexões, lógica de consulta 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 for Databases processa todas as operações do 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 concierge de restaurantes para "Foodie Finds", um agente do ADK com tecnologia do Gemini que ajuda os clientes a navegar pelo cardápio de um restaurante usando filtros padrão (categoria, tipo de culinária) e descobrir pratos com descrições em linguagem natural, como "Quero algo picante e vegetariano". 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 for Databases aplica isso a 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 há 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
Use 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 seu 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 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:

Verificar 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 deve 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. Em seguida, ele 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=restaurant-pwd" >> .env
echo "DB_INSTANCE=restaurant-instance" >> .env
echo "DB_NAME=restaurant_db" >> .env
source .env

Como criar um script Bash para criação de instância e banco 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_restaurant_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_restaurant_db.py usando o comando abaixo:

cloudshell edit scripts/setup_restaurant_db.py

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

# Menu items data
MENU_ITEMS = [
    ("Truffle Mushroom Risotto", "Italian", "Main Course",
     "Arborio rice, truffle oil, porcini mushrooms, parmesan, white wine",
     "$28", "Vegetarian, Gluten-Free", True,
     "A creamy, luxurious risotto made with arborio rice slow-cooked in white wine and mushroom broth, finished with shaved black truffle and aged parmesan. The porcini mushrooms add a deep, earthy flavor that pairs beautifully with the delicate truffle oil drizzled on top."),
    ("Spicy Tuna Tartare", "Japanese", "Appetizer",
     "Ahi tuna, sriracha, sesame oil, avocado, crispy wonton",
     "$22", "Gluten-Free, Dairy-Free", True,
     "Fresh ahi tuna diced and tossed with sriracha aioli, toasted sesame oil, and lime juice, served atop creamy avocado slices with crispy wonton chips. A perfect balance of heat, richness, and crunch inspired by modern Japanese fusion cuisine."),
    ("Lamb Kofta Kebab", "Middle Eastern", "Main Course",
     "Ground lamb, cumin, coriander, yogurt sauce, flatbread",
     "$24", "Halal", True,
     "Hand-formed spiced lamb kebabs grilled over charcoal, seasoned with cumin, coriander, and sumac. Served with warm flatbread, tangy yogurt-cucumber sauce, and a fresh herb salad. A classic Middle Eastern street food elevated with premium ingredients."),
    ("Pad Thai", "Thai", "Main Course",
     "Rice noodles, shrimp, tamarind, peanuts, bean sprouts, lime",
     "$19", "Gluten-Free, Dairy-Free", True,
     "Stir-fried rice noodles with tiger shrimp, scrambled egg, and a sweet-sour tamarind sauce, topped with crushed peanuts, fresh bean sprouts, and a squeeze of lime. This classic Thai street food dish balances sweet, sour, salty, and umami in every bite."),
    ("Margherita Pizza", "Italian", "Main Course",
     "San Marzano tomatoes, fresh mozzarella, basil, olive oil",
     "$18", "Vegetarian", True,
     "A Neapolitan-style pizza with a thin, charred crust topped with crushed San Marzano tomatoes, creamy buffalo mozzarella, fresh basil leaves, and a drizzle of extra virgin olive oil. Simple, classic, and made with imported Italian ingredients."),
    ("Miso Glazed Black Cod", "Japanese", "Main Course",
     "Black cod, white miso, mirin, sake, pickled ginger",
     "$36", "Gluten-Free, Dairy-Free", True,
     "Buttery black cod marinated for 72 hours in a sweet white miso glaze with mirin and sake, then broiled until caramelized. Served with pickled ginger and steamed bok choy. A signature dish inspired by Nobu's iconic preparation."),
    ("Caesar Salad", "American", "Appetizer",
     "Romaine lettuce, parmesan, croutons, anchovy dressing",
     "$14", "Contains Gluten", True,
     "Crisp romaine hearts tossed with a house-made anchovy-garlic dressing, shaved parmesan, and golden sourdough croutons. A timeless salad that serves as the perfect light starter or side dish with grilled proteins."),
    ("Chicken Tikka Masala", "Indian", "Main Course",
     "Chicken thigh, tomato cream sauce, garam masala, basmati rice",
     "$21", "Gluten-Free", True,
     "Tender chunks of tandoori-marinated chicken simmered in a rich, creamy tomato sauce spiced with garam masala, cumin, and fenugreek. Served over fragrant basmati rice with warm garlic naan on the side."),
    ("Chocolate Lava Cake", "French", "Dessert",
     "Dark chocolate, butter, eggs, vanilla, powdered sugar",
     "$15", "Vegetarian", True,
     "A warm, individual-sized chocolate cake with a molten dark chocolate center that flows when you break through the delicate outer shell. Made with 70% Belgian dark chocolate and served with a scoop of vanilla bean ice cream."),
    ("Pho Bo", "Vietnamese", "Main Course",
     "Rice noodles, beef brisket, star anise, cinnamon, bean sprouts, Thai basil",
     "$17", "Gluten-Free, Dairy-Free", True,
     "A deeply aromatic beef broth simmered for 12 hours with star anise, cinnamon, and charred ginger, ladled over rice noodles and thinly sliced beef brisket. Served with fresh Thai basil, bean sprouts, jalapeño, and lime for the table to customize."),
    ("Lobster Bisque", "French", "Appetizer",
     "Lobster, heavy cream, cognac, tarragon, cayenne",
     "$19", "Gluten-Free", True,
     "A velvety smooth soup made from roasted lobster shells, finished with heavy cream, a splash of cognac, and fresh tarragon. Each bowl is garnished with tender lobster meat and a pinch of cayenne for subtle warmth."),
    ("Falafel Plate", "Middle Eastern", "Main Course",
     "Chickpeas, herbs, tahini, pickled vegetables, hummus",
     "$16", "Vegan, Gluten-Free", True,
     "Crispy-on-the-outside, fluffy-on-the-inside chickpea fritters seasoned with fresh parsley, cilantro, and cumin. Served with creamy tahini sauce, house-made hummus, pickled turnips, and warm pita bread."),
    ("Crème Brûlée", "French", "Dessert",
     "Heavy cream, vanilla bean, egg yolks, caramelized sugar",
     "$13", "Vegetarian, Gluten-Free", True,
     "A classic French custard made with Madagascar vanilla bean and farm-fresh egg yolks, topped with a perfectly torched layer of caramelized sugar that cracks with a satisfying snap. Rich, creamy, and elegantly simple."),
    ("Korean BBQ Short Ribs", "Korean", "Main Course",
     "Beef short ribs, soy sauce, sesame, garlic, pear marinade",
     "$32", "Dairy-Free", False,
     "Premium beef short ribs marinated overnight in a sweet and savory blend of soy sauce, Asian pear, garlic, and toasted sesame. Grilled tableside over charcoal and served with lettuce wraps, pickled daikon, and gochujang dipping sauce."),
    ("Tiramisu", "Italian", "Dessert",
     "Mascarpone, espresso, ladyfingers, cocoa, Marsala wine",
     "$14", "Vegetarian, Contains Gluten", True,
     "Layers of espresso-soaked ladyfingers and whipped mascarpone cream flavored with Marsala wine, dusted with premium Dutch cocoa powder. Made fresh daily and chilled for 24 hours to develop rich, complex flavors."),
]


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 menu_items 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 menu_items (
            id SERIAL PRIMARY KEY,
            name VARCHAR NOT NULL,
            cuisine_type VARCHAR NOT NULL,
            category VARCHAR NOT NULL,
            ingredients VARCHAR NOT NULL,
            price VARCHAR NOT NULL,
            dietary_tags VARCHAR NOT NULL,
            available BOOLEAN NOT NULL DEFAULT TRUE,
            description TEXT NOT NULL,
            description_embedding vector(3072)
        )
    """)


def seed_menu_items(cursor, conn):
    """Insert menu items."""
    cursor.execute("SELECT COUNT(*) FROM menu_items")
    existing_count = cursor.fetchone()[0]

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

    cursor.executemany("""
        INSERT INTO menu_items (name, cuisine_type, category, ingredients, price, dietary_tags, available, description)
        VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
    """, MENU_ITEMS)
    conn.commit()
    return len(MENU_ITEMS)


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

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

    cursor.execute(f"""
        UPDATE menu_items
        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_menu_items(cursor, conn)
        if seeded > 0:
            print(f"      ✓ Inserted {seeded} menu items")

        # 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ção 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 as credenciais padrão do aplicativo.

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 MCP Toolbox 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 baixar o 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.1.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 executado é 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 propagação setup_restaurant_db.py

Como entender o script de inicialização `scripts/setup_restaurant_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 restaurant_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 dos itens de menu
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 job. 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 for Databases

Esta etapa apresenta o MCP Toolbox for Databases, configura a conexão com sua instância do Cloud SQL e define duas ferramentas de consulta SQL padrão.

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 reimplantar o agente.

Com a caixa de ferramentas, você grava um arquivo YAML. Cada ferramenta é mapeada para uma instrução SQL parametrizada. A caixa de ferramentas processa o pool de conexões, consultas parametrizadas, autenticação e observabilidade. As ferramentas são dissociadas do agente. Para atualizar uma consulta, edite tools.yaml e reinicie a caixa de ferramentas sem tocar 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 à origem dela por 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: restaurant-db
type: cloud-sql-postgres
project: ${GOOGLE_CLOUD_PROJECT}
region: ${REGION}
instance: ${DB_INSTANCE}
database: ${DB_NAME}
user: postgres
password: ${DB_PASSWORD}

---