GSP1350

Présentation

Cet atelier montre comment implémenter et déployer un service d'agent IA client à l'aide d'Agent Development Kit (ADK) pour créer un agent IA qui va utiliser des outils distants, en l'occurrence un serveur MCP (Model Context Protocol). Le principe architectural clé illustré dans cet exemple est la séparation des préoccupations : une couche de raisonnement (l'agent) communique avec une autre couche séparée pour les outils (le serveur MCP) par l'intermédiaire d'une API sécurisée.

Dans cet atelier, un serveur MCP a déjà été déployé. Il fournit des données sur les animaux d'un zoo fictif aux LLM. Vous devrez créer un agent de guide touristique (une application Python) pour le zoo fictif. L'agent utilise le serveur MCP pour accéder aux informations sur les animaux du zoo et Wikipédia pour créer la meilleure expérience de visite guidée possible.

Enfin, vous déploierez l'agent de guide touristique sur Google Cloud Run, afin qu'il soit accessible à tous les visiteurs du zoo et pas seulement en local.

Points abordés

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

• Structurer un projet Python pour le déployer avec ADK
• Implémenter un agent utilisant des outils avec google-adk
• Connecter un agent à un serveur MCP distant pour utiliser son ensemble d'outils
• Déployer une application Python en tant que conteneur sans serveur sur Cloud Run
• Configurer une authentification sécurisée de service à service à l'aide de rôles IAM
• Supprimer les ressources Cloud pour éviter d'accumuler des coûts

Pourquoi effectuer le déploiement sur Cloud Run ?

Cloud Run est parfait pour héberger des agents ADK, car il s'agit d'une plate-forme sans serveur : vous pouvez donc vous concentrer sur votre code sans avoir à gérer l'infrastructure sous-jacente. Cloud Run gère également les tâches opérationnelles à votre place.

Il fonctionne un peu comme une boutique éphémère, qui n'ouvre et n'utilise des ressources que lorsque des clients (en l'occurrence, des requêtes) se présentent. Lorsqu'il n'y a pas de clients, la boutique est complètement fermée, ce qui évite d'avoir à payer quand elle est vide.

Principales caractéristiques de Cloud Run

Exécute des conteneurs partout

• Vous fournissez un conteneur (image Docker) contenant votre application.
• Cloud Run l'exécute sur l'infrastructure de Google.
• Vous n'avez pas besoin de gérer les correctifs de l'OS, la configuration des VM ni le scaling.

Scaling automatique

• Si personne n'utilise votre application, aucune instance n'est exécutée (vous ne payez rien en cas d'inactivité).
• Si vous recevez soudain 1 000 requêtes, Cloud Run lance autant de ressources que nécessaire pour les traiter.

Sans état par défaut

• Chaque requête peut être envoyée à une instance différente.
• Si vous devez stocker l'état, utilisez un service externe comme Cloud SQL, Firestore ou Redis.

Compatible avec n'importe quel langage ou framework

• Tant qu'il s'exécute dans un conteneur Linux, Cloud Run est compatible avec Python, Go, Node.js, Java ou .NET.

Services facturés à l'utilisation

• Facturation par requête + temps de calcul (avec une précision à 100 ms).
• À l'inverse des VM classiques, les ressources ne sont pas facturées lorsqu'elles sont inactives.

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

Remarque : Ouvrez une fenêtre de navigateur en mode incognito (recommandé) ou de navigation privée pour effectuer cet atelier. Vous éviterez ainsi les conflits entre votre compte personnel et le compte temporaire de participant, qui pourraient entraîner des frais supplémentaires facturés sur votre compte personnel.

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

Remarque : Utilisez uniquement le compte de participant pour cet atelier. Si vous utilisez un autre compte Google Cloud, des frais peuvent être facturés à ce compte.

Activer Cloud Shell

Cloud Shell est une machine virtuelle qui contient de nombreux outils pour les développeurs. Elle comprend un répertoire d'accueil persistant de 5 Go et s'exécute sur Google Cloud. Cloud Shell vous permet d'accéder via une ligne de commande à vos ressources Google Cloud.

1. Cliquez sur Activer Cloud Shell  en haut de la console Google Cloud.

2. Passez les fenêtres suivantes :

   • Accédez à la fenêtre d'informations de Cloud Shell.
   • Autorisez Cloud Shell à utiliser vos identifiants pour effectuer des appels d'API Google Cloud.

Une fois connecté, vous êtes en principe authentifié et le projet est défini sur votre ID_PROJET : . Le résultat contient une ligne qui déclare l'ID_PROJET pour cette session :

Your Cloud Platform project in this session is set to {{{project_0.project_id | "PROJECT_ID"}}}

gcloud est l'outil de ligne de commande pour Google Cloud. Il est préinstallé sur Cloud Shell et permet la complétion par tabulation.

3. (Facultatif) Vous pouvez lister les noms des comptes actifs à l'aide de cette commande :

gcloud auth list

4. Cliquez sur Autoriser.

Résultat :

ACTIVE: * ACCOUNT: {{{user_0.username | "ACCOUNT"}}} To set the active account, run: $ gcloud config set account `ACCOUNT`

5. (Facultatif) Vous pouvez lister les ID de projet à l'aide de cette commande :

gcloud config list project

Résultat :

[core] project = {{{project_0.project_id | "PROJECT_ID"}}} Remarque : Pour consulter la documentation complète sur gcloud, dans Google Cloud, accédez au guide de présentation de la gcloud CLI.

Tâche 1 : Télécharger ADK, l'installer et créer un dossier de projet

Dans cette tâche, vous allez activer les API requises et créer un dossier de projet pour stocker le code source qui servira à déployer votre projet Python.

Activer les API et définir les variables d'environnement

1. Dans Cloud Shell, cliquez sur Ouvrir l'éditeur pour ouvrir l'éditeur Cloud Shell dans votre répertoire d'accueil.
2. Dans la barre d'action de l'éditeur Cloud Shell, cliquez sur Afficher > Terminal.

Remarque : Vous devrez peut-être agrandir votre fenêtre de navigateur pour voir l'option de menu "Afficher".

Pour le reste de cet atelier, utilisez cette fenêtre comme IDE, avec l'éditeur Cloud Shell en haut et le terminal Cloud Shell en bas.

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.

3. Dans le terminal, saisissez la commande suivante pour configurer votre projet :

   gcloud config set project {{{project_0.project_id | filled in at lab start}}}

Résultat attendu : Vous devez voir un message confirmant la mise à jour de la propriété.

Remarque : Si vous redémarrez Cloud Shell ou si la fenêtre reste inactive, vous devrez reconfigurer le projet.

4. Exécutez la commande suivante pour activer tous les services nécessaires :

   gcloud services enable \ run.googleapis.com \ artifactregistry.googleapis.com \ cloudbuild.googleapis.com \ aiplatform.googleapis.com \ compute.googleapis.com

Résultat attendu : Vous devez voir un message confirmant que l'opération a réussi.

Cliquez sur Vérifier ma progression pour valider l'objectif. Activer les API

Créer les répertoires du projet

1. Exécutez la commande suivante, qui crée un dossier principal dans l'atelier pour le code source de l'agent :

   mkdir zoo_guide_agent && cd zoo_guide_agent

Vous êtes maintenant prêt à créer le fichier requirements.txt. Ce fichier liste les bibliothèques Python dont votre agent de zoo a besoin.

2. Exécutez la commande suivante pour créer le fichier dans le répertoire zoo_guide_agent et l'ouvrir dans l'éditeur Cloud Shell afin de pouvoir le modifier :

   cloudshell edit requirements.txt

3. Ajoutez les lignes suivantes au fichier requirements.txt et appuyez sur Ctrl+S pour enregistrer vos modifications :

   google-adk==1.28.0 langchain==1.2.14 langchain-community==0.4.1 wikipedia

4. Exécutez la commande suivante dans le terminal pour installer vos packages Python et mettre à jour votre variable PATH :

   export PATH=$PATH:~/.local/bin pip3 install -r requirements.txt --user

5. Définissez des variables pour le projet, la région et l'utilisateur actuels à l'aide des commandes suivantes :

   export PROJECT_ID=$(gcloud config get-value project) export REGION=$(gcloud compute project-info describe \ --format="value(commonInstanceMetadata.items[google-compute-default-region])") export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)") export SERVICE_ACCOUNT="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"

Remarque : Si vous redémarrez Cloud Shell ou si la fenêtre reste inactive, vous devrez réinitialiser les variables ci-dessus.

6. Créez et ouvrez un fichier .env pour authentifier l'agent dans le répertoire zoo_guide_agent à l'aide de la commande suivante :

   cloudshell edit .env

Le répertoire contenant le fichier .env s'ouvre dans l'éditeur Cloud Shell.

7. Ajoutez les lignes suivantes au fichier .env et enregistrez vos modifications :

   MODEL="{{{ project_0.startup_script.gemini_flash_model_id | filled in at lab start }}}" SERVICE_ACCOUNT="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" GOOGLE_GENAI_USE_ENTERPRISE=true GOOGLE_CLOUD_LOCATION=global

Se connecter au point de terminaison du serveur MCP sécurisé

Dans cette section, vous allez établir une connexion au serveur MCP distant.

1. Revenez au terminal Cloud Shell et exécutez la commande suivante pour autoriser l'identité de service Cloud Run à appeler le serveur MCP distant :

   gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:$SERVICE_ACCOUNT" \ --role="roles/run.invoker"

2. Exécutez la commande suivante pour enregistrer l'URL du serveur MCP dans une variable d'environnement :

   echo -e "\nMCP_SERVER_URL=https://zoo-mcp-server-${PROJECT_NUMBER}.${REGION}.run.app/mcp/" >> .env

3. Ensuite, exécutez la commande ci-dessous pour créer le fichier __init__.py. Ce fichier indique à Python que le répertoire zoo_guide_agent est un package :

   cloudshell edit __init__.py

4. Dans l'éditeur Cloud Shell qui s'ouvre, ajoutez le code suivant à __init__.py et enregistrez vos modifications :

   from . import agent

Tâche 2 : Créer le workflow de l'agent

Dans cette tâche, vous allez configurer le workflow de l'agent de guide touristique pour le zoo. Vous allez d'abord importer les bibliothèques nécessaires à la configuration initiale. Ensuite, vous définirez les capacités de l'agent du zoo (les outils qu'il utilise), ainsi que les agents spécialisés. Enfin, vous définirez l'agent de workflow et vous assemblerez le workflow principal.

Créer le fichier principal agent.py

• Revenez au terminal Cloud Shell et exécutez la commande ci-dessous pour créer le fichier principal agent.py. Il s'ouvre dans l'éditeur Cloud Shell, ce qui vous permet de coller le code complet de votre système multi-agent lors des étapes suivantes :

  cloudshell edit agent.py

Importer les bibliothèques et effectuer la configuration initiale

Ce premier bloc importe toutes les bibliothèques nécessaires depuis ADK et Google Cloud. Il configure également la journalisation et charge les variables d'environnement à partir de votre fichier .env, ce qui est essentiel pour accéder au modèle et à l'URL du serveur.

• Ajoutez le code suivant à votre fichier agent.py :

  import os import sys import logging import google.cloud.logging from dotenv import load_dotenv # Add current directory for workspace utilities sys.path.append(os.path.dirname(os.path.abspath(__file__))) from google.adk import Agent from google.adk.agents import SequentialAgent from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset, StreamableHTTPConnectionParams from google.adk.tools.tool_context import ToolContext from google.adk.tools.langchain_tool import LangchainTool from langchain_community.tools import WikipediaQueryRun from langchain_community.utilities import WikipediaAPIWrapper import google.auth import google.auth.transport.requests import google.oauth2.id_token # --- Setup Logging and Environment --- cloud_logging_client = google.cloud.logging.Client() cloud_logging_client.setup_logging() load_dotenv() model_name = os.getenv("MODEL")

Définir les outils

Un agent n'est efficace que s'il dispose des bons outils. Dans cette section, vous allez définir toutes les fonctionnalités de votre agent, y compris une fonction personnalisée pour enregistrer des données, un outil MCP qui se connecte à votre serveur MCP sécurisé, ainsi qu'un outil Wikipédia.

• Ajoutez le code suivant à la fin de agent.py :

  # Greet user and save their prompt def add_prompt_to_state( tool_context: ToolContext, prompt: str ) -> dict[str, str]: """Saves the user's initial prompt to the state.""" tool_context.state["PROMPT"] = prompt logging.info(f"[State updated] Added to PROMPT: {prompt}") return {"status": "success"} # Configuring the MCP Tool to connect to the Zoo MCP server mcp_server_url = os.getenv("MCP_SERVER_URL") if not mcp_server_url: raise ValueError("The environment variable MCP_SERVER_URL is not set.") def get_id_token(): """Get an ID token to authenticate with the MCP server.""" target_url = os.getenv("MCP_SERVER_URL") audience = target_url.split('/mcp/')[0] request = google.auth.transport.requests.Request() id_token = google.oauth2.id_token.fetch_id_token(request, audience) return id_token """ ## Use this code if you are using the public MCP Server and comment out the code below defining mcp_tools mcp_tools = MCPToolset( connection_params=StreamableHTTPConnectionParams( url=mcp_server_url ) ) """ mcp_tools = MCPToolset( connection_params=StreamableHTTPConnectionParams( url=mcp_server_url, headers={ "Authorization": f"Bearer {get_id_token()}", }, ), ) # Configuring the Wikipedia Tool wikipedia_tool = LangchainTool( tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper()) )

Présentation des trois outils

• add_prompt_to_state 📝 : cet outil mémorise les questions posées par les visiteurs du zoo. Lorsqu'un visiteur demande "Où sont les lions ?", il enregistre cette question spécifique dans la mémoire de l'agent afin que les autres agents du workflow sachent ce qu'ils doivent rechercher.

  Comment ? Une fonction Python écrit le prompt du visiteur dans le dictionnaire partagé tool_context.state. Ce dictionnaire représente la mémoire à court terme de l'agent pour une conversation unique. Les données enregistrées dans l'état par un agent peuvent être lues par l'agent suivant dans le workflow.

• MCPToolset 🦁 : cet outil permet de connecter l'agent de guide touristique au serveur MCP du zoo prédéployé dans cet atelier. Ce serveur dispose d'outils dédiés à la recherche d'informations spécifiques sur les animaux du zoo, comme leur nom, leur âge et leur enclos.

  Comment ? Il se connecte de manière sécurisée à l'URL du serveur privé du zoo. Il utilise get_id_token pour obtenir automatiquement une "carte d'accès" sécurisée (jeton d'ID de compte de service) afin de prouver son identité et d'obtenir l'accès.

• LangchainTool 🌍 : cet outil fournit à l'agent de guide touristique des connaissances générales sur le monde. Si un visiteur pose une question qui ne figure pas dans la base de données du zoo (par exemple, "Que mangent les lions dans leur habitat naturel ?"), cet outil permet à l'agent de rechercher la réponse sur Wikipédia.

  Comment ? Il sert d'adaptateur permettant à l'agent d'utiliser l'outil WikipediaQueryRun prédéfini depuis la bibliothèque LangChain.

Ressources :

• Outils MCP
• Outils de fonction
• Attribut State

Définir les agents spécialisés

Dans cette section, vous allez définir deux agents spécialisés : l'agent de recherche et l'agent de formulation des réponses. L'agent de recherche est le "cerveau" de votre opération. Cet agent interprète le prompt de l'utilisateur à partir de l'attribut State (État) partagé, interroge ses outils avancés (le serveur MCP du zoo et Wikipédia) et détermine celui qu'il doit utiliser pour trouver la réponse.

Le rôle de l'agent de formulation des réponses est de présenter les réponses. Il ne recherche aucune information nouvelle dans les outils. Il transforme les données brutes collectées par l'agent de recherche (transmises à l'aide de l'attribut "State") en réponse conviviale et conversationnelle en utilisant les compétences linguistiques du LLM.

• Ajoutez le code suivant à la fin de agent.py :

  # 1. Researcher Agent comprehensive_researcher = Agent( name="comprehensive_researcher", model=model_name, description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.", instruction=""" You are a helpful research assistant. Your goal is to fully answer the user's PROMPT. You have access to two tools: 1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations). 2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat). First, analyze the user's PROMPT. - If the prompt can be answered by only one tool, use that tool. - If the prompt is complex and requires information from both the zoo's database AND Wikipedia, you MUST use both tools to gather all necessary information. - Synthesize the results from the tool(s) you use into preliminary data outputs. PROMPT: {{ PROMPT }} """, tools=[ mcp_tools, wikipedia_tool ], output_key="research_data" # A key to store the combined findings ) # 2. Response Formatter Agent response_formatter = Agent( name="response_formatter", model=model_name, description="Synthesizes all information into a friendly, readable response.", instruction=""" You are the friendly voice of the Zoo Tour Guide. Your task is to take the RESEARCH_DATA and present it to the user in a complete and helpful answer. - First, present the specific information from the zoo (like names, ages, and where to find them). - Then, add the interesting general facts from the research. - If some information is missing, just present the information you have. - Be conversational and engaging. RESEARCH_DATA: {{ research_data }} """ )

Définir l'agent de workflow

L'agent de workflow est l'entité qui gère la visite du zoo en coulisses. Une fois la demande de recherche envoyée, il s'assure que les deux agents que vous avez définis à l'étape 3 interviennent dans le bon ordre : d'abord la recherche, puis la formulation de la réponse. Il garantit que le processus consistant à répondre aux questions des visiteurs du zoo est prévisible et fiable.

Comment ? Il s'agit d'un agent séquentiel (SequentialAgent) spécifique qui ne réfléchit pas par lui-même. Son seul rôle est d'exécuter une liste de sous-agents sub_agents (l'agent de recherche et l'agent de formulation) dans un ordre fixe, en transmettant automatiquement la mémoire partagée de l'un à l'autre.

• Ajoutez le bloc de code suivant en bas du fichier agent.py :

  tour_guide_workflow = SequentialAgent( name="tour_guide_workflow", description="The main workflow for handling a user's request about an animal.", sub_agents=[ comprehensive_researcher, # Step 1: Gather all data response_formatter, # Step 2: Format the final response ] )

Assembler le workflow principal

Le workflow principal est désigné par root_agent, qui sert de point de départ à toutes les nouvelles conversations dans le framework ADK. Le rôle principal de cet agent est d'orchestrer le processus global. Il agit comme le contrôleur initial qui gère le premier tour de la conversation.

• Ajoutez ce dernier bloc de code à la fin de agent.py et enregistrez vos modifications :

  root_agent = Agent( name="greeter", model=model_name, description="The main entry point for the Zoo Tour Guide.", instruction=""" - Let the user know you will help them learn about the animals we have in the zoo. - When the user responds, use the 'add_prompt_to_state' tool to save their response. After using the tool, transfer control to the 'tour_guide_workflow' agent. """, tools=[add_prompt_to_state], sub_agents=[tour_guide_workflow] )

Votre fichier agent.py est maintenant terminé.

Les différentes étapes vous ont permis de comprendre le rôle spécifique de chaque composant (outils, agents de traitement et agents de gestion) dans la création du système intelligent final. Passons maintenant au déploiement.

Tâche 3 : Préparer l'application pour le déploiement

Maintenant que votre environnement local est prêt, vous devez préparer votre projet Google Cloud pour déployer l'agent de guide du zoo.

Cette étape implique de vérifier une dernière fois la structure de fichiers de votre agent pour vous assurer qu'elle est compatible avec la commande de déploiement. Plus important encore, vous allez configurer une autorisation IAM essentielle qui permet à votre service Cloud Run déployé d'agir à votre place et d'appeler les modèles Agent Platform. Vous aurez ainsi la certitude que l'environnement cloud est prêt à exécuter votre agent.

1. Revenez au terminal Cloud Shell et exécutez la commande suivante pour charger les variables dans votre session shell :

   source .env

2. Exécutez la commande suivante pour attribuer au compte de service le rôle "Utilisateur Agent Platform", lequel lui donne l'autorisation de générer des prédictions et d'appeler les modèles de Google :

   # Grant the "Agent Platform User" role to your service account gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:$SERVICE_ACCOUNT" \ --role="roles/aiplatform.user"

Tâche 4 : Déployer l'agent à l'aide de la CLI ADK

Maintenant que votre code local et votre projet Google Cloud sont prêts, il est temps de déployer l'agent.

Dans cette tâche, vous allez utiliser la commande adk deploy cloud_run, qui permet d'automatiser l'ensemble du workflow de déploiement en toute simplicité. Cette commande unique crée un package à partir du code, génère une image de conteneur, la transmet à Artifact Registry et lance le service sur Cloud Run pour le rendre accessible sur le Web.

Déployer l'agent

1. Exécutez la commande suivante pour déployer l'agent :

   # Run the deployment command adk deploy cloud_run \ --project=$PROJECT_ID \ --region=$REGION \ --service_name=zoo-tour-guide \ --with_ui \ .

2. Si vous êtes invité à confirmer que vous souhaitez continuer et/ou à autoriser les appels non authentifiés vers [zoo-tour-guide], appuyez sur Y dans les deux cas, puis sur ENTRÉE.

Remarque : L'exécution de cette commande de déploiement peut prendre entre 5 et 10 minutes.

3. Exécutez la commande suivante pour modifier les paramètres de configuration du service Cloud Run existant :

   gcloud run services update zoo-tour-guide \ --region=$REGION \ --update-labels=dev-tutorial=codelab-adk \ --set-env-vars="MODEL=$MODEL,MCP_SERVER_URL=$MCP_SERVER_URL,GOOGLE_CLOUD_LOCATION=global"

Obtenir le lien de déploiement

• Une fois l'agent déployé dans Cloud Run, il génère l'URL du service, à laquelle vous pouvez accéder dans un nouvel onglet de navigateur.

  Le format doit ressembler au résultat suivant. Résultat de l'URL du service :

  https://zoo-tour-guide-{{{project_0.startup_script.project_number | filled in at lab start}}}.{{{project_0.default_region | filled in at lab start}}}.run.app

Comme vous avez utilisé le flag --with_ui lors du déploiement sur Cloud Run, vous devriez voir l'UI de développement ADK.

Remarque : Toute personne disposant de l'URL peut accéder à cet agent. Il est donc recommandé de réserver cette approche aux tests internes. Remarque : Une fois le déploiement réussi, la vérification du suivi d'activité peut prendre quelques minutes avant d'aboutir.

Cliquez sur Vérifier ma progression pour valider l'objectif. Déployer l'agent

Tâche 5 : Tester l'agent déployé

Maintenant que votre agent est en service sur Cloud Run, vous allez effectuer un test pour vérifier que le déploiement a réussi et que l'agent fonctionne comme prévu. Vous devez utiliser l'URL du service public pour accéder à l'interface Web d'ADK et interagir avec l'agent.

1. Ouvrez l'URL publique du service Cloud Run qui a été générée lors de la tâche précédente dans votre navigateur Web ou appuyez sur CTRL et cliquez simultanément sur l'URL dans le résultat (elle doit s'ouvrir dans un nouvel onglet de navigateur). L'UI de développement ADK s'ouvre.

   Si vous recevez une notification demandant si vous souhaitez que Cloud Shell ouvre le site Web externe, cliquez sur Ouvrir pour confirmer.

2. Activez l'option Distribution de jetons en haut à droite de la barre d'outils ADK.

Vous pouvez maintenant interagir avec l'agent du zoo.

3. Saisissez le prompt suivant dans le champ du prompt et appuyez sur ENTRÉE pour démarrer une nouvelle conversation :

Hello

Observez le résultat. L'agent doit répondre rapidement en présentant son message de bienvenue standard :

"Hello! I'm your Zoo Tour Guide. I can help you learn about the amazing animals we have here. What would you like to know or explore today?"

4. Maintenant, interagissez avec l'agent de guide du zoo. Saisissez le prompt suivant pour reprendre la conversation :

Where are the penguins located?

Vous devriez obtenir un résultat semblable à celui-ci :

5. Essayez ces autres prompts pour voir comment l'agent utilise différents outils (MCP et Wikipédia) et combine les informations :

Pour tester les connaissances générales (Wikipédia uniquement) :

What is the average lifespan of a penguin in the wild?

Pour tester la combinaison de données internes et externes :

What species are the penguins in our zoo, and what do they typically eat in the wild?

À propos des lions (test des deux outils) :

Where are the lions and what do they eat in the wild?

À propos des ours polaires (test pour des animaux qui ne sont pas forcément présents dans le zoo) :

Do we have polar bears in this zoo?

Explication du flux de l'agent

Votre système fonctionne comme une équipe intelligente multi-agents. Le processus est géré par une séquence claire pour assurer un flux efficace et fluide, de la question de l'utilisateur à la réponse détaillée finale.

1. L'accueil du zoo ("La réception")

L'ensemble du processus commence par l'agent qui accueille l'utilisateur.

Son rôle : lancer la conversation. Sa consigne est de saluer l'utilisateur et de lui demander quel animal l'intéresse.

Son outil : lorsque l'utilisateur répond, cet agent utilise l'outil add_prompt_to_state pour recueillir ses mots exacts (par exemple, "parle-moi des lions") et les enregistrer dans la mémoire du système.

Le transfert : après avoir enregistré le prompt, il passe immédiatement le contrôle au sous-agent tour_guide_workflow.

2. Le chercheur complet ("Le superchercheur")

Cet agent intervient en premier dans le workflow principal et représente le "cerveau" de l'opération. Au lieu d'une grande équipe, vous disposez désormais d'un seul agent hautement qualifié qui peut accéder à toutes les informations disponibles.

Son rôle : analyser la question de l'utilisateur et élaborer un plan intelligent. Il utilise la fonctionnalité avancée d'exploitation des outils intégrée au modèle de langage pour déterminer s'il a besoin :

• des données internes issues des registres du zoo (par le biais du serveur MCP) ;
• des informations générales issues du Web (par l'intermédiaire de l'API Wikipédia) ;
• ou des deux, pour les questions complexes.

Son action : il exécute les outils nécessaires pour collecter toutes les données brutes requises. Par exemple, si on lui demande "Quel âge ont vos lions et de quoi se nourrissent-ils dans leur habitat naturel ?", il appellera le serveur MCP pour obtenir l'âge et l'outil Wikipédia pour obtenir des informations sur leur régime alimentaire.

3. L'outil de formulation des réponses ("Le présentateur")

Une fois que l'agent de recherche a rassemblé tous les faits, c'est le dernier agent à entrer en action.

Son rôle : incarner la voix bienveillante du guide du zoo. Il prend les données brutes (qui peuvent provenir d'une seule source ou des deux) et les affine.

Son action : il synthétise toutes les informations en une seule réponse cohérente et dynamique. En suivant ses instructions, il présente d'abord les renseignements spécifiques au zoo, puis ajoute les informations générales pertinentes.

Résultat final : le texte généré par cet agent constitue la réponse complète et détaillée que l'utilisateur voit dans la fenêtre de discussion.

Tâche 6 : Nettoyer l'environnement

Lors de cette tâche, vous allez supprimer les ressources Cloud que vous avez créées dans cet atelier pour éviter d'accumuler des frais.

• Revenez à l'onglet du terminal Cloud Shell et exécutez la commande suivante :

  gcloud run services delete zoo-tour-guide --region=$REGION --quiet gcloud artifacts repositories delete cloud-run-source-deploy --location=$REGION --quiet

Étapes suivantes et informations supplémentaires

Si vous souhaitez en savoir plus sur la création d'agents, consultez les ressources suivantes :

• Documentation ADK
• Créer des outils personnalisés pour les agents

Félicitations !

Dans cet atelier, vous avez appris à structurer un projet Python pour le déployer à l'aide de l'interface de ligne de commande ADK, à implémenter un workflow multi-agent, à vous connecter à un serveur MCP distant pour utiliser ses outils, à enrichir des données internes en intégrant des outils externes comme l'API Wikipédia et à déployer l'agent en tant que conteneur sans serveur sur Cloud Run.

Dernière modification du manuel : 21 juillet 2026

Dernier test de l'atelier : 21 juillet 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.