1. Introduction
Dans cet atelier de programmation, vous allez créer un agent à l'aide de l'Agent Development Kit (ADK) qui utilise la MCP Toolbox for Databases.
Dans cet atelier de programmation, vous allez suivre une approche par étapes :
- Provisionnez une base de données Cloud SQL pour PostgreSQL qui contiendra la base de données des hôtels et des exemples de données.
- Configurez MCP Toolbox for Databases, qui permet d'accéder aux données.
- Concevez et développez un agent à l'aide d'Agent Development Kit (ADK) qui utilisera la boîte à outils MCP pour répondre aux requêtes de l'utilisateur.
- Découvrez les options permettant de tester l'agent et la boîte à outils MCP pour les bases de données en local et sur Google Cloud via le service Cloud Run.
Objectifs de l'atelier
- Concevez, créez et déployez un agent qui répondra aux requêtes des utilisateurs sur les hôtels dans un lieu donné ou qui recherchera des hôtels par nom.
Points abordés
- Provisionner et remplir une base de données Cloud SQL pour PostgreSQL avec des exemples de données.
- Configurez la boîte à outils MCP pour les bases de données pour l'instance de base de données Cloud SQL pour PostgreSQL.
- Concevez et développez un agent à l'aide d'Agent Development Kit (ADK) pour répondre aux requêtes des utilisateurs.
- Testez l'agent et MCP Toolbox for Databases dans l'environnement local.
- (Facultatif) Déployez l'agent et MCP Toolbox for Databases dans Google Cloud.
Prérequis
- Navigateur Web Chrome
- Un compte Gmail
- Un projet Cloud pour lequel la facturation est activée
Cet atelier de programmation, conçu pour les développeurs de tous niveaux (y compris les débutants), utilise Python dans son exemple d'application. Toutefois, la connaissance de Python n'est pas requise. Une capacité de lecture de code de base suffira à comprendre les concepts présentés.
2. Avant de commencer
Créer un projet
- Dans la console Google Cloud, sur la page du sélecteur de projet, sélectionnez ou créez un projet Google Cloud.
- Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier si la facturation est activée sur un projet .
- Vous allez utiliser Cloud Shell, un environnement de ligne de commande exécuté dans Google Cloud et fourni avec bq. Cliquez sur "Activer Cloud Shell" en haut de la console Google Cloud.
- Une fois connecté à Cloud Shell, vérifiez que vous êtes déjà authentifié et que le projet est défini sur votre ID de projet à l'aide de la commande suivante :
gcloud auth list
- Exécutez la commande suivante dans Cloud Shell pour vérifier que la commande gcloud connaît votre projet.
gcloud config list project
- Si votre projet n'est pas défini, utilisez la commande suivante pour le définir :
gcloud config set project <YOUR_PROJECT_ID>
- Activez les API requises à l'aide de la commande ci-dessous. Cette opération peut prendre quelques minutes. Merci de patienter.
gcloud services enable cloudresourcemanager.googleapis.com \
servicenetworking.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
cloudfunctions.googleapis.com \
aiplatform.googleapis.com \
sqladmin.googleapis.com \
compute.googleapis.com
Si la commande s'exécute correctement, un message semblable à celui ci-dessous s'affiche :
Operation "operations/..." finished successfully.
Vous pouvez également utiliser la console au lieu de la commande gcloud. Pour ce faire, recherchez chaque produit ou utilisez ce lien.
Si vous oubliez d'activer une API, vous pourrez toujours le faire au cours de l'implémentation.
Consultez la documentation pour connaître les commandes gcloud ainsi que leur utilisation.
3. Créer une instance Cloud SQL
Nous allons utiliser une instance Google Cloud SQL pour PostgreSQL pour stocker nos données d'hôtels. Cloud SQL pour PostgreSQL est un service de base de données entièrement géré qui vous aide à configurer, maintenir, gérer et administrer vos bases de données relationnelles PostgreSQL sur Google Cloud Platform.
Exécutez la commande suivante dans Cloud Shell pour créer l'instance :
gcloud sql instances create hoteldb-instance \
--database-version=POSTGRES_15 \
--tier db-g1-small \
--region=us-central1 \
--edition=ENTERPRISE \
--root-password=postgres
L'exécution de cette commande prend environ trois à cinq minutes. Une fois la commande exécutée, un résultat indiquant qu'elle est terminée doit s'afficher, ainsi que les informations sur votre instance Cloud SQL, comme NAME, DATABASE_VERSION, LOCATION, etc.
4. Préparer la base de données Hôtels
Notre tâche consiste maintenant à créer des exemples de données pour notre agent d'hôtel.
Accédez à la page Cloud SQL de la console Cloud.Vous devriez voir l'instance hoteldb-instance prête et créée. Cliquez sur le nom de l'instance (hoteldb-instance) comme indiqué ci-dessous :
Dans le menu de gauche de Cloud SQL, accédez à l'option de menu Cloud SQL Studio, comme indiqué ci-dessous :
Vous serez invité à vous connecter à Cloud SQL Studio, via lequel nous allons exécuter quelques commandes SQL. Sélectionnez postgres pour l'option "Base de données", et postgres pour les options "Utilisateur" et "Mot de passe". Cliquez sur AUTHENTICATE.
Commençons par créer la table "hotel" selon le schéma ci-dessous. Dans l'un des volets de l'éditeur de Cloud SQL Studio, exécutez le code SQL suivant :
CREATE TABLE hotels(
id INTEGER NOT NULL PRIMARY KEY,
name VARCHAR NOT NULL,
location VARCHAR NOT NULL,
price_tier VARCHAR NOT NULL,
checkin_date DATE NOT NULL,
checkout_date DATE NOT NULL,
booked BIT NOT NULL
);
Remplissons maintenant la table "hotels" avec des exemples de données. Exécutez le code SQL suivant :
INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked)
VALUES
(1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-20', '2024-04-22', B'0'),
(2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'),
(3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'),
(4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-05', '2024-04-24', B'0'),
(5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-01', '2024-04-23', B'0'),
(6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'),
(7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-02', '2024-04-27', B'0'),
(8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-09', '2024-04-24', B'0'),
(9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'),
(10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0');
Validons les données en exécutant une requête SQL SELECT comme indiqué ci-dessous :
SELECT * FROM hotels;
Vous devriez voir un certain nombre d'enregistrements dans le tableau "hotels", comme indiqué ci-dessous :
Nous avons terminé de configurer une instance Cloud SQL et créé nos exemples de données. Dans la section suivante, nous allons configurer MCP Toolbox for Databases.
5. Configurer MCP Toolbox for Databases
MCP Toolbox for Databases est un serveur MCP Open Source pour les bases de données. Il a été conçu pour les entreprises et la production. Il vous permet de développer des outils plus facilement, plus rapidement et de manière plus sécurisée en gérant les complexités telles que le regroupement de connexions, l'authentification, etc.
La boîte à outils vous aide à créer des outils d'IA générative qui permettent à vos agents d'accéder aux données de votre base de données. La boîte à outils fournit les éléments suivants :
- Développement simplifié : intégrez des outils à votre agent en moins de 10 lignes de code, réutilisez des outils entre plusieurs agents ou frameworks, et déployez plus facilement de nouvelles versions d'outils.
- Meilleures performances : bonnes pratiques telles que le regroupement de connexions, l'authentification, etc.
- Sécurité renforcée : authentification intégrée pour un accès plus sécurisé à vos données
- Observabilité de bout en bout : métriques et traçage prêts à l'emploi avec compatibilité intégrée pour OpenTelemetry.
Toolbox se situe entre le framework d'orchestration de votre application et votre base de données. Il fournit un plan de contrôle utilisé pour modifier, distribuer ou appeler des outils. Il simplifie la gestion de vos outils en vous fournissant un emplacement centralisé pour les stocker et les mettre à jour. Vous pouvez ainsi partager des outils entre les agents et les applications, et les mettre à jour sans nécessairement redéployer votre application.
Vous pouvez constater que Cloud SQL est l'une des bases de données compatibles avec MCP Toolbox for Databases. Nous l'avons provisionnée dans la section précédente.
Installer la boîte à outils
Ouvrez le terminal Cloud Shell et créez un dossier nommé mcp-toolbox.
mkdir mcp-toolbox
Accédez au dossier mcp-toolbox à l'aide de la commande ci-dessous :
cd mcp-toolbox
Installez la version binaire de MCP Toolbox for Databases à l'aide du script ci-dessous. La commande ci-dessous est destinée à Linux, mais si vous utilisez Mac ou Windows, assurez-vous de télécharger le bon binaire. Consultez la page des versions pour votre système d'exploitation et votre architecture, puis téléchargez le fichier binaire approprié.
export VERSION=0.13.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
Nous disposons maintenant de la version binaire de la boîte à outils. L'étape suivante consiste à configurer la boîte à outils avec nos sources de données et d'autres configurations.
Configurer tools.yaml
La principale façon de configurer Toolbox est d'utiliser le fichier tools.yaml. Créez un fichier nommé tools.yaml dans le même dossier, c'est-à-dire mcp-toolbox, dont le contenu est indiqué ci-dessous.
Vous pouvez utiliser l'éditeur nano disponible dans Cloud Shell. La commande nano est la suivante : "nano tools.yaml".
N'oubliez pas de remplacer la valeur YOUR_PROJECT_ID par l'ID de votre projet Google Cloud.
sources:
my-cloud-sql-source:
kind: cloud-sql-postgres
project: YOUR_PROJECT_ID
region: us-central1
instance: hoteldb-instance
database: postgres
user: postgres
password: "postgres"
tools:
search-hotels-by-name:
kind: postgres-sql
source: my-cloud-sql-source
description: Search for hotels based on name.
parameters:
- name: name
type: string
description: The name of the hotel.
statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%';
search-hotels-by-location:
kind: postgres-sql
source: my-cloud-sql-source
description: Search for hotels based on location. Result is sorted by price from least to most expensive.
parameters:
- name: location
type: string
description: The location of the hotel.
statement: |
SELECT *
FROM hotels
WHERE location ILIKE '%' || $1 || '%'
ORDER BY
CASE price_tier
WHEN 'Midscale' THEN 1
WHEN 'Upper Midscale' THEN 2
WHEN 'Upscale' THEN 3
WHEN 'Upper Upscale' THEN 4
WHEN 'Luxury' THEN 5
ELSE 99 -- Handle any unexpected values, place them at the end
END;
toolsets:
my_first_toolset:
- search-hotels-by-name
- search-hotels-by-location
Voici une brève présentation du fichier :
Sourcesreprésentent les différentes sources de données avec lesquelles un outil peut interagir. Une source représente une source de données avec laquelle un outil peut interagir. Vous pouvez définirSourcesen tant que mappage dans la section "sources" de votre fichier tools.yaml. En règle générale, une configuration de source contient toutes les informations nécessaires pour se connecter à la base de données et interagir avec elle. Dans notre cas, nous avons configuré une seule source qui pointe vers notre instance Cloud SQL pour PostgreSQL avec les identifiants. Pour en savoir plus, consultez la documentation de référence sur les sources.Toolsdéfinissent les actions qu'un agent peut effectuer, comme lire et écrire dans une source. Un outil représente une action que votre agent peut effectuer, comme exécuter une instruction SQL. Vous pouvez définirToolscomme un mappage dans la section "tools" de votre fichier tools.yaml. En règle générale, un outil a besoin d'une source pour agir. Dans notre cas, nous définissons deux outils :search-hotels-by-nameetsearch-hotels-by-location, et nous spécifions la source sur laquelle ils agissent, ainsi que le code SQL et les paramètres. Pour en savoir plus, consultez la documentation de référence sur les outils.- Enfin, nous avons
Toolset, qui vous permet de définir des groupes d'outils que vous souhaitez pouvoir charger ensemble. Cela peut être utile pour définir différents groupes en fonction de l'agent ou de l'application. Dans notre cas, nous avons un seul ensemble d'outils appelémy_first_toolset, qui contient les deux outils que nous avons définis.
Exécuter le serveur MCP Toolbox for Databases
Exécutez la commande suivante (à partir du dossier mcp-toolbox) pour démarrer le serveur :
./toolbox --tools-file "tools.yaml"
Idéalement, vous devriez voir un résultat indiquant que le serveur a pu se connecter à nos sources de données et a chargé l'ensemble d'outils et les outils. Voici un exemple de résultat :
2025-09-05T12:56:28.490964335Z INFO "Initialized 1 sources."
2025-09-05T12:56:28.491127294Z INFO "Initialized 0 authServices."
2025-09-05T12:56:28.491184521Z INFO "Initialized 2 tools."
2025-09-05T12:56:28.491223782Z INFO "Initialized 2 toolsets."
2025-09-05T12:56:28.497457533Z INFO "Server ready to serve!"
Par défaut, le serveur MCP Toolbox s'exécute sur le port 5000. Si vous constatez que le port 5000 est déjà utilisé, n'hésitez pas à utiliser un autre port (par exemple, 7000) conformément à la commande ci-dessous. Veuillez utiliser 7000 au lieu du port 5000 dans les commandes suivantes.
./toolbox --tools-file "tools.yaml" --port 7000
Utilisons Cloud Shell pour tester cela.
Cliquez sur "Aperçu sur le Web" dans Cloud Shell, comme indiqué ci-dessous :
Cliquez sur Modifier le port, puis définissez le port sur 5000, comme indiqué ci-dessous. Cliquez ensuite sur "Modifier et prévisualiser".
Vous devriez obtenir le résultat suivant :
Dans l'URL du navigateur, ajoutez ce qui suit à la fin de l'URL :
/api/toolset
Les outils actuellement configurés devraient s'afficher. Voici un exemple de résultat :
{
"serverVersion": "0.13.0+binary.linux.amd64.1a6dfe8d37d0f42fb3fd3f75c50988534dbc1b85",
"tools": {
"search-hotels-by-location": {
"description": "Search for hotels based on location. Result is sorted by price from least to most expensive.",
"parameters": [
{
"name": "location",
"type": "string",
"required": true,
"description": "The location of the hotel.",
"authSources": []
}
],
"authRequired": []
},
"search-hotels-by-name": {
"description": "Search for hotels based on name.",
"parameters": [
{
"name": "name",
"type": "string",
"required": true,
"description": "The name of the hotel.",
"authSources": []
}
],
"authRequired": []
}
}
}
Tester les outils via l'UI MCP Toolbox for Databases
La boîte à outils fournit une interface visuelle (UI de la boîte à outils) permettant d'interagir directement avec les outils en modifiant les paramètres, en gérant les en-têtes et en exécutant les appels, le tout dans une interface Web simple.
Si vous souhaitez tester cette fonctionnalité, vous pouvez exécuter la commande précédente que nous avons utilisée pour lancer le serveur Toolbox avec une option --ui.
Pour ce faire, arrêtez l'instance précédente du serveur MCP Toolbox for Databases que vous avez peut-être en cours d'exécution, puis exécutez la commande suivante :
./toolbox --tools-file "tools.yaml" --ui
Idéalement, vous devriez voir un résultat indiquant que le serveur a pu se connecter à nos sources de données et a chargé l'ensemble d'outils et les outils. Vous trouverez ci-dessous un exemple de résultat. Vous remarquerez qu'il indique que l'interface utilisateur de la boîte à outils est opérationnelle.
2025-09-08T02:44:11.561572538Z INFO "Initialized 1 sources."
2025-09-08T02:44:11.561966395Z INFO "Initialized 0 authServices."
2025-09-08T02:44:11.562060934Z INFO "Initialized 2 tools."
2025-09-08T02:44:11.562105678Z INFO "Initialized 2 toolsets."
2025-09-08T02:44:11.568209923Z INFO "Server ready to serve!"
2025-09-08T02:44:11.568259411Z INFO "Toolbox UI is up and running at: http://localhost:5000/ui"
Cliquez sur l'URL de l'UI et assurez-vous que /ui figure à la fin de l'URL. Une interface utilisateur s'affiche, comme illustré ci-dessous :
Cliquez sur l'option "Outils" à gauche pour afficher les outils qui ont été configurés. Dans notre cas, il devrait y en avoir deux, à savoir search-hotels-by-name et search-hotels-by-location, comme indiqué ci-dessous :
Il vous suffit de cliquer sur l'un des outils (search-hotels-by-location) pour afficher une page vous permettant de tester l'outil en fournissant les valeurs de paramètre requises, puis de cliquer sur Exécuter l'outil pour afficher le résultat. Voici un exemple d'exécution :
Le MCP Toolkit for Databases décrit également une méthode Pythonique pour valider et tester les outils, qui est documentée ici. Nous allons passer cette étape et passer directement au kit de développement d'agent (ADK) dans la section suivante, qui utilisera ces outils.
6. Écrire notre agent avec Agent Development Kit (ADK)
Installer l'Agent Development Kit (ADK)
Ouvrez un nouvel onglet de terminal dans Cloud Shell et créez un dossier nommé my-agents comme suit. Accédez également au dossier my-agents.
mkdir my-agents
cd my-agents
Nous allons maintenant créer un environnement Python virtuel à l'aide de venv comme suit :
python -m venv .venv
Activez l'environnement virtuel comme suit :
source .venv/bin/activate
Installez les packages ADK et MCP Toolbox for Databases avec la dépendance langchain comme suit :
pip install google-adk toolbox-core
Vous pouvez désormais appeler l'utilitaire adk comme suit.
adk
Une liste de commandes s'affiche.
$ adk
Usage: adk [OPTIONS] COMMAND [ARGS]...
Agent Development Kit CLI tools.
Options:
--version Show the version and exit.
--help Show this message and exit.
Commands:
api_server Starts a FastAPI server for agents.
create Creates a new app in the current folder with prepopulated agent template.
deploy Deploys agent to hosted environments.
eval Evaluates an agent given the eval sets.
run Runs an interactive CLI for a certain agent.
web Starts a FastAPI server with Web UI for agents.
Créer notre première application d'agent
Nous allons maintenant utiliser adk pour créer un scaffold pour notre application d'agent d'hôtel à l'aide de la commande adk create avec le nom d'application **(hotel-agent-app)**comme indiqué ci-dessous.
adk create hotel-agent-app
Suivez les étapes et sélectionnez les éléments suivants :
- Modèle Gemini permettant de choisir un modèle pour l'agent racine.
- Choisissez Vertex AI pour le backend.
- Votre ID de projet et votre région Google par défaut s'affichent. Sélectionnez la valeur par défaut.
Choose a model for the root agent:
1. gemini-2.5-flash
2. Other models (fill later)
Choose model (1, 2): 1
1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2
You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai
Enter Google Cloud project ID [YOUR_PROJECT_ID]:
Enter Google Cloud region [us-central1]:
Agent created in <YOUR_HOME_FOLDER>/my-agents/hotel-agent-app:
- .env
- __init__.py
- agent.py
Observez le dossier dans lequel un modèle par défaut et les fichiers requis pour l'agent ont été créés.
Commençons par le fichier .env. Le contenu est présenté ci-dessous :
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION
Les valeurs indiquent que nous allons utiliser Gemini via Vertex AI avec les valeurs respectives pour l'ID et l'emplacement du projet Google Cloud.
Ensuite, nous avons le fichier __init__.py qui marque le dossier comme module et qui contient une seule instruction qui importe l'agent à partir du fichier agent.py.
from . import agent
Enfin, examinons le fichier agent.py. Le contenu est présenté ci-dessous :
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.5-flash',
name='root_agent',
description='A helpful assistant for user questions.',
instruction='Answer user questions to the best of your knowledge',
)
Il s'agit de l'agent le plus simple que vous puissiez écrire avec ADK. Sur la page de la documentation ADK, un agent est une unité d'exécution autonome conçue pour agir de manière autonome afin d'atteindre des objectifs spécifiques. Les agents peuvent effectuer des tâches, interagir avec les utilisateurs, utiliser des outils externes et se coordonner avec d'autres agents.
Plus précisément, un LLMAgent, souvent appelé Agent, utilise des grands modèles de langage (LLM) comme moteur principal pour comprendre le langage naturel, raisonner, planifier, générer des réponses et décider de manière dynamique comment procéder ou quels outils utiliser. Il est donc idéal pour les tâches flexibles axées sur le langage. Pour en savoir plus sur les agents LLM, cliquez ici.
Modifions le code de agent.py comme suit :
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.5-flash',
name='hotel_agent',
description='A helpful assistant that answers questions about a specific city.',
instruction='Answer user questions about a specific city to the best of your knowledge. Do not answer questions outside of this.',
)
Tester l'application Agent en local
Dans la fenêtre de terminal existante, exécutez la commande suivante. Assurez-vous de vous trouver dans le dossier parent (my-agents) contenant le dossier hotel-agent-app.
adk web
Voici un exemple d'exécution :
INFO: Started server process [1478]
INFO: Waiting for application startup.
+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at http://127.0.0.1:8000. |
+-----------------------------------------------------------------------------+
INFO: Application startup complete.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
Cliquez sur le dernier lien. Une console Web devrait s'afficher pour vous permettre de tester l'agent. L'écran suivant devrait s'afficher dans le navigateur :
Notez que hotel-agent-app a été identifié en haut à gauche. Vous pouvez maintenant commencer à discuter avec l'agent. Fournissez quelques requêtes sur des villes. Voici un exemple de conversation :
Vous pouvez arrêter le processus en cours d'exécution dans le terminal Cloud Shell (Ctrl+C).
Vous pouvez également tester l'agent à l'aide de la commande adk run ci-dessous, à partir du dossier my-agents.
adk run hotel-agent-app
Essayez la commande et vous pourrez discuter avec l'agent via la ligne de commande (terminal). Saisissez exit pour fermer la conversation.
7. Connecter notre agent à des outils
Maintenant que nous savons comment écrire un agent et le tester en local. Nous allons connecter cet agent aux outils. Dans le contexte de l'ADK, un outil représente une fonctionnalité spécifique fournie à un agent d'IA, lui permettant d'effectuer des actions et d'interagir avec le monde au-delà de ses capacités de génération de texte et de raisonnement de base.
Dans notre cas, nous allons équiper notre agent avec les outils que nous avons configurés dans MCP Toolbox for Databases.
Modifiez le fichier agent.py en ajoutant le code suivant. Notez que nous utilisons le port 5000 par défaut dans le code, mais si vous utilisez un autre numéro de port, veuillez l'utiliser.
from google.adk.agents import Agent
from toolbox_core import ToolboxSyncClient
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
# Load single tool
# tools = toolbox.load_tool('search-hotels-by-location')
# Load all the tools
tools = toolbox.load_toolset('my_first_toolset')
root_agent = Agent(
name="hotel_agent",
model="gemini-2.5-flash",
description=(
"Agent to answer questions about hotels in a city or hotels by name."
),
instruction=(
"You are a helpful agent who can answer user questions about the hotels in a specific city or hotels by name. Use the tools to answer the question"
),
tools=tools,
)
Nous pouvons maintenant tester l'agent qui récupérera les données réelles de notre base de données PostgreSQL configurée avec la boîte à outils MCP pour les bases de données.
Pour ce faire, suivez cette séquence :
Dans un terminal Cloud Shell, lancez MCP Toolbox for Databases. Vous l'avez peut-être déjà exécuté localement sur le port 5000, comme nous l'avons testé précédemment. Si ce n'est pas le cas, exécutez la commande suivante (à partir du dossier mcp-toolbox) pour démarrer le serveur :
./toolbox --tools_file "tools.yaml"
Idéalement, vous devriez voir un résultat indiquant que le serveur a pu se connecter à nos sources de données et a chargé l'ensemble d'outils et les outils. Voici un exemple de résultat :
2025-09-05T12:56:28.490964335Z INFO "Initialized 1 sources."
2025-09-05T12:56:28.491127294Z INFO "Initialized 0 authServices."
2025-09-05T12:56:28.491184521Z INFO "Initialized 2 tools."
2025-09-05T12:56:28.491223782Z INFO "Initialized 2 toolsets."
2025-09-05T12:56:28.497457533Z INFO "Server ready to serve!"
Une fois le serveur MCP démarré, lancez l'agent dans un autre terminal, comme nous l'avons fait précédemment, à l'aide de la commande adk run (à partir du dossier my-agents) indiquée ci-dessous. Vous pouvez également utiliser la commande adk web si vous le souhaitez.
$ adk run hotel-agent-app/
Log setup complete: /tmp/agents_log/agent.20250423_170001.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
Running agent hotel_agent, type exit to exit.
user: what can you do for me?
[hotel_agent]: I can help you find hotels in a specific city or search for hotels by name.
user: I would like to search for hotels
[hotel_agent]: Great, do you have a specific city or hotel name in mind?
user: Yes a specific city
[hotel_agent]: Great, which city are you interested in?
user: Basel
[hotel_agent]: OK. I found three hotels in Basel: Hilton Basel, Hyatt Regency Basel, and Holiday Inn Basel.
Notez que l'agent utilise désormais les deux outils que nous avons configurés dans MCP Toolbox for Databases (search-hotels-by-name et search-hotels-by-location) et nous fournit les options appropriées. Il peut ensuite récupérer facilement les données de la base de données de l'instance PostgreSQL et mettre en forme la réponse en conséquence.
Le développement et les tests locaux de notre agent d'hôtel, que nous avons créé à l'aide de l'Agent Development Kit (ADK) et qui était alimenté par les outils que nous avons configurés dans MCP Toolbox for Databases, sont désormais terminés.
8. (Facultatif) Déployer MCP Toolbox for Databases et l'agent sur Cloud Run
Dans la section précédente, nous avons utilisé le terminal Cloud Shell pour lancer le serveur MCP Toolbox et tester les outils avec l'agent. Cette opération s'est exécutée localement dans l'environnement Cloud Shell.
Vous avez la possibilité de déployer à la fois le serveur MCP Toolbox et l'agent sur les services Google Cloud qui peuvent héberger ces applications pour nous.
Héberger le serveur MCP Toolbox sur Cloud Run
Pour commencer, nous pouvons démarrer le serveur MCP Toolbox et l'héberger sur Cloud Run. Nous obtiendrons ainsi un point de terminaison public que nous pourrons intégrer à n'importe quelle autre application et/ou aux applications Agent. Les instructions pour héberger ce service sur Cloud Run sont disponibles ici. Nous allons maintenant passer en revue les étapes clés.
Lancez un terminal Cloud Shell ou utilisez-en un existant. Accédez au dossier mcp-toolbox, dans lequel se trouvent le binaire toolbox et tools.yaml.
Exécutez les commandes suivantes (une explication est fournie pour chacune d'elles) :
Définissez la variable PROJECT_ID pour qu'elle pointe vers l'ID de votre projet Google Cloud.
export PROJECT_ID="YOUR_GOOGLE_CLOUD_PROJECT_ID"
Ensuite, vérifiez que les services Google Cloud suivants sont activés dans le projet.
gcloud services enable run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
iam.googleapis.com \
secretmanager.googleapis.com
Créons un compte de service distinct qui servira d'identité pour le service Toolbox que nous allons déployer sur Google Cloud Run. Nous nous assurons également que ce compte de service dispose des rôles appropriés, c'est-à-dire qu'il peut accéder à Secret Manager et communiquer avec Cloud SQL.
gcloud iam service-accounts create toolbox-identity
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
--role roles/secretmanager.secretAccessor
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
--role roles/cloudsql.client
Nous allons importer le fichier tools.yaml en tant que secret. Comme nous devons installer la boîte à outils dans Cloud Run, nous allons utiliser la dernière image de conteneur pour la boîte à outils et la définir dans la variable IMAGE.
gcloud secrets create tools --data-file=tools.yaml
export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest
Dernière étape de la commande de déploiement habituelle sur Cloud Run :
gcloud run deploy toolbox \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools:latest" \
--args="--tools_file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--allow-unauthenticated
Cela devrait lancer le processus de déploiement du serveur Toolbox avec notre tools.yaml configuré sur Cloud Run. Si le déploiement réussit, un message semblable à celui-ci s'affiche :
Deploying container to Cloud Run service [toolbox] in project [YOUR_PROJECT_ID] region [us-central1]
OK Deploying new service... Done.
OK Creating Revision...
OK Routing traffic...
OK Setting IAM Policy...
Done.
Service [toolbox] revision [toolbox-00001-zsk] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-<SOME_ID>.us-central1.run.app
Vous pouvez désormais accéder à l'Service URL listé ci-dessus dans le navigateur. Le message "Hello World" que nous avons vu précédemment doit s'afficher. Vous pouvez également accéder à l'URL suivante pour voir les outils disponibles :
SERVICE URL/api/toolset
Vous pouvez également accéder à Cloud Run depuis la console Google Cloud. Le service Toolbox sera disponible dans la liste des services Cloud Run.
Remarque : Si vous souhaitez continuer à exécuter votre agent d'hôtel en local tout en vous connectant au service Cloud Run nouvellement déployé, il vous suffit d'apporter une modification au fichier my-agents/hotel-agent-app/agent.py.
Au lieu de :
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
Remplacez-la par l'URL du service Cloud Run, comme indiqué ci-dessous :
toolbox = ToolboxSyncClient("CLOUD_RUN_SERVICE_URL")
Testez l'application Agent à l'aide de adk run ou adk web, comme nous l'avons vu précédemment.
Déployer l'application Hotel Agent sur Cloud Run
La première étape consiste à vous assurer d'avoir apporté la modification dans my-agents/hotel-agent-app/agent.py, comme indiqué ci-dessus, pour pointer vers l'URL du service Toolbox qui s'exécute sur Cloud Run et non sur l'hôte local.
Dans une nouvelle session de terminal Cloud Shell ou une session de terminal existante, assurez-vous d'être dans l'environnement virtuel Python que nous avons configuré précédemment.
Commençons par créer un fichier requirements.txt dans le dossier my-agents/hotel-agent-app, comme indiqué ci-dessous :
google-adk
toolbox-core
Accédez au dossier my-agents et définissez d'abord les variables d'environnement suivantes :
export GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_CLOUD_PROJECT_ID
export GOOGLE_CLOUD_LOCATION=us-central1
export AGENT_PATH="hotel-agent-app/"
export SERVICE_NAME="hotels-service"
export APP_NAME="hotels-app"
export GOOGLE_GENAI_USE_VERTEXAI=True
Enfin, déployons l'application d'agent sur Cloud Run à l'aide de la commande adk deploy cloud_run comme indiqué ci-dessous. Si vous êtes invité à autoriser les appels non authentifiés au service, veuillez indiquer "y" pour le moment.
adk deploy cloud_run \
--project=$GOOGLE_CLOUD_PROJECT \
--region=$GOOGLE_CLOUD_LOCATION \
--service_name=$SERVICE_NAME \
--app_name=$APP_NAME \
--with_ui \
$AGENT_PATH
Le processus de déploiement de l'application Hotel Agent sur Cloud Run commencera. Il importera les sources, les empaquettera dans un conteneur Docker, les transférera vers Artifact Registry, puis déploiera le service sur Cloud Run. Cette opération peut prendre quelques minutes. Merci de patienter.
Un message semblable à celui-ci doit s'afficher :
Start generating Cloud Run source files in /tmp/cloud_run_deploy_src/20250905_132636
Copying agent source code...
Copying agent source code completed.
Creating Dockerfile...
Creating Dockerfile complete: /tmp/cloud_run_deploy_src/20250905_132636/Dockerfile
Deploying to Cloud Run...
Building using Dockerfile and deploying container to Cloud Run service [hotels-service] in project [YOUR_PROJECT_ID] region [us-central1]
- Building and deploying... Uploading sources.
- Uploading sources...
. Building Container...
OK Building and deploying... Done.
OK Uploading sources...
OK Building Container... Logs are available at [https://console.cloud.google.com/cloud-build/builds;region=us-central1/d1f7e76b-0587-4bb6-b9c0-bb4360c07aa0?project=415
458962931]. f
OK Creating Revision...
OK Routing traffic...
Done.
Service [hotels-service] revision [hotels-service-00003-hrl] has been deployed and is serving 100 percent of traffic.
Service URL: <YOUR_CLOUDRUN_APP_URL>
INFO: Display format: "none"
Cleaning up the temp folder: /tmp/cloud_run_deploy_src/20250905_132636
Une fois le déploiement réussi, une valeur vous sera fournie pour l'URL du service. Vous pourrez ensuite y accéder dans le navigateur pour afficher la même application Web qui vous a permis de discuter avec l'agent de l'hôtel, comme nous l'avons vu précédemment dans la configuration locale.
9. Nettoyage
Pour éviter que des frais ne soient facturés en permanence sur votre compte Google Cloud, il est important de supprimer les ressources que nous avons créées lors de cet atelier. Nous allons supprimer l'instance Cloud SQL et, si vous avez déployé l'application Toolbox et Hotels sur Cloud Run, nous supprimerons également ces services.
Assurez-vous que les variables d'environnement suivantes sont correctement définies, en fonction de votre projet et de votre région :
export PROJECT_ID="YOUR_PROJECT_ID"
export REGION="YOUR_REGION"
Les deux commandes suivantes suppriment les services Cloud Run que nous avons déployés :
gcloud run services delete toolbox --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet
gcloud run services delete hotels-service --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet
La commande suivante supprime l'instance Cloud SQL :
gcloud sql instances delete hoteldb-instance
10. Félicitations
Félicitations, vous avez réussi à créer un agent à l'aide de l'Agent Development Kit (ADK) qui utilise MCP Toolbox for Databases.