GENAI124

Présentation

Dans cet atelier, vous allez découvrir MCP (Model Context Protocol), 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 apprendrez à intégrer MCP à vos agents ADK en utilisant les outils fournis par les serveurs MCP existants pour améliorer vos workflows ADK. Vous verrez également comment exposer des outils ADK tels que load_web_page via 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 via 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 Start Lab (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 le bouton "Start Lab" (Démarrer l'atelier), indique combien de temps les ressources cloud resteront accessibles.

Cet atelier pratique Qwiklabs vous permet de suivre vous-même 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 Platform le temps de l'atelier.

Conditions requises

Pour réaliser cet atelier, vous devez remplir les conditions suivantes :

• Vous devez avoir accès à un navigateur Internet standard (nous vous recommandons d'utiliser Chrome).
• Vous devez disposer de suffisamment de temps pour réaliser l'atelier en une fois.

Remarque : Si vous possédez déjà un compte ou un projet GCP, veillez à ne pas l'utiliser pour réaliser cet atelier.

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

Remarque : Nous vous recommandons d'utiliser une fenêtre de navigation privée pour la plupart des activités Qwiklabs afin d'éviter toute confusion entre votre compte étudiant Qwiklabs et d'autres comptes connectés à Google Cloud. Si vous utilisez Chrome, fermez toutes les fenêtres de navigation privée, effectuez un clic droit sur le bouton Ouvrir la console Google Cloud en haut de cet atelier et sélectionnez Ouvrir le lien dans une fenêtre de navigation privée.

Activer les API recommandées

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

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

2. Dans la fenêtre de la console Google Cloud, ouvrez Cloud Shell en appuyant sur les touches G, puis S de votre clavier. Vous pouvez également cliquer sur le bouton Activer Cloud Shell () en haut à droite de la console Cloud.

3. Cliquez sur Continuer.

4. Si vous êtes invité à autoriser Cloud Shell, cliquez sur Autoriser.

5. En haut à droite du panneau du terminal Cloud Shell, cliquez sur le bouton Ouvrir dans une nouvelle fenêtre .

6. Dans le terminal Cloud Shell, saisissez la commande suivante pour ouvrir l'éditeur Cloud Shell dans votre répertoire d'accueil :

   cloudshell workspace ~

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

8. 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

9. Installez ADK en exécutant la commande suivante dans le terminal Cloud Shell.

   Remarque : Vous allez spécifier la version pour vous assurer que la version d'ADK que vous installez correspond à celle utilisée dans cet atelier. Vous pouvez consulter le numéro de version et les notes de version les plus récents dans le dépôt adk-python. sudo python3 -m pip install google-adk==1.5.0

10. Collez les commandes suivantes dans le terminal Cloud Shell pour copier un fichier depuis un bucket Cloud Storage et le décompresser. Un répertoire de projet contenant le code de cet atelier sera ainsi créé :

    gcloud storage cp gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/adk_mcp_tools.zip . unzip adk_mcp_tools.zip

11. Installez les éléments supplémentaires requis pour l'atelier :

    python3 -m pip install -r adk_mcp_tools/requirements.txt

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

Tâche 2 : Utilisation du serveur MCP Google Maps avec des agents ADK (ADK en tant que client MCP) dans adk web

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

Dans cette sous-section, vous allez générer une clé API nommée GOOGLE_MAPS_API_KEY.

1. Ouvrez l'onglet de navigateur affichant la console Google Cloud (et non l'é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.

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

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

   Par défaut, votre nouvelle clé s'appelle Clé API 1. Sélectionnez la clé, renommez-la en GOOGLE_MAPS_API_KEY, puis cliquez sur Enregistrer.

   

Définir votre agent avec MCPToolset pour Google Maps

Dans cette sous-section, vous allez configurer votre agent pour qu'il utilise MCPToolset pour Google Maps, ce qui lui permettra de fournir des itinéraires et des informations basées sur la localisation de manière fluide.

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

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

8. Collez la commande suivante dans un fichier en texte brut, 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={{{ project_0.default_region | Region}}} GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_API_KEY" EOF

9. Copiez et collez la commande mise à jour dans le terminal Cloud Shell pour l'exécuter et écrire un fichier .env qui fournira les détails d'authentification pour ce répertoire d'agent.

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

    cp google_maps_mcp_agent/.env adk_mcp_server/.env

11. Ensuite, ajoutez le code suivant à l'endroit indiqué dans le fichier agent.py pour ajouter l'outil Google Maps à votre agent. Cela permettra à votre agent d'utiliser MCPToolset pour Google Maps afin de fournir des itinéraires ou des informations basées sur la localisation.

    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, ), ) ],

12. 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

    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)

13. Pour afficher l'interface Web dans un nouvel onglet, cliquez sur le lien http://127.0.0.1:8000 dans le résultat du terminal.

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

15. 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'UI de développement d'ADK et réessayez. What's the route from Paris, France to Berlin, Germany?

    Résultat :

    

16. 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 :

    

17. 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.

    

18. Dans l'onglet Request (Requête), 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.

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

20. 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 une 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 via 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'onglet de l'éditeur Cloud Shell et sélectionnez le répertoire adk_mcp_tools/adk_mcp_server.

2. Un fichier Python nommé adk_server.py a été préparé et commenté pour vous. 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 qu'il 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

3. Cliquez sur le fichier agent.py dans le répertoire adk_mcp_server.

4. Mettez à jour le chemin d'accès à votre fichier adk_server.py.

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

5. Ensuite, ajoutez le code suivant à l'endroit indiqué dans le fichier agent.py pour ajouter MCPToolset à votre agent. Un agent ADK agit en tant que client du serveur MCP. Cet agent ADK utilisera 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 ) ],

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

   

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

8. 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 :

   cd ~/adk_mcp_tools adk web

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

10. Dans le menu déroulant Select an agent (Sélectionner un agent) à gauche, sélectionnez adk_mcp_server.

11. Interrogez l'agent avec la requête suivante :

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

    Résultat :

    

    Ce qui se passe :

    1. L'agent ADK (web_reader_mcp_client_agent) utilise MCPToolset pour se connecter à votre adk_server.py.
    2. Le serveur MCP reçoit la requête call_tool, exécute l'outil ADK load_web_page et renvoie le résultat.
    3. L'agent ADK transmettra 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 à 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 via 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 : 3 septembre 2025

Dernier test de l'atelier : 3 septembre 2025

Copyright 2020 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.