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

Base de données en tant qu'outil : RAG agentif avec ADK, MCP Toolbox et Cloud SQL

1. Introduction

L'utilité des agents d'IA dépend des données auxquelles ils peuvent accéder. La plupart des données réelles se trouvent dans des bases de données. Pour connecter des agents à des bases de données, il faut généralement écrire du code d'agent pour la gestion des connexions, la logique des requêtes et les pipelines d'intégration. Chaque agent qui a besoin d'accéder à une base de données répète ce travail, et chaque modification de requête nécessite de redéployer l'agent.

Cet atelier de programmation présente une approche différente. Vous déclarez vos outils de base de données dans un fichier YAML (requêtes SQL standards, recherche de similarité vectorielle, voire génération automatique d'embeddings), et MCP Toolbox for Databases gère toutes les opérations de base de données en tant que serveur MCP. Votre code d'agent reste minimal : chargez les outils et laissez Gemini décider lequel appeler.

Objectifs de l'atelier

Un concierge de restaurant pour "Foodie Finds" : un agent ADK optimisé par Gemini qui aide les clients à parcourir le menu d'un restaurant à l'aide de filtres standards (catégorie, type de cuisine) et à découvrir des plats grâce à des descriptions en langage naturel comme "Je veux quelque chose de pimenté et de végétarien". L'agent lit et écrit dans une base de données Cloud SQL PostgreSQL entièrement via MCP Toolbox for Databases, qui gère tous les accès à la base de données, y compris la génération automatique d'embeddings pour la recherche vectorielle. À la fin, la boîte à outils et l'agent s'exécutent sur Cloud Run.

Points abordés

Comment le protocole MCP (Model Context Protocol) standardise l'accès aux outils pour les agents d'IA et comment MCP Toolbox for Databases l'applique aux opérations de base de données
Configurer MCP Toolbox for Databases en tant que middleware entre un agent ADK et Cloud SQL PostgreSQL
Définissez les outils de base de données de manière déclarative dans tools.yaml : aucun code de base de données dans votre agent
Créer un agent ADK qui charge les outils à partir d'un serveur Toolbox en cours d'exécution à l'aide de ToolboxToolset
Générez des embeddings vectoriels à l'aide de la fonction embedding() intégrée de Cloud SQL et activez la recherche sémantique avec pgvector.
Utiliser la fonctionnalité valueFromParam pour l'ingestion automatique de vecteurs lors des opérations d'écriture
Déployer le serveur Toolbox et l'agent ADK sur Cloud Run

Prérequis

Un compte Google Cloud avec un compte de facturation d'essai
Connaître les bases de Python et de SQL
Une expérience préalable avec Cloud Database et l'ADK sera utile.

2. Configurer votre environnement

Cette étape prépare votre environnement Cloud Shell, configure votre projet Google Cloud et clone le dépôt de référence.

Ouvrir Cloud Shell

Ouvrez Cloud Shell dans votre navigateur. Cloud Shell fournit un environnement préconfiguré avec tous les outils dont vous avez besoin pour cet atelier de programmation. Cliquez sur Autoriser lorsque vous y êtes invité.

Cliquez ensuite sur Afficher > Terminal pour ouvrir le terminal.Votre interface devrait ressembler à ceci :

Ce sera notre interface principale, avec l'IDE en haut et le terminal en bas.

Configurer votre répertoire de travail

Créez votre répertoire de travail. Tout le code que vous écrivez dans cet atelier de programmation se trouve ici :

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

Ensuite, préparons plusieurs répertoires pour gérer des éléments tels que les scripts de seeding et les journaux.

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

Configurer un projet Google Cloud

Créez le fichier .env avec les variables de localisation :

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

Pour simplifier la configuration du projet dans votre terminal, téléchargez ce script de configuration du projet dans votre répertoire de travail :

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

Exécutez le script. Il valide votre compte de facturation d'essai, crée un projet (ou en valide un existant), enregistre l'ID de votre projet dans un fichier .env du répertoire actuel et définit le projet actif dans gcloud.

bash setup_verify_trial_project.sh && source .env

Le script va :

Vérifier que vous disposez d'un compte de facturation d'essai actif
Recherchez un projet existant dans .env (le cas échéant).
Créez un projet ou réutilisez-en un existant.
Associer le compte de facturation d'essai à votre projet
Enregistrez l'ID du projet dans .env.
Définir le projet comme projet gcloud actif

Vérifiez que le projet est correctement défini en examinant le texte jaune à côté de votre répertoire de travail dans l'invite du terminal Cloud Shell. L'ID de votre projet devrait s'afficher.

Activer l'API requise

Ensuite, nous devons activer plusieurs API pour le produit avec lequel nous allons 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) : votre agent utilise les modèles Gemini, et Toolbox utilise l'API d'embedding pour la recherche vectorielle.
API Cloud SQL Admin (sqladmin.googleapis.com) : vous provisionnez et gérez une instance PostgreSQL.
L'API Compute Engine (compute.googleapis.com) est requise pour créer des instances Cloud SQL.
Cloud Run, Cloud Build, Artifact Registry : utilisés lors de l'étape de déploiement plus loin dans cet atelier

3. Préparer des scripts pour l'initialisation de la base de données

Cette étape lance la création de l'instance Cloud SQL et exécute un script de configuration automatisé qui attend que l'instance soit prête, puis crée la base de données, l'alimente avec des offres d'emploi et génère des embeddings, le tout en une seule opération.

Commençons par ajouter le mot de passe de la base de données à votre fichier .env et à le recharger :

echo "DB_PASSWORD=restaurant-pwd" >> .env
echo "DB_INSTANCE=restaurant-instance" >> .env
echo "DB_NAME=restaurant_db" >> .env
source .env

Créer un script Bash pour créer une instance et une base de données

Créez ensuite le script scripts/setup_database.sh à l'aide de la commande suivante :

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

Ensuite, copiez le code suivant dans le fichier 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 ""

Créer un script Python pour l'amorçage des données

Créez ensuite le fichier Python de script de seeding scripts/setup_restaurant_db.py à l'aide de la commande ci-dessous.

cloudshell edit scripts/setup_restaurant_db.py

Copiez ensuite le code suivant dans le fichier 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()

Passons maintenant à l'étape suivante.

4. Créer et initialiser la base de données

Nos scripts sont maintenant prêts à être exécutés. Nous aurons besoin de Python pour exécuter notre script préparé. Préparons-le d'abord.

Configurer le projet Python

uv est un gestionnaire de packages et de projets Python rapide écrit en Rust ( documentation uv ). Cet atelier de programmation l'utilise pour la rapidité et la simplicité de la maintenance du projet Python.

Initialisez un projet Python et ajoutez les dépendances requises :

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

Notez que nous utilisons ici le SDK Python cloud-sql-python-connector pour initialiser une connexion sécurisée avec notre instance de base de données, qui est authentifiée à l'aide des identifiants par défaut de l'application.

Exécuter le script de configuration

Nous pouvons maintenant exécuter le script d'installation en arrière-plan et inspecter la sortie de la console qui sera écrite dans le fichier logs/atabase_setup.log à l'aide de la commande suivante. Vous pouvez passer à la section suivante en attendant la fin de cette opération.

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

Télécharger le fichier binaire de la boîte à outils

Dans ce tutoriel, nous allons utiliser MCP Toolbox. Heureusement, il est fourni avec un fichier binaire prédéfini qui est prêt à être utilisé dans l'environnement Linux. Maintenant, téléchargeons-le en arrière-plan, car cela prendra un certain temps. Exécutez la commande suivante pour télécharger le fichier binaire et inspecter le journal de sortie sur le logs/toolbox_dl.log . Vous pouvez passer à la section suivante en attendant la fin de cette opération.

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 &

Comprendre le script de configuration `scripts/setup_database.sh`

Essayons maintenant de comprendre le script de configuration que nous avons configuré précédemment. Il effectue les opérations suivantes :

La toute première commande que nous exécutons est la commande gcloud sql instances create avec l'option suivante :

db-custom-1-3840 est le plus petit niveau Cloud SQL à cœur dédié (1 vCPU, 3,75 Go de RAM) de l'édition ENTERPRISE.Pour en savoir plus, cliquez ici. Un cœur dédié est requis pour l'intégration de Vertex AI ML. Les niveaux à cœur partagé (db-f1-micro, db-g1-small) ne sont pas compatibles.
--root-password définit le mot de passe de l'utilisateur postgres par défaut.
--enable-google-ml-integration active l'intégration intégrée de Cloud SQL à Vertex AI, ce qui vous permet d'appeler des modèles d'embedding directement depuis SQL à l'aide de la fonction embedding().

Vérifiez si l'instance est déjà à l'état RUNNABLE.
Accordez au compte de service de l'instance Cloud SQL l'autorisation d'appeler Vertex AI à l'aide de la commande gcloud projects add-iam-policy-binding. Cette opération est requise pour la fonction embedding() intégrée que nous utiliserons pour initialiser la base de données.
Créer la base de données
Exécuter le script d'amorçage setup_restaurant_db.py

Comprendre le script d'amorçage `scripts/setup_restaurant_db.py`

Passons maintenant au script de seeding. Il effectue les opérations suivantes :

Initialiser la connexion à l'instance de base de données
Installe deux extensions PostgreSQL :

google_ml_integration : fournit la fonction SQL embedding(), qui appelle les modèles d'embedding Vertex AI directement à partir de SQL. Il s'agit d'une extension au niveau de la base de données qui rend les fonctions de ML disponibles dans restaurant_db. Le flag au niveau de l'instance (--enable-google-ml-integration) que vous définissez lors de la création de l'instance permet à la VM Cloud SQL d'accéder à Vertex AI. L'extension rend les fonctions SQL disponibles dans cette base de données spécifique.
vector (pgvector) : ajoute le type de données vector et les opérateurs de distance pour stocker et interroger les embeddings.

Créez la table et notez que la colonne description_embedding est vector(3072), c'est-à-dire une colonne pgvector qui stocke des vecteurs de dimension 3072.
Déplacer les données des éléments de menu initiaux
Générez les données d'embedding à partir du champ description et remplissez description_embedding à l'aide de l'intégration Vertex intégrée via la fonction embedding().

embedding('gemini-embedding-001', description) : appelle le modèle d'embedding Gemini de Vertex AI directement depuis SQL, en transmettant le texte description de chaque offre d'emploi. Il s'agit de l'extension google_ml_integration que vous avez installée dans le script de seed.
::vector : convertit le tableau float renvoyé au type vector de pgvector afin qu'il puisse être stocké et interrogé avec des opérateurs de distance.
UPDATE s'exécute sur les 15 lignes, générant un embedding de dimension 3072 par description de poste.

Cela préparera les données initiales auxquelles notre agent accédera.

5. Configurer MCP Toolbox for Databases

Cette étape présente MCP Toolbox for Databases, le configure pour qu'il se connecte à votre instance Cloud SQL et définit deux outils de requête SQL standards.

Qu'est-ce que MCP et pourquoi utiliser Toolbox ?

MCP (Model Context Protocol) est un protocole ouvert qui standardise la façon dont les agents d'IA découvrent les outils externes et interagissent avec eux. Il définit un modèle client-serveur : l'agent héberge un client MCP et les outils sont exposés par les serveurs MCP. N'importe quel client compatible avec MCP peut utiliser n'importe quel serveur compatible avec MCP. L'agent n'a pas besoin de code d'intégration personnalisé pour chaque outil.

MCP Toolbox for Databases est un serveur MCP Open Source conçu spécifiquement pour l'accès aux bases de données. Sans cela, vous devriez écrire des fonctions Python qui ouvrent des connexions à la base de données, gèrent les pools de connexions, construisent des requêtes paramétrées pour éviter les injections SQL, gèrent les erreurs et intègrent tout ce code dans votre agent. Chaque agent ayant besoin d'accéder à la base de données répète cette opération. Pour modifier une requête, vous devez redéployer l'agent.

Avec Toolbox, vous écrivez un fichier YAML. Chaque outil correspond à une instruction SQL paramétrée. La boîte à outils gère le regroupement des connexions, les requêtes paramétrées, l'authentification et l'observabilité. Les outils sont dissociés de l'agent. Vous pouvez mettre à jour une requête en modifiant tools.yaml et en redémarrant la boîte à outils, sans toucher au code de l'agent. Les mêmes outils fonctionnent avec ADK, LangGraph, LlamaIndex ou tout framework compatible avec MCP.

Écrire la configuration des outils

Nous devons maintenant créer un fichier nommé tools.yaml dans l'éditeur Cloud Shell pour configurer nos outils.

cloudshell edit tools.yaml

Le fichier utilise le format YAML multidocument : chaque bloc séparé par --- est une ressource autonome. Chaque ressource comporte un kind qui déclare ce qu'elle est (sources pour les connexions à la base de données, tools pour les actions appelables par l'agent) et un type qui spécifie le backend (cloud-sql-postgres pour la source, postgres-sql pour les outils basés sur SQL). Un outil fait référence à sa source par name, ce qui permet à Toolbox de savoir quel pool de connexions exécuter. Les variables d'environnement utilisent la syntaxe ${VAR_NAME} et sont résolues au démarrage.

Copions d'abord les scripts suivants dans le fichier 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}

---