Créer un agent de voyage à l'aide de MCP Toolbox for Databases et du kit de développement d'agents
À propos de cet atelier de programmation
1. Introduction
Dans cet atelier de programmation, vous allez créer un agent à l'aide du kit de développement d'agents (ADK) qui utilise la boîte à outils MCP pour les bases de données.
Au cours de l'atelier de programmation, vous allez suivre une approche par étapes, comme suit:
- 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.
- Concevoir et développer un agent à l'aide du kit de développement d'agents (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 une zone géographique ou qui recherchera des hôtels par nom.
Points abordés
- Provisionnement et remplissage d'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.
- Concevoir et développer un agent à l'aide de l'Agent Development Kit (ADK) pour répondre aux requêtes des utilisateurs
- Tester 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 application exemple. Toutefois, vous n'avez pas besoin de connaître Python pour 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 avec 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. Veuillez 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 l'exécution de la commande aboutit, un message semblable à celui ci-dessous s'affiche:
Operation "operations/..." finished successfully.
Vous pouvez également rechercher chaque produit dans la console ou utiliser ce lien.
Si une API est manquante, vous pouvez toujours l'activer 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 les données de nos 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 \
--cpu=2 \
--memory=8GiB \
--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 s'affiche, ainsi que des informations sur votre instance Cloud SQL, telles que NAME, DATABASE_VERSION, LOCATION, etc.
4. Préparer la base de données des 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 que hoteldb-instance est prêt et créé. Cliquez sur le nom de l'instance (hoteldb-instance), comme illustré ci-dessous:
Dans le menu de gauche de Cloud SQL, accédez à l'option de menu Cloud SQL Studio, comme illustré ci-dessous:
Vous serez alors 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". Pour "Utilisateur" et "Mot de passe", la valeur à utiliser est postgres. Cliquez sur AUTHENTICATE.
Commençons par créer la table des hôtels conformément au schéma ci-dessous. Dans l'un des volets de l'éditeur de Cloud SQL Studio, exécutez l'instruction SQL suivante:
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 "hôtels" 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-22', '2024-04-20', 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-24', '2024-04-05', B'0'),
(5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'),
(6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'),
(7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'),
(8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', 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 instruction SQL SELECT, comme indiqué ci-dessous:
SELECT * FROM hotels;
Un certain nombre d'enregistrements doivent s'afficher dans le tableau des hôtels, comme indiqué ci-dessous:
Nous avons terminé de configurer une instance Cloud SQL et avons créé nos exemples de données. Dans la section suivante, nous allons configurer la 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 répondre aux exigences de qualité de production et d'entreprise. 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 pool 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. Toolbox 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 prise en charge intégrée d'OpenTelemetry.
La boîte à outils se situe entre le framework d'orchestration de votre application et votre base de données. Elle fournit un plan de contrôle qui permet de modifier, de distribuer ou d'invoquer 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 les partager entre les agents et les applications, et les mettre à jour sans avoir à redéployer votre application.
Vous pouvez voir que Cloud SQL est l'une des bases de données compatibles avec la boîte à outils MCP pour les bases de données. 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 la MCP Toolbox for Databases à l'aide du script ci-dessous:
export VERSION=0.3.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
La version binaire de la boîte à outils est maintenant prête à être utilisée. L'étape suivante consiste à configurer la boîte à outils avec nos sources de données et d'autres configurations.
Configurer tools.yaml
La principale méthode de configuration de Toolbox consiste à utiliser le fichier tools.yaml. Créez un fichier nommé tools.yaml dans le même dossier (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.
parameters:
- name: location
type: string
description: The location of the hotel.
statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%';
toolsets:
my_first_toolset:
- search-hotels-by-name
- search-hotels-by-location
Voyons brièvement le fichier:
Sourcesreprésente 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éfinirSourcescomme une carte 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.- Les
Toolsdéfinissent les actions qu'un agent peut effectuer, telles que la lecture et l'écriture dans une source. Un outil représente une action que votre agent peut effectuer, comme exécuter une instruction SQL. Vous pouvez définirToolscomme une carte dans la section "tools" de votre fichier tools.yaml. En règle générale, un outil nécessite une source sur laquelle agir. Dans notre cas, nous définissons deux outils:search-hotels-by-nameetsearch-hotels-by-location, et 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 n'avons qu'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 une sortie indiquant que le serveur a pu se connecter à nos sources de données et a chargé l'ensemble d'outils. Voici un exemple de sortie:
./toolbox --tools-file "tools.yaml"
2025-04-23T14:32:29.564903079Z INFO "Initialized 1 sources."
2025-04-23T14:32:29.565009291Z INFO "Initialized 0 authServices."
2025-04-23T14:32:29.565070176Z INFO "Initialized 2 tools."
2025-04-23T14:32:29.565120847Z INFO "Initialized 2 toolsets."
2025-04-23T14:32:29.565510068Z INFO "Server ready to serve!"
Le serveur MCP Toolbox s'exécute par défaut sur le port 5000. Utilisons Cloud Shell pour le tester.
Cliquez sur "Aperçu sur le Web" dans Cloud Shell, comme illustré ci-dessous:
Cliquez sur Change port (Modifier le port), définissez le port sur 5000, comme indiqué ci-dessous, puis cliquez 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 sortie:
{
"serverVersion": "0.3.0+container.12222fe27ae070f2689a0632d60fda45412d1f97",
"tools": {
"search-hotels-by-location": {
"description": "Search for hotels based on location.",
"parameters": [
{
"name": "location",
"type": "string",
"description": "The location of the hotel.",
"authSources": []
}
]
},
"search-hotels-by-name": {
"description": "Search for hotels based on name.",
"parameters": [
{
"name": "name",
"type": "string",
"description": "The name of the hotel.",
"authSources": []
}
]
}
}
}
MCP Toolbox for Databases décrit une méthode Python pour valider et tester les outils, qui est documentée ici. Nous allons passer directement à l'Agent Development Kit (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
Créons maintenant 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 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:
--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 échafaudage pour notre application d'agent d'hôtel via la commande create adk avec un nom d'application **(hotel-agent-app)**, comme indiqué ci-dessous.
adk create hotel-agent-app
Suivez les étapes ci-dessous et sélectionnez les éléments suivants:
- Modèle Gemini pour choisir un modèle pour l'agent racine.
- Choisissez Vertex AI pour le backend.
- Votre ID de projet Google et votre région par défaut s'affichent. Sélectionnez la valeur par défaut.
Choose a model for the root agent:
1. gemini-2.0-flash-001
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 [gcp-experiments-349209]:
Enter Google Cloud region [us-central1]:
Agent created in /home/romin/hotel-agent-app:
- .env
- __init__.py
- agent.py
Examinez 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. dont le contenu est indiqué 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 utiliserons Gemini via Vertex AI, ainsi que les valeurs respectives pour l'ID et l'emplacement du projet Google Cloud.
Le fichier __init__.py marque le dossier comme un module et 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 affiché ci-dessous:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.0-flash-001',
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 pouvez écrire avec l'ADK. D'après la page de la documentation de l'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, communément 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 de la marche à suivre ou des 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.0-flash-001',
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 d'être dans le dossier parent (my-agents) contenant le dossier hotel-agent-app.
adk web
Voici un exemple d'exécution:
INFO: Started server process [5015]
INFO: Waiting for application startup.
+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at http://localhost:8000. |
+-----------------------------------------------------------------------------+
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
Cliquez sur le dernier lien. Une console Web s'affichera pour vous permettre de tester l'agent. L'application suivante devrait s'ouvrir dans le navigateur, comme indiqué ci-dessous:
Notez que l'application hotel-agent a été identifiée en haut à gauche. Vous pouvez maintenant commencer à discuter avec l'agent. Fournissez quelques requêtes concernant les 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, comme indiqué 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
Nous savons maintenant comment écrire un agent et le tester en local. Nous allons connecter cet agent à "Outils". Dans le contexte d'ADK, un outil représente une capacité spécifique fournie à un agent d'IA, ce qui lui permet 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 des outils que nous avons configurés dans MCP Toolbox for Databases.
Modifiez le fichier agent.py avec le code suivant:
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.0-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 extrait des 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, procédez comme suit:
Dans un terminal de Cloud Shell, lancez la MCP Toolbox for Databases. Il est possible que vous l'exécutiez déjà 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 une sortie indiquant que le serveur a pu se connecter à nos sources de données et a chargé l'ensemble d'outils. Voici un exemple de sortie:
./toolbox --tools-file "tools.yaml"
2025-04-23T14:32:29.564903079Z INFO "Initialized 1 sources."
2025-04-23T14:32:29.565009291Z INFO "Initialized 0 authServices."
2025-04-23T14:32:29.565070176Z INFO "Initialized 2 tools."
2025-04-23T14:32:29.565120847Z INFO "Initialized 2 toolsets."
2025-04-23T14:32:29.565510068Z 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 du kit de développement d'agents (ADK), sont maintenant terminés. Il était alimenté par des outils que nous avons configurés dans MCP Toolbox for Databases.
8. (Facultatif) Déployer MCP Toolbox for Databases et l'agent dans 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'exécutait localement dans l'environnement Cloud Shell.
Vous pouvez déployer à la fois le serveur MCP Toolbox et l'Agent sur des services Google Cloud pouvant héberger ces applications pour nous.
Héberger le serveur MCP Toolbox sur Cloud Run
Commençons par le serveur de la boîte à outils MCP et hébergeons-le sur Cloud Run. Nous disposerons alors d'un point de terminaison public que nous pourrons intégrer à n'importe quelle autre application et/ou aux applications de l'agent. Pour savoir comment l'héberger sur Cloud Run, cliquez ici. Nous allons maintenant passer en revue les étapes clés.
Lancez un nouveau terminal Cloud Shell ou utilisez un terminal Cloud Shell existant. Accédez au dossier mcp-toolbox, dans lequel se trouvent les binaires toolbox et tools.yaml.
Exécutez les commandes suivantes (une explication est fournie pour chaque commande):
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"
Vérifiez ensuite 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é au 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 familière vers 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
Le processus de déploiement du serveur Toolbox avec notre tools.yaml configuré dans Cloud Run devrait démarrer. Si le déploiement réussit, un message semblable au suivant 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 à 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 consulter les outils disponibles:
SERVICE URL/api/toolset
Vous pouvez également accéder à Cloud Run depuis la console Google Cloud. Le service Toolbox s'affichera alors dans la liste des services de Cloud Run.
Remarque: Si vous souhaitez continuer à exécuter votre agent d'hôtel en local tout en vous connectant au nouveau service Cloud Run, vous devez simplement 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 de l'agent à l'aide de adk run ou de adk web, comme nous l'avons vu précédemment.
Déployer l'application de l'agent d'hôtel sur Cloud Run
La première étape consiste à vous assurer que vous avez effectué la modification dans my-agents/hotel-agent-app/agent.py comme indiqué ci-dessus pour qu'elle pointe vers l'URL du service Toolbox exécuté sur Cloud Run et non vers l'hôte local.
Dans un nouveau 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 commençons par définir 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 de l'agent sur Cloud Run à l'aide de la commande cloud_run adk deploy, comme indiqué ci-dessous. Si vous êtes invité à autoriser les appels non authentifiés au service, veuillez indiquer "y" comme valeur 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 de l'agent d'hôtel dans Cloud Run commence. Il importe les sources, les empaquette dans un conteneur Docker, les transfère vers Artifact Registry, puis déploie le service sur Cloud Run. Cette opération peut prendre quelques minutes. Veuillez patienter.
Un message semblable à celui-ci doit s'afficher:
Start generating Cloud Run source files in /tmp/cloud_run_deploy_src/20250424_045623
Copying agent source code...
Copying agent source code complete.
Creating Dockerfile...
Creating Dockerfile complete: /tmp/cloud_run_deploy_src/20250424_045623/Dockerfile
Deploying to Cloud Run...
Building using Dockerfile and deploying container to Cloud Run service [hotels-service] in project [YOUR_GOOGLE_CLOUD_PROJECT] region [us-central1]
| Building and deploying... Uploading sources.
| Uploading sources...
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/b02f5a74-6da6-4367-aaba-0c8aa098edf5?project=415458962931].
OK Creating Revision...
OK Routing traffic...
Done.
Service [hotels-service] revision [hotels-service-00002-cpm] has been deployed and is serving 100 percent of traffic.
Service URL: https://hotels-service-<SOME_ID>.us-central1.run.app
Cleaning up the temp folder: /tmp/cloud_run_deploy_src/20250424_045623
Une fois le déploiement terminé, vous recevrez une valeur pour l'URL du service, à laquelle vous pourrez 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 lors de la configuration locale.
9. Félicitations
Félicitations, vous avez créé un agent à l'aide du kit de développement d'agents (ADK) qui utilise MCP Toolbox for Databases.