GENAI124

Présentation

Dans cet atelier, vous allez découvrir Model Context Protocol (MCP), une norme ouverte qui permet d'intégrer de façon transparente des services, des sources de données, des outils et des applications externes. Vous allez apprendre à intégrer MCP à vos agents Agent Development Kit (ADK) en utilisant les outils fournis par les serveurs MCP existants pour améliorer vos workflows ADK. Vous découvrirez également comment exposer des outils ADK tels que load_web_page à l'aide d'un serveur MCP personnalisé, ce qui permet une intégration plus large avec les clients MCP.

Qu'est-ce que le protocole MCP (Model Context Protocol) ?

Le protocole MCP (Model Context Protocol) est une norme ouverte conçue pour standardiser la façon dont les grands modèles de langage (LLM) comme Gemini et Claude communiquent avec des applications, des sources de données et des outils externes. Considérez-le comme un mécanisme de connexion universel qui simplifie la façon dont les LLM obtiennent du contexte, exécutent des actions et interagissent avec divers systèmes.

MCP suit une architecture client-serveur, qui définit la façon dont les données (ressources), les modèles interactifs (prompts) et les fonctions exploitables (outils) sont exposés par un serveur MCP et consommés par un client MCP (qui peut être une application hôte LLM ou un agent IA).

Cet atelier aborde deux principaux modèles d'intégration :

• Utiliser des serveurs MCP existants dans ADK : un agent ADK agit en tant que client MCP, en exploitant les outils fournis par des serveurs MCP externes.
• Exposer les outils ADK à l'aide d'un serveur MCP : créer un serveur MCP qui encapsule les outils ADK, ce qui les rend accessibles à n'importe quel client MCP.

Objectifs

Dans cet atelier, vous allez apprendre à effectuer les tâches suivantes :

• utiliser un agent ADK en tant que client MCP pour interagir avec les outils des serveurs MCP existants ;
• configurer et déployer votre propre serveur MCP pour exposer les outils ADK à d'autres clients ;
• connecter les agents ADK à des outils externes grâce à une communication MCP standardisée ;
• permettre une interaction fluide entre les LLM et les outils à l'aide de MCP.

Préparation

Avant de cliquer sur le bouton "Démarrer l'atelier"

Lisez ces instructions. Les ateliers sont minutés, et vous ne pouvez pas les mettre en pause. Le minuteur, qui démarre lorsque vous cliquez sur Démarrer l'atelier, indique combien de temps les ressources Google Cloud resteront accessibles.

Cet atelier pratique vous permet de suivre les activités dans un véritable environnement cloud, et non dans un environnement de simulation ou de démonstration. Des identifiants temporaires vous sont fournis pour vous permettre de vous connecter à Google Cloud le temps de l'atelier.

Pour réaliser cet atelier :

• Vous devez avoir accès à un navigateur Internet standard (nous vous recommandons d'utiliser Chrome).

• Vous disposez d'un temps limité. N'oubliez pas qu'une fois l'atelier commencé, vous ne pouvez pas le mettre en pause.

Démarrer l'atelier et se connecter à la console Google Cloud

1. Cliquez sur le bouton Démarrer l'atelier. Si l'atelier est payant, une boîte de dialogue s'affiche pour vous permettre de sélectionner un mode de paiement. Sur la gauche, vous trouverez le panneau "Détails concernant l'atelier", qui contient les éléments suivants :

   • Le bouton "Ouvrir la console Google Cloud"
   • Le temps restant
   • Les identifiants temporaires que vous devez utiliser pour cet atelier
   • Des informations complémentaires vous permettant d'effectuer l'atelier

2. Cliquez sur Ouvrir la console Google Cloud (ou effectuez un clic droit et sélectionnez Ouvrir le lien dans la fenêtre de navigation privée si vous utilisez le navigateur Chrome).

   L'atelier lance les ressources, puis ouvre la page "Se connecter" dans un nouvel onglet.

   Conseil : Réorganisez les onglets dans des fenêtres distinctes, placées côte à côte.

   Remarque : Si la boîte de dialogue Sélectionner un compte s'affiche, cliquez sur Utiliser un autre compte.

3. Si nécessaire, copiez le nom d'utilisateur ci-dessous et collez-le dans la boîte de dialogue Se connecter.

   {{{user_0.username | "Username"}}}

   Vous trouverez également le nom d'utilisateur dans le panneau "Détails concernant l'atelier".

4. Cliquez sur Suivant.

5. Copiez le mot de passe ci-dessous et collez-le dans la boîte de dialogue Bienvenue.

   {{{user_0.password | "Password"}}}

   Vous trouverez également le mot de passe dans le panneau "Détails concernant l'atelier".

6. Cliquez sur Suivant.

   Important : Vous devez utiliser les identifiants fournis pour l'atelier. Ne saisissez pas ceux de votre compte Google Cloud. Remarque : Si vous utilisez votre propre compte Google Cloud pour cet atelier, des frais supplémentaires peuvent vous être facturés.

7. Accédez aux pages suivantes :

   • Acceptez les conditions d'utilisation.
   • N'ajoutez pas d'options de récupération ni d'authentification à deux facteurs (ce compte est temporaire).
   • Ne vous inscrivez pas à des essais sans frais.

Après quelques instants, la console Cloud s'ouvre dans cet onglet.

Remarque : Pour accéder aux produits et services Google Cloud, cliquez sur le menu de navigation ou saisissez le nom du service ou du produit dans le champ Recherche.

Tâche 1 : Installer l'ADK et configurer votre environnement

Dans cet environnement d'atelier, l'API Vertex AI, l'API Routes et l'API Directions ont été activées pour vous.

Préparer un onglet dans l'éditeur Cloud Shell

1. Dans la console Google Cloud, cliquez sur le bouton Activer Cloud Shell () en haut à droite de la console Cloud.
2. Cliquez sur Continuer.
3. Si vous êtes invité à autoriser Cloud Shell, cliquez sur Autoriser.
4. En haut à droite du panneau du terminal Cloud Shell, cliquez sur le bouton Ouvrir dans une nouvelle fenêtre ().
5. Cliquez sur l'icône Ouvrir l'éditeur () en haut du volet pour afficher les fichiers.
6. En haut du menu de navigation de gauche, cliquez sur l'icône Explorateur () pour ouvrir l'explorateur de fichiers.
7. Cliquez sur le bouton Ouvrir le dossier.
8. Dans la boîte de dialogue "Ouvrir le dossier" qui s'affiche, cliquez sur OK pour sélectionner le dossier de base de votre compte élève.
9. Fermez les éventuels tutoriels ou panneaux Gemini qui s'affichent sur le côté droit de l'écran pour donner plus de place à l'éditeur de code.
10. Pour le reste de cet atelier, vous pouvez utiliser cette fenêtre comme IDE avec l'éditeur Cloud Shell et le terminal Cloud Shell.

Télécharger et installer ADK et les exemples de code pour cet atelier

Dans cette section, vous allez exécuter les commandes suivantes dans le terminal Cloud Shell.

1. Exécutez la commande suivante dans le terminal Cloud Shell pour copier le répertoire du projet depuis Cloud Storage :

   gcloud storage cp -r gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/* .

2. Exécutez les commandes suivantes pour installer l'Agent Development Kit (ADK) et les autres dépendances requises pour exécuter les exemples d'applications :

   export PATH=$PATH:"/home/${USER}/.local/bin" python3 -m pip install google-adk==1.22.1 -r adk_mcp_tools/requirements.txt

Cliquez sur Vérifier ma progression pour valider l'objectif. Installer l'ADK et configurer votre environnement

Tâche 2 : Utiliser le serveur MCP Google Maps avec des agents ADK (ADK en tant que client MCP) dans l'UI de développement ADK

Cette section montre comment intégrer des outils provenant d'un serveur MCP Google Maps externe à vos agents ADK. Il s'agit du modèle d'intégration le plus courant lorsque votre agent ADK doit utiliser des fonctionnalités fournies par un service existant qui expose une interface MCP. Vous verrez comment la classe MCPToolset peut être directement ajoutée à la liste tools de votre agent, ce qui permet une connexion fluide à un serveur MCP, la découverte de ses outils et leur mise à disposition pour votre agent. Ces exemples se concentrent principalement sur les interactions dans l'environnement de développement adk web.

MCPToolset

La classe MCPToolset est le principal mécanisme d'ADK pour l'intégration des outils d'un serveur MCP. Lorsque vous incluez une instance MCPToolset dans la liste tools de votre agent, elle gère automatiquement l'interaction avec le serveur MCP spécifié. Voici comment cela fonctionne :

• Gestion des connexions : lors de l'initialisation, MCPToolset établit et gère la connexion au serveur MCP. Il peut s'agir d'un processus de serveur local (utilisant StdioServerParameters pour la communication via l'entrée/la sortie standard) ou d'un serveur distant (utilisant SseServerParams pour les événements envoyés par le serveur). L'ensemble d'outils gère également l'arrêt progressif de cette connexion lorsque l'agent ou l'application se termine.
• Découverte et adaptation des outils : une fois la connexion établie, MCPToolset interroge le serveur MCP pour connaître les outils disponibles (via la méthode MCP list_tools). Les schémas de ces outils MCP découverts sont ensuite convertis en instances BaseTool compatibles avec ADK.
• Exposition à l'agent : ces outils adaptés sont ensuite mis à la disposition de votre LlmAgent comme s'il s'agissait d'outils ADK natifs.
• Relais des appels d'outils : lorsque votre LlmAgent décide d'utiliser l'un de ces outils, MCPToolset relaie l'appel (en utilisant la méthode MCP call_tool) au serveur MCP de manière transparente, envoie les arguments nécessaires et renvoie la réponse du serveur à l'agent.
• Filtrage (facultatif) : vous pouvez utiliser le paramètre tool_filter lors de la création d'un MCPToolset pour sélectionner un sous-ensemble spécifique d'outils sur le serveur MCP, plutôt que de tous les exposer à votre agent.

Obtenir une clé API et activer les API

Le serveur MCP Google Maps nécessite une clé API pour communiquer avec les services Google Maps. Au cours de cette étape, vous allez générer une clé API nommée GOOGLE_MAPS_API_KEY et la limiter aux API Directions et Routes pour des raisons de sécurité.

1. Accédez à l'onglet de navigateur de la console Google Cloud (et non à votre éditeur Cloud Shell).

2. Vous pouvez fermer le volet du terminal Cloud Shell dans cet onglet du navigateur pour agrandir la zone de la console.

3. Recherchez Identifiants dans la barre de recherche en haut de la page. Sélectionnez "Identifiants" dans les résultats.

4. Sur la page Identifiants, cliquez sur Créer des identifiants en haut de la page, puis sélectionnez Clé API.

5. Dans le champ Nom, saisissez GOOGLE_MAPS_API_KEY.

6. Pour API accessibles à l'aide de cette clé, sélectionnez les API suivantes :

   • API Directions
   • API Routes

7. Cliquez sur Créer.

   La boîte de dialogue Clé API créée affiche la clé API que vous venez de créer. Veillez à copier et à enregistrer cette clé en local, car vous en aurez besoin plus tard dans l'atelier.

8. Cliquez sur Fermer dans la boîte de dialogue.

   

Définir votre agent avec MCPToolset pour Google Maps

Vous allez maintenant configurer votre agent pour qu'il utilise les outils Google Maps. En ajoutant MCPToolset, vous permettez à l'agent de découvrir et d'appeler dynamiquement les API Maps si nécessaire.

1. Collez la commande suivante dans un document en texte brut sur votre ordinateur, puis remplacez la valeur YOUR_ACTUAL_API_KEY par la clé API Google Maps que vous avez générée et enregistrée à l'étape précédente :

   cd ~/adk_mcp_tools cat << EOF > google_maps_mcp_agent/.env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id | Project }}} GOOGLE_CLOUD_LOCATION=global GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_API_KEY" MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} EOF

2. Copiez et collez la commande mise à jour dans le terminal Cloud Shell, puis exécutez-la pour écrire un fichier .env qui fournit les détails d'authentification pour ce répertoire d'agent.

3. Copiez le fichier .env dans l'autre répertoire d'agent que vous utiliserez plus tard dans cet atelier en exécutant la commande suivante :

   cp google_maps_mcp_agent/.env adk_mcp_server/.env

4. Dans le volet de l'explorateur de fichiers de l'éditeur Cloud Shell, recherchez le dossier adk_mcp_tools. Cliquez dessus pour l'ouvrir.

5. Accédez au répertoire adk_mcp_tools/google_maps_mcp_agent.

6. Ouvrez agent.py et ajoutez le code suivant après le commentaire ## Add the MCPToolset (sur une nouvelle ligne après la ligne 53) pour configurer la connexion de l'agent au serveur MCP Google Maps :

   tools=[ MCPToolset( connection_params=StdioConnectionParams( server_params=StdioServerParameters( command='npx', args=[ "-y", "@modelcontextprotocol/server-google-maps", ], env={ "GOOGLE_MAPS_API_KEY": google_maps_api_key } ), timeout=15, ), ) ],

7. Enregistrez le fichier.

8. Dans le répertoire du projet adk_mcp_tools, lancez l'interface utilisateur de développement d'Agent Development Kit à l'aide de la commande suivante :

   adk web --allow_origins "regex:https://.*.cloudshell.dev" --otel_to_cloud --reload_agents

   Résultat :

   INFO: Started server process [2434] 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://127.0.0.1:8000 (Press CTRL+C to quit)

9. Pour afficher l'interface Web dans un nouvel onglet, cliquez sur le lien http://127.0.0.1:8000 dans la sortie du terminal.

10. L'interface utilisateur de développement d'ADK s'ouvre dans un nouvel onglet du navigateur. Dans le menu déroulant Sélectionner un agent à gauche, sélectionnez google_maps_mcp_agent.

11. Lancez une conversation avec l'agent et exécutez les prompts suivants :

    Get directions from GooglePlex to SFO. Remarque : Si votre appel d'API expire la première fois que vous l'utilisez, cliquez sur + Nouvelle session en haut à droite de l'interface utilisateur de développement d'ADK et réessayez. What's the route from Paris, France to Berlin, Germany?

    Résultat :

    

12. Cliquez sur l'icône de l'agent à côté de la bulle de chat de l'agent avec un éclair, qui indique un appel de fonction. L'outil d'inspection des événements s'ouvre pour cet événement.

    

    Notez que le graphique de l'agent indique plusieurs outils différents, identifiés par l'emoji clé à molette (🔧). Même si vous n'avez importé qu'un seul MCPToolset, cet ensemble d'outils comprend les différents outils que vous voyez listés ici, tels que maps_place_details et maps_directions.

    

    Dans l'onglet Événement, vous pouvez voir la structure de la requête. Vous pouvez utiliser les flèches en haut de l'outil d'inspection des événements pour parcourir les réflexions de l'agent, les appels de fonction et les réponses.

13. Lorsque vous avez terminé de poser des questions à cet agent, fermez l'onglet du navigateur de l'interface utilisateur de développement.

14. Revenez au panneau du terminal Cloud Shell et appuyez sur CTRL+C pour arrêter le serveur.

Cliquez sur Vérifier ma progression pour valider l'objectif. Créer la clé API et déployer l'agent ADK

Tâche 3 : Créer un serveur MCP avec les outils ADK (serveur MCP exposant ADK)

Dans cette section, vous allez apprendre à exposer l'outil ADK load_web_page à l'aide d'un serveur MCP personnalisé. Ce modèle vous permet d'encapsuler les outils ADK existants et de les rendre accessibles à n'importe quelle application cliente MCP standard.

Créer le script du serveur MCP et implémenter la logique du serveur

1. Revenez à l'éditeur Cloud Shell et sélectionnez le répertoire adk_mcp_tools/adk_mcp_server.

2. Ouvrez le fichier Python nommé adk_server.py. Ce fichier contient la logique de votre serveur MCP personnalisé. Examinez le code pour comprendre comment il encapsule l'outil ADK et le livre.

   Prenez le temps de parcourir ce fichier et de lire les commentaires pour comprendre comment le code encapsule un outil et le livre en tant que serveur MCP. Notez comment le code permet aux clients MCP de lister les outils disponibles et d'appeler l'outil ADK de manière asynchrone, en gérant les requêtes et les réponses dans un format conforme à MCP.

Tester le serveur MCP personnalisé avec un agent ADK

1. Ouvrez agent.py dans le répertoire adk_mcp_server.

2. À la ligne 31, remplacez la valeur de PATH_TO_YOUR_MCP_SERVER_SCRIPT par le chemin d'accès suivant pour que l'agent puisse se connecter à votre script de serveur personnalisé :

   /home/{{{project_0.startup_script.updated_lab_username | Username}}}/adk_mcp_tools/adk_mcp_server/adk_server.py

3. Ensuite, ajoutez le code suivant à la ligne 55, c'est-à-dire après ## Add the MCPToolset below: dans le fichier agent.py, pour ajouter MCPToolset à votre agent. Un agent ADK agit en tant que client du serveur MCP. Cet agent ADK utilise MCPToolset pour se connecter à votre script adk_server.py.

   tools=[ MCPToolset( connection_params=StdioConnectionParams( server_params=StdioServerParameters( command="python3", # Command to run your MCP server script args=[PATH_TO_YOUR_MCP_SERVER_SCRIPT], # Argument is the path to the script ), timeout=15, ), tool_filter=['load_web_page'] # Optional: ensure only specific tools are loaded ) ],

4. Enregistrez le fichier.

5. Pour exécuter le serveur MCP, démarrez le script adk_server.py en exécutant la commande suivante dans le terminal Cloud Shell :

   python3 ~/adk_mcp_tools/adk_mcp_server/adk_server.py

   Résultat :

   

6. Ouvrez un nouvel onglet de terminal Cloud Shell en cliquant sur le bouton en haut de la fenêtre du terminal Cloud Shell.

7. Dans le terminal Cloud Shell, à partir du répertoire du projet adk_mcp_tools, lancez l'interface utilisateur de développement d'Agent Development Kit à l'aide de la commande suivante :

   export PATH=$PATH:"/home/${USER}/.local/bin" cd ~/adk_mcp_tools adk web --allow_origins "regex:https://.*.cloudshell.dev" --otel_to_cloud --reload_agents Remarque : La variable "PATH" a été ajoutée à cette commande pour la réinitialiser, car le nouveau terminal Cloud Shell peut générer une erreur si vous exécutez le reste de la commande sans elle. Il s'agit généralement d'une erreur "adk web not found" (adk web introuvable).

8. Pour afficher l'interface Web dans un nouvel onglet, cliquez sur le lien http://127.0.0.1:8000 dans la sortie du terminal.

9. Dans le menu déroulant Sélectionner un agent à gauche, sélectionnez adk_mcp_server.

10. Envoyez le prompt suivant à l'agent :

    Load the content from http://example.com.

    Résultat :

    

    Ce qui se passe :

    • L'agent ADK (web_reader_mcp_client_agent) utilise MCPToolset pour se connecter à votre adk_server.py.
    • Le serveur MCP reçoit la requête call_tool, exécute l'outil ADK load_web_page et renvoie le résultat.
    • L'agent ADK transmet ensuite ces informations. Vous devriez voir des journaux provenant de l'UI Web ADK (et de son terminal) et de votre terminal adk_server.py dans l'onglet du terminal Cloud Shell où il s'exécute.

    Cela montre que les outils ADK peuvent être encapsulés dans un serveur MCP, ce qui les rend accessibles à un large éventail de clients conformes à MCP, y compris les agents ADK.

Félicitations !

Dans cet atelier, vous avez appris à intégrer des outils MCP (Model Context Protocol) externes à vos agents ADK (Agent Development Kit) à l'aide de la classe MCPToolset. Vous avez découvert comment vous connecter à un serveur MCP, utiliser ses outils dans votre agent et exposer des outils ADK comme load_web_page à l'aide d'un serveur MCP personnalisé. Ces compétences vous permettent d'ajouter des services externes puissants à vos agents ADK, ce qui améliore vos workflows de développement Web.

Dernière mise à jour du manuel : 21 avril 2026

Dernier test de l'atelier : 21 avril 2026

Copyright 2026 Google LLC. Tous droits réservés. Google et le logo Google sont des marques de Google LLC. Tous les autres noms d'entreprises et de produits peuvent être des marques des entreprises auxquelles ils sont associés.