GENAI129

Présentation

Au cours de cet atelier, vous démontrerez votre capacité à créer des agents à l'aide de l'Agent Development Kit (ADK), à les déployer dans Agent Runtime et à les exploiter depuis une application Web.

Objectif

Au cours de cet atelier, vous allez :

• Créer un agent avec Agent Development Kit (ADK) composé d'un agent racine et de sous-agents
• Permettre aux agents d'utiliser un outil Agent Search et des fonctions Python utilisées comme outils
• Stocker la sortie de l'agent dans l'état de la session et récupérer les valeurs de l'état de la session pour les instructions d'agent suivantes
• Déployer l'agent dans Agent Runtime
• Interroger l'agent déployé dans Agent Runtime

Supports d'apprentissage associés

Si vous souhaitez trouver des ressources qui vous aideront à développer les compétences nécessaires pour réussir cet atelier, consultez les sections pertinentes ci-dessous :

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, si nécessaire

2. Cliquez sur Ouvrir la console Google Cloud (ou effectuez un clic droit et sélectionnez Ouvrir le lien dans une fenêtre en navigation privée si vous utilisez 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. N'utilisez pas les identifiants de votre compte Google Cloud. Remarque : Si vous utilisez votre propre compte Google Cloud pour cet atelier, des frais supplémentaires pourront 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.

Scénario du challenge

L'un de vos collègues a commencé à développer un agent qu'il a appelé Paint Agent. Cet agent a pour objectif d'aider les utilisateurs à :

• sélectionner un produit de peinture à partir des fiches techniques des produits Cymbal Shops ;
• choisir une couleur dans la gamme de produits sélectionnée ;
• déterminer la quantité de peinture nécessaire en fonction des dimensions des pièces ;
• calculer le prix selon les options retenues.

Malheureusement, votre collègue a rencontré un bug, puis il a quitté l'entreprise.

En tant que nouvel ingénieur en ML chez Cymbal Shops, votre mission est de finaliser et de déployer Paint Agent. L'agent est structuré comme ceci :

Tâche 1 : Créer une application Agent Search des informations relatives aux produits de peinture

Dans cette tâche, vous allez déployer un datastore Agent Search. Ce datastore importera une fiche technique décrivant les produits de peinture de Cymbal Shops. Vous pouvez prévisualiser ce document dans un onglet de votre fenêtre de navigation privée à l'adresse https://storage.cloud.google.com/-bucket/Cymbal_Shops_Paint_Datasheets.pdf. Cette fiche technique servira de source de données de référence pour les requêtes des utilisateurs concernant vos peintures.

Un datastore et une application de recherche permettent à votre agent de trouver rapidement le contenu de votre organisation. Il peut ensuite utiliser ces informations pour fournir une réponse appropriée à l'utilisateur en fonction de vos données.

1. Dans la console Google Cloud, accédez à Agent Platform > Agents > Recherche.

2. Créez une application Agent Search avec la configuration suivante :

   Champ	Valeur
   Type d'application	Recherche personnalisée (général)
   Nom de l'application	Paint Search
   Nom de l'entreprise	Cymbal Shops
   Emplacement	mondial

3. Créez un datastore Agent Search avec la configuration suivante :

   Champ	Valeur
   Source de données	Cloud Storage
   Type de données	Documents
   Dossier ou fichier	Fichier
   Fichier à importer	-bucket/Cymbal_Shops_Paint_Datasheets.pdf
   Emplacement	mondial
   Nom du datastore	Cymbal Paint
   Analyseur de documents	Analyseur de mise en page
   Activer l'annotation de tables	Activé
   Inclure les en-têtes d'ancêtres dans les fragments	Activé

4. Sélectionnez Général comme modèle de tarification pour l'application et le datastore.

Cliquez sur Vérifier ma progression pour valider l'objectif. Créer un datastore et une application de recherche

Tâche 2 : Installer ADK et configurer votre environnement

Dans cet environnement d'atelier, l'API Agent Platform a été activée pour vous. Si vous deviez suivre ces étapes dans votre propre projet, vous pourriez les activer en accédant à Agent Platform et en suivant le prompt.

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

1. Dans la barre de titre de la console Google Cloud, cliquez sur Activer Cloud Shell ().

   Remarque  : Vous pouvez également sélectionner l'onglet du navigateur de la console, puis appuyer sur G, puis sur S pour ouvrir le terminal Cloud Shell.

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 en forme de crayon 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 de l'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 Qwiklabs.

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

1. Collez la commande suivante dans le terminal Cloud Shell afin de copier les fichiers d'un bucket Cloud Storage. Un répertoire de projet contenant le code pour cet atelier sera ainsi créé :

   gcloud storage cp -r gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/adk_challenge_lab . 2> /dev/null

2. Mettez à jour votre variable d'environnement PATH et installez ADK ainsi que les autres éléments requis pour l'atelier en exécutant les commandes suivantes dans le terminal Cloud Shell.

   export PATH=$PATH:"/home/${USER}/.local/bin" python3 -m pip install -r adk_challenge_lab/requirements.txt python3 -m pip install chainlit==2.11.1

3. Copiez les commandes suivantes dans un fichier texte. Remplacez la valeur YOUR_ID de SEARCH_ENGINE_ID par l'ID du moteur de recherche que vous venez de créer (il ressemble à paint-search_1756... et se trouve dans la liste des applications dans Agent Platform > Agents > Recherche) :

   cd ~/adk_challenge_lab cat << EOF > .env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}} GOOGLE_CLOUD_LOCATION={{{project_0.default_region| GCP_LOCATION}}} RESOURCES_BUCKET={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} SEARCH_ENGINE_ID=YOUR_ID EOF

4. Après les avoir modifiées, exécutez les commandes dans le terminal Cloud Shell pour créer un fichier .env contenant les variables d'authentification et de configuration du modèle. [Remarque : Pour afficher un fichier caché (c'est-à-dire un fichier commençant par un point), accédez aux menus de l'éditeur Cloud Shell et activez Affichage > Afficher/Masquer les fichiers cachés.]

5. Copiez le fichier .env dans le répertoire de l'agent pour fournir à l'agent les configurations d'authentification nécessaires une fois qu'il est déployé :

   cp .env paint_agent/.env

Tâche 3 : Déboguer Paint Agent

Un de vos collègues a commencé à travailler sur Paint Agent, mais s'est retrouvé bloqué. Pour terminer et déployer l'agent, vous devez reprendre le travail là où il l'a laissé. Cela implique de corriger un bug qu'il n'a pas résolu.

1. Dans le terminal Cloud Shell, exécutez la version actuelle de l'agent avec la commande suivante :

   adk run paint_agent

2. Lorsque l'invite [user]: s'affiche, saisissez la commande :

   bonjour

   Si l'agent vous demande si vous souhaitez en savoir plus sur les peintures Cymbal Shops, répondez :

   oui

   Le résultat attendu se termine par :

   ... google.genai.errors.ClientError: 400 INVALID_ARGUMENT. {'error': {'code': 400, 'message': 'Multiple tools are supported only when they are all search tools.', 'status': 'INVALID_ARGUMENT'}}

   Vous allez résoudre cette erreur lors des prochaines étapes.

3. Ouvrez le fichier adk_challenge_lab/paint_agent/agent.py et examinez les listes de sous-agents et d'outils utilisés par root_agent. Vous constatez que cela inclut plusieurs sous-agents. Le transfert vers des sous-agents appelle implicitement un outil transfer_to_agent.

4. L'outil de root_agent n'est pas un outil de recherche. Par conséquent, au moins l'un des sous-agents doit appeler un outil de recherche. Explorez les sous-agents du répertoire sub_agents pour trouver l'outil de recherche utilisé (dans ce cas, VertexAiSearchTool) :

   Contrôle des connaissances (la réponse s'affiche au fur et à mesure) :

5. Même si un outil de recherche ne peut pas être combiné à d'autres outils non liés à la recherche au sein d'un agent (y compris via un sous-agent, comme dans ce cas), ADK propose un outil nommé AgentTool qui peut encapsuler un agent isolé utilisant un outil de recherche. Cet agent-outil peut ensuite être utilisé conjointement avec d'autres outils.

   Revenez au fichier adk_challenge_lab/paint_agent/agent.py de root_agent et ajoutez AgentTool() à la liste des outils de l'agent racine. Fournissez les arguments suivants à AgentTool() :

   • agent doit être défini sur search_agent (le sous-agent qui utilise l'outil de recherche que vous avez découvert ci-dessus).
   • skip_summarization doit être défini sur False, car vous souhaitez que l'agent génère un rapport sur les résultats renvoyés par l'outil de recherche.

6. Supprimez ce sous-agent de la liste sub_agents.

7. Enregistrez le fichier.

   Remarque : Ne continuez l'atelier que lorsque votre datastore a été créé et votre document indexé. Pour suivre l'avancement, accédez au datastore Agent Platform > Agents > Search > Datastores > Cymbal Paint, sous l'onglet Documents.

   En pratique, vous obtiendrez un résultat plus fiable si vous attendez quelques minutes après que l'état indique "Prêt" avant d'interroger votre agent.

8. Dans le terminal Cloud Shell, exécutez à nouveau l'agent avec la commande suivante :

   adk run paint_agent

   Vous devriez maintenant pouvoir discuter avec l'agent et obtenir des informations sur les produits de peinture de Cymbal Shops.

9. Demandez à l'agent le prix des peintures EcoGreens et Forever Paint.

   
   

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

10. Lorsque vous avez terminé de discuter avec l'agent dans l'interface de ligne de commande, saisissez exit pour mettre fin à la conversation.

Tâche 4 : Enregistrer et utiliser l'état partagé

Votre root_agent importe et utilise un outil set_session_value depuis adk_challenge_lab/paint_agent/tools.py. L'objectif est de collecter des informations telles que SELECTED_PAINT et COVERAGE_RATE auprès de l'utilisateur, de les stocker dans la session et de les utiliser dans le chat multitour. Cependant, elle n'est pas entièrement implémentée.

1. Mettez à jour la fonction set_session_value dans le fichier adk_challenge_lab/paint_agent/tools.py pour stocker les paires clé-valeur dans le dictionnaire state de ToolContext.

2. Mettez à jour la réponse de la fonction pour renvoyer un message d'état f"stored '{value}' in '{key}'".

3. Ouvrez le fichier agent.py associé à l'agent coverage_calculator_agent (sous-agent de room_planner, qui est lui-même un sous-agent de votre root_agent).

4. Vous pouvez constater que ses instructions ne chargent pas correctement les valeurs du dictionnaire d'état. Mettez à jour l'instruction pour remplacer les termes en MAJUSCULES par la fonctionnalité de modèles de clé de l'ADK afin de charger les valeurs d'état dans les instructions. Utilisez la syntaxe facultative (par exemple, {SELECTED_PAINT?}) pour vous assurer que l'agent ne plante pas s'il est appelé avant qu'une clé d'état ne soit renseignée.

5. Testez votre agent en exécutant la commande suivante :

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

6. Sélectionnez paint_agent.

7. Vous devriez maintenant pouvoir avoir la conversation suivante avec votre agent :

   Vous	Réponse de l'agent
   bonjour	[Propose de partager des informations sur les peintures Cymbal Shops.]
   oui	[Partage des informations sur les produits de peinture, à savoir Project Paint, EcoGreens, SureCoverage, Forever Paint.]
   J'aimerais utiliser la gamme EcoGreens.	[L'onglet State doit afficher les valeurs d'état mises à jour. Demande le nombre de pièces et leurs noms.]
   Une seule pièce, mon bureau.	[Vous demande de choisir une couleur pour votre bureau.]
   Deep Ocean	[Vous demande les dimensions de la pièce.]
   3 m sur 4 m. 3 m de haut. 1 porte, 2 fenêtres.	[Demande le nombre de couches.]
   Deux couches.	[Calcule que vous aurez besoin de couvrir 74 mètres carrés.]

   Remarque : Pour que les images des produits s'affichent correctement, veuillez activer les cookies tiers pour ce domaine dans les paramètres du navigateur et actualiser la page.

8. Lorsque vous avez terminé de discuter avec votre agent, vous pouvez fermer l'onglet du navigateur de l'UI de développement.

   Cliquez sur Vérifier ma progression pour valider l'objectif. Définir et utiliser l'état de session

9. Sélectionnez le panneau du terminal Cloud Shell et appuyez sur CTRL+C pour arrêter le serveur.

Tâche 5 : Déployer dans Agent Runtime

1. Dans le terminal Cloud Shell, assurez-vous d'être dans le répertoire adk_challenge_lab :

   cd ~/adk_challenge_lab

2. Déployez votre agent dans Agent Runtime à l'aide de la commande adk deploy agent_engine. Vous devez inclure le répertoire d'agent comme dernier argument positionnel (par exemple, si vous êtes actuellement dans le répertoire). Utilisez l'argument suivant :

   Paramètre	Argument
   --display_name	"Paint Agent"

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

3. Pendant le déploiement de l'agent, attribuez les rôles IAM Utilisateur Agent Platform et Utilisateur Discovery Engine au compte de service .

4. Notez qu'une fois le déploiement terminé, le nom de ressource de l'agent déployé s'affiche dans la console.

   Cliquez sur Vérifier ma progression pour valider l'objectif. Déployer dans Agent Runtime

Tâche 6 : Interroger l'agent déployé

1. Dans le fichier adk_challenge_lab/chainlit_ui/app.py, recherchez la ligne ci-dessous et insérez le nom de ressource de l'agent que vous avez déployé afin de charger votre agent distant :

   agent = client.agent_engines.get(name='YOUR_AGENT_RESOURCE_NAME')

2. Exécutez l'UI avec la commande suivante :

   cd ~/adk_challenge_lab/chainlit_ui chainlit run app.py

   Résultat attendu :

   2025-08-25 12:30:00 - Your app is available at http://localhost:8000

3. Cliquez sur le lien http://localhost:8000 pour l'ouvrir dans un nouvel onglet de navigateur.

4. Engagez la conversation suivante avec l'agent déployé :

   Vous	Réponse de l'agent
   bonjour	[Propose de partager des informations sur les peintures Cymbal Shops.]
   oui	[Partage des informations sur les produits de peinture, à savoir Project Paint, EcoGreens, SureCoverage, Forever Paint.]
   J'aimerais utiliser Forever Paint.	[Demande le nombre de pièces et leurs noms.]
   Deux pièces. Le salon et la chambre de bébé.	[Vous demande de choisir une couleur pour votre salon et la chambre de bébé.]
   "Sunlight through a canvas tent" pour la chambre de bébé et "Coffee Cream" pour le salon.	[Vous demande les dimensions de la pièce.]
   Le salon mesure 5 mètres sur 4. 2,5 m de hauteur. 1 porte, 3 fenêtres.	[Demande le nombre de couches.]
   Deux couches.	[Demande les dimensions de la chambre de bébé.]
   La chambre du bébé mesure 3 mètres sur 3 mètres. 2,5 m de hauteur. 1 porte, 1 fenêtre.	[Fournit une estimation pour une couche et confirme le nombre de couches nécessaires.]
   Toujours deux couches.	[Calcule que vous aurez besoin de couvrir 77 mètres carrés pour le salon et 53 mètres carrés pour la chambre de bébé.]

5. Si vous souhaitez démarrer une nouvelle conversation avec votre agent, vous pouvez cliquer sur l'icône en haut à gauche.

   Cliquez sur Vérifier ma progression pour valider l'objectif. Configurer une interface pour interroger votre agent

Félicitations !

Dans cet atelier, vous avez effectué les tâches suivantes :

• Créer un agent avec Agent Development Kit (ADK) composé d'un agent racine et de sous-agents
• Permettre aux agents d'utiliser un outil Agent Search et des fonctions Python utilisées comme outils
• Stocker la sortie de l'agent dans un dictionnaire d'état de session, puis récupérer les valeurs de ce dictionnaire pour les instructions d'agent suivantes
• Déployer votre agent dans Agent Runtime
• Interroger l'agent déployé dans Agent Runtime

Formations et certifications Google Cloud

Les formations et certifications Google Cloud vous aident à tirer pleinement parti des technologies Google Cloud. Nos cours portent sur les compétences techniques et les bonnes pratiques à suivre pour être rapidement opérationnel et poursuivre votre apprentissage. Nous proposons des formations pour tous les niveaux, à la demande, en salle et à distance, pour nous adapter aux emplois du temps de chacun. Les certifications vous permettent de valider et de démontrer vos compétences et votre expérience en matière de technologies Google Cloud.

Dernière mise à jour du manuel : 2 juillet 2026

Dernier test de l'atelier : 2 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 de société et de produit peuvent être des marques des sociétés auxquelles ils sont associés.