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

1. Introduction

L'utilité des agents IA dépend des données auxquelles ils ont accès. La plupart des données réelles se trouvent dans des bases de données. Connecter des agents à des bases de données signifie généralement écrire la gestion des connexions, la logique des requêtes et les pipelines d'intégration dans le code de votre agent. Chaque agent qui a besoin d'accéder à la base de données répète cette tâche, et chaque modification de requête nécessite un redéploiement de 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 d'embeddings automatiques). MCP Toolbox pour les bases de données 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 assistant intelligent pour les tableaux d'offres d'emploi pour "TechJobs" : il s'agit d'un agent ADK optimisé par Gemini qui aide les développeurs à parcourir les offres d'emploi dans le secteur de la technologie à l'aide de filtres standards (rôle, pile technologique) et à découvrir des emplois grâce à des descriptions en langage naturel comme "Je recherche un emploi à distance dans le domaine des chatbots d'IA". 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 pour les bases de données 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 de la boîte à outils 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
Aucune expérience préalable avec ADK, MCP Toolbox ou pgvector n'est requise.

2. Configurer votre environnement

REMARQUES IMPORTANTES :

Ce tutoriel nécessite un projet Google Cloud associé à un compte de facturation actif. Si vous n'en avez pas encore, veuillez suivre les étapes ci-dessous pour obtenir un compte de facturation d'essai que vous pourrez utiliser pour ce tutoriel :

Ouvrir une fenêtre de navigation privée
Si vous participez à un atelier, l'URL du portail d'échange est généralement fournie lors de la session. Sinon, vous pouvez accéder à ce portail d'échange de compte de facturation d'essai.
Connectez-vous avec votre compte Gmail personnel ( les adresses e-mail Google Workspace et autres ne fonctionneront pas). )
Suivez les instructions d'échange détaillées pour créer un projet Google Cloud associé au compte de facturation d'essai que vous avez déjà revendiqué pour ce tutoriel.

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 écrirez 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

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

Téléchargez le 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.

Si votre session Cloud Shell est réinitialisée à un moment donné de cet atelier de programmation, revenez à votre répertoire de travail et réexécutez bash setup_verify_trial_project.sh && source .env pour restaurer la configuration de votre projet. Vérifiez que le texte jaune de l'ID du projet réapparaît dans l'invite du terminal.

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.
API Compute Engine (compute.googleapis.com) : 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. Créer l'instance de base de données

Cette étape configure la création de l'instance Cloud SQL en arrière-plan. Elle est provisionnée pendant que vous poursuivez le tutoriel.

Démarrer la création de l'instance

Ajoutez le mot de passe de la base de données à votre fichier .env et rechargez-le :

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

Lancez la création de l'instance Cloud SQL. Cette opération s'exécute en arrière-plan pour que vous puissiez continuer à travailler :

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

db-custom-1-3840 est le plus petit niveau Cloud SQL à cœur dédié (1 vCPU, 3,75 Go de RAM) dans l'édition ENTERPRISE. Pour en savoir plus, cliquez ici. Un cœur dédié est requis pour l'intégration 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().
& exécute la commande en arrière-plan.

Cette opération s'exécutera en arrière-plan. Téléchargeons maintenant le binaire MCP Toolbox. Vous pouvez le faire dans le même terminal.

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. Téléchargeons-le en arrière-plan, car cela prend un certain temps.

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

Laissez ce processus s'exécuter dans l'onglet actuel (nous l'exécutons déjà en arrière-plan, mais la sortie sera toujours affichée). Ouvrons un nouvel onglet de terminal dans Cloud Shell (cliquez sur l'icône +) pour nous concentrer davantage.

Revenez à votre répertoire de travail et activez le projet à l'aide du script de configuration précédent.

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

Cette étape configure le projet Python, installe les dépendances et crée le répertoire de l'agent ADK.

4. Initialiser le projet d'agent

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 sa rapidité et sa simplicité.

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

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

google-adk : kit de développement d'agents de Google, y compris le SDK Gemini
toolbox-adk : intégration d'ADK pour MCP Toolbox for Databases.

Créer la structure de répertoire de l'agent

L'ADK attend une structure de dossier spécifique : un répertoire nommé d'après votre agent contenant __init__.py, agent.py et .env. Pour vous aider, il dispose d'une commande intégrée permettant d'établir rapidement la structure :

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

Votre répertoire devrait maintenant se présenter comme suit :

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

5. Déplacer la base de données des fiches d'emploi

Cette étape écrit les données de départ, attend que l'instance Cloud SQL ait terminé le provisionnement et charge la table jobs avec 15 annonces d'emploi et leur description intégrée.

Écrire le code SQL d'amorçage

Nous allons créer un fichier nommé seed.sql dans l'éditeur Cloud Shell avec le contenu de la fiche de poste. Cela crée la table jobs avec la prise en charge de pgvector et insère 15 offres d'emploi dans des entreprises technologiques.

Commencez par créer le fichier seed.sql à l'aide de la commande suivante :

cloudshell edit seed.sql

Copiez ensuite ces scripts dans le fichier.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Le script d'amorçage 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 jobs_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.

La colonne description_embedding est vector(3072), c'est-à-dire une colonne pgvector qui stocke des vecteurs de dimension 3 072. Pour l'instant, il est défini sur NULL. Vous générerez et renseignerez les embeddings à l'étape suivante à l'aide de la fonction embedding().

Terminer la configuration de la base de données

La création de l'instance Cloud SQL que vous avez lancée à l'étape précédente peut être toujours en cours. Vérifiez que l'instance est prête :

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

Vous devriez obtenir le résultat suivant :

RUNNABLE

Ensuite, accordez au compte de service de l'instance Cloud SQL l'autorisation d'appeler Vertex AI. Cela est nécessaire pour la fonction embedding() intégrée que vous utiliserez à l'étape suivante :

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

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

Ensuite, créez une base de données dédiée aux offres d'emploi :

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

Vous devriez voir un message confirmant que la base de données a été créée :

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

Se connecter à la base de données et l'initialiser

Démarrez le proxy d'authentification Cloud SQL (cloud-sql-proxy est préinstallé dans Cloud Shell). Cela permet d'établir une connexion sécurisée et authentifiée entre Cloud Shell et votre instance Cloud SQL :

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

Si le proxy démarre, vous devriez voir ces résultats dans le terminal :

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

Le terminal actuel affiche désormais le journal du proxy Cloud SQL en continu. Ouvrons un nouvel onglet de terminal dans Cloud Shell (cliquez sur l'icône +) pour nous concentrer davantage.

Revenez à votre répertoire de travail et activez le projet à l'aide du script de configuration précédent.

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

Exécutez ensuite le script de seed.

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

Le résultat du terminal doit ressembler à ceci :

CREATE EXTENSION
CREATE EXTENSION
CREATE TABLE
INSERT 0 15

Vérifions les données

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

Vous devriez voir 15 offres d'emploi pour différents postes :

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

Générer des embeddings pour les descriptions de poste

La colonne description_embedding de la table jobs est actuellement définie sur NULL. L'extension google_ml_integration intégrée à Cloud SQL fournit une fonction embedding() qui appelle Vertex AI directement depuis SQL. Aucun script Python ni SDK externe n'est nécessaire.

Démarrez la génération d'embeddings en arrière-plan. Cela appelle Vertex AI pour générer un vecteur de 3 072 dimensions à l'aide du modèle gemini-embedding-001 pour chacune des 15 descriptions de poste :

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

Voici ce que fait le script :

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 3 072 dimensions par description de poste.
& exécute la commande en arrière-plan pour que vous puissiez continuer à travailler pendant que Vertex AI traite les embeddings.

Comme pour l'exécution des processus en arrière-plan précédents, le terminal actuel affichera le journal du processus. Ouvrons un nouvel onglet de terminal dans Cloud Shell (cliquez sur l'icône +) pour nous concentrer davantage.

Revenez à votre répertoire de travail et activez le projet à l'aide du script de configuration précédent.

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

Nous pourrons ensuite passer à la procédure suivante.

6. 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 ?

Le 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. Tout 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 l'injection 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. Modifier une requête signifie redéployer l'agent.

Avec Toolbox, vous écrivez un fichier YAML. Chaque outil correspond à une instruction SQL paramétrée. Toolbox 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 : mettez à 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 possède 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: sources
name: jobs-db
type: cloud-sql-postgres
project: ${GOOGLE_CLOUD_PROJECT}
region: ${REGION}
instance: jobs-instance
database: jobs_db
user: postgres
password: ${DB_PASSWORD}

---