Créer et déployer un agent ADK sur Cloud Run

1. Introduction

Cet atelier porte sur l'implémentation et le déploiement d'un service d'agent client. Vous utiliserez l'Agent Development Kit (ADK) pour créer un agent d'IA qui utilise des outils.

Dans cet atelier, nous allons créer un agent de zoo qui utilise Wikipédia pour répondre aux questions sur les animaux.

Enfin, nous déploierons l'agent de guide touristique sur Google Cloud Run, au lieu de l'exécuter uniquement en local.

Prérequis

• Un projet Google Cloud avec facturation activée.

Points abordés

• Comment structurer un projet Python pour le déploiement ADK.
• Implémenter un agent utilisant des outils avec google-adk
• Découvrez comment déployer une application Python en tant que conteneur sans serveur sur Cloud Run.
• Découvrez comment configurer une authentification sécurisée de service à service à l'aide de rôles IAM.
• Comment supprimer des ressources Cloud pour éviter d'encourir des frais à l'avenir.

Prérequis

• Un compte Google Cloud et un projet Google Cloud
• Un navigateur Web tel que Chrome

2. Pourquoi effectuer le déploiement sur Cloud Run ?

Cloud Run est un excellent choix pour héberger des agents ADK, car il s'agit d'une plate-forme sans serveur. Vous pouvez donc vous concentrer sur votre code et non sur la gestion de l'infrastructure sous-jacente. Nous nous occupons des tâches opérationnelles pour vous.

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 fonctionnalités

Exécutez des conteneurs n'importe où :

• 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 aucune personne n'utilise votre application, aucune instance n'est exécutée (l'application est mise à l'échelle sur zéro instance, ce qui est rentable).
• Si 1 000 requêtes sont envoyées, il crée autant de copies que nécessaire.

Sans état par défaut :

• Chaque requête peut être envoyée à une instance différente.
• Si vous avez besoin de stocker un état, utilisez un service externe tel que Cloud SQL, Firestore ou Memorystore.

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.

Payez seulement ce que vous utilisez :

• Facturation basée sur les requêtes : facturation par requête + temps de calcul (jusqu'à 100 ms).
• Facturation basée sur les instances : facturation pour toute la durée de vie de l'instance (aucun frais par requête).

3. Configuration du projet

Compte Google

Si vous ne possédez pas encore de compte Google personnel, vous devez en créer un.

Utilisez un compte personnel au lieu d'un compte professionnel ou scolaire.

Il est possible que des restrictions s'appliquent aux comptes professionnels et scolaires, ce qui vous empêche d'activer les API nécessaires pour cet atelier.

Se connecter à la console Google Cloud

Connectez-vous à la console Google Cloud à l'aide d'un compte Google personnel.

Activer la facturation

Configurer un compte de facturation personnel

Si vous avez configuré la facturation à l'aide de crédits Google Cloud, vous pouvez ignorer cette étape.

Pour configurer un compte de facturation personnel, cliquez ici pour activer la facturation dans la console Cloud.

Remarques :

• L'exécution de cet atelier devrait coûter moins de 1 USD en ressources Cloud.
• Vous pouvez suivre les étapes à la fin de cet atelier pour supprimer les ressources et éviter ainsi que des frais supplémentaires ne vous soient facturés.
• Les nouveaux utilisateurs peuvent bénéficier d'un essai sans frais pour un crédit de 300$.

Créer un projet (facultatif)

Si vous n'avez pas de projet que vous souhaitez utiliser pour cet atelier, créez-en un.

4. Ouvrir l'éditeur Cloud Shell

1. Cliquez sur ce lien pour accéder directement à l'éditeur Cloud Shell.
2. Si vous êtes invité à autoriser l'accès à un moment donné, cliquez sur Autoriser pour continuer.
3. Si le terminal ne s'affiche pas en bas de l'écran, ouvrez-le :
   • Cliquez sur Afficher.
   • Cliquez sur Terminal.

5. Activer les API

Pour utiliser Cloud Run, Artifact Registry, Cloud Build, Vertex AI et Compute Engine, vous devez activer leurs API respectives dans votre projet Google Cloud.

• Dans le terminal, activez les API :

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

  Une fois l'exécution terminée, un résultat semblable à celui-ci devrait s'afficher :

  Operation "operations/acat.p2-[GUID]" finished successfully.
  

Présentation des API

• L'API Admin Cloud Run (run.googleapis.com) vous permet d'exécuter des services de frontend et de backend, des jobs par lot ou des sites Web dans un environnement entièrement géré. Il gère l'infrastructure pour déployer et faire évoluer vos applications conteneurisées.
• L'API Artifact Registry (artifactregistry.googleapis.com) fournit un dépôt sécurisé et privé pour stocker vos images de conteneurs. Il s'agit de l'évolution de Container Registry, qui s'intègre parfaitement à Cloud Run et Cloud Build.
• L'API Cloud Build (cloudbuild.googleapis.com) est une plate-forme CI/CD sans serveur qui exécute vos compilations sur l'infrastructure Google Cloud. Il permet de créer votre image de conteneur dans le cloud à partir de votre Dockerfile.
• L'API Vertex AI (aiplatform.googleapis.com) permet à votre application déployée de communiquer avec les modèles Gemini pour effectuer des tâches d'IA de base. Elle fournit l'API unifiée pour tous les services d'IA de Google Cloud.
• L'API Compute Engine (compute.googleapis.com) fournit des machines virtuelles sécurisées et personnalisables qui s'exécutent sur l'infrastructure de Google. Bien que Cloud Run soit géré, l'API Compute Engine est souvent requise en tant que dépendance de base pour diverses ressources de mise en réseau et de calcul.

6. Préparer votre environnement de développement

Créez le répertoire.

1. Dans le terminal, créez le répertoire du projet et les sous-répertoires nécessaires :

   cd && mkdir zoo_guide_agent && cd zoo_guide_agent
   

2. Dans le terminal, exécutez la commande suivante pour ouvrir le répertoire zoo_guide_agent dans l'explorateur de l'éditeur Cloud Shell :

   cloudshell open-workspace ~/zoo_guide_agent
   

3. Le panneau de l'explorateur à gauche s'actualise. Le répertoire que vous avez créé devrait maintenant s'afficher.
   
   

   Si le terminal disparaît lorsque vous effectuez cette opération, vous pouvez le rouvrir en cliquant sur Afficher, puis sur Terminal dans le menu du haut.

Définir votre projet

1. Dans le terminal, définissez votre projet à l'aide de la commande suivante :

   gcloud config set project [PROJECT_ID]
   

   Exemple : gcloud config set project lab-project-id-example

   Si vous ne vous souvenez pas de votre ID de projet, vous pouvez l'obtenir en exécutant la commande suivante : gcloud projects list

   
2. Le message suivant doit s'afficher :

   Updated property [core/project].
   

   Si le message WARNING s'affiche et que vous êtes invité à Do you want to continue (Y/n)?, cela signifie probablement que vous avez saisi l'ID du projet de manière incorrecte. Appuyez sur n, puis sur Enter, et réessayez d'exécuter la commande gcloud config set project.

Installer les éléments requis

1. Exécutez la commande suivante dans le terminal pour créer le fichier requirements.txt.

   cloudshell edit requirements.txt
   

2. Ajoutez le contenu suivant au fichier requirements.txt que vous venez de créer.

   google-adk==1.14.0
   langchain-community==0.3.27
   wikipedia==1.4.0
   

3. Dans le terminal, créez et activez un environnement virtuel à l'aide d'uv. Cela garantit que les dépendances de votre projet ne sont pas en conflit avec le système Python.

   uv venv
   source .venv/bin/activate
   

   Remarque : Si votre session Cloud Shell est actualisée ou si vous ouvrez un nouvel onglet de terminal, vous devrez peut-être réactiver l'environnement virtuel en exécutant source .venv/bin/activate.

4. Installez les packages requis dans votre environnement virtuel dans le terminal.

   uv pip install -r requirements.txt
   

Configurer des variables d'environnement

• Utilisez la commande suivante dans le terminal pour créer le fichier .env.

  # 1. Set the variables in your terminal first
  PROJECT_ID=$(gcloud config get-value project)
  PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
  SA_NAME=lab2-cr-service
  
  # 2. Create the .env file using those variables
  cat <<EOF > .env
  PROJECT_ID=$PROJECT_ID
  PROJECT_NUMBER=$PROJECT_NUMBER
  SA_NAME=$SA_NAME
  SERVICE_ACCOUNT=${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com
  MODEL="gemini-2.5-flash"
  EOF
  

  Vérifiez le fichier .env et assurez-vous que des valeurs ont été attribuées à PROJECT_ID, PROJECT_NUMBER et SERVICE_ACCOUNT. S'il manque des informations sur le projet, exécutez gcloud projects list pour les trouver. Si le compte de service est manquant, vous pouvez lister les comptes de votre projet pour trouver l'adresse e-mail (elle doit se terminer par .iam.gserviceaccount.com) en exécutant la commande suivante : gcloud iam service-accounts list.

7. Créer un workflow d'agent

Créer un fichier __init__.py

1. Créez le fichier init.py en exécutant la commande suivante dans le terminal :

   cloudshell edit __init__.py
   

   Ce fichier indique à Python que le répertoire zoo_guide_agent est un package.
2. Ajoutez le code suivant au nouveau fichier __init__.py :

   from . import agent
   

Créer le fichier agent.py

1. Créez le fichier agent.py principal en collant la commande suivante dans le terminal.

   cloudshell edit agent.py
   

2. Importations et configuration initiale : ajoutez le code suivant à votre fichier agent.py actuellement vide :

   import os
   import logging
   import google.cloud.logging
   from dotenv import load_dotenv
   
   from google.adk import Agent
   from google.adk.agents import SequentialAgent
   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")
   

   Ce premier bloc du fichier agent.py importe toutes les bibliothèques nécessaires à partir de l'ADK et de 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 à votre modèle et à l'URL du serveur.
3. Définissez les outils : un agent n'est efficace que s'il peut utiliser les outils appropriés. Ajoutez le code suivant en bas de agent.py pour définir les outils :

   # 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 Wikipedia Tool
   wikipedia_tool = LangchainTool(
       tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())
   )
   

   Présentation des outils
   • add_prompt_to_state 📝 : cet outil se souvient de ce que demande un visiteur 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 : il s'agit d'une fonction Python qui écrit la requête du visiteur dans le dictionnaire tool_context.state partagé. Ce dictionnaire représente la mémoire à court terme de l'agent pour une conversation unique. Les données enregistrées dans l'état de session par un agent peuvent être lues par l'agent suivant dans le workflow.
   • LangchainTool 🌍 : donne à l'agent 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 à notre agent d'utiliser l'outil WikipediaQueryRun prédéfini de la bibliothèque LangChain.
     
     
4. Définissez les agents spécialisés : ajoutez le code suivant en bas de agent.py pour définir les agents comprehensive_researcher et response_formatter :

   # 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=[
           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 }
       """
   )
   

   • L'agent comprehensive_researcher est le "cerveau" de notre opération. Il prend la requête de l'utilisateur à partir de State partagé, l'examine avec l'outil Wikipédia et décide lesquels utiliser pour trouver la réponse.
   • Le rôle de l'agent response_formatter est la présentation. Il prend les données brutes collectées par l'agent Researcher (transmises via l'état) et utilise les compétences linguistiques du LLM pour les transformer en une réponse conviviale et conversationnelle.
     
5. Définissez l'agent Workflow : ajoutez ce bloc de code au bas de agent.py pour définir l'agent séquentiel tour_guide_workflow :

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

   L'agent de workflow agit comme le responsable du back-office pour la visite du zoo. Il prend en charge la demande de recherche et s'assure que les deux agents que nous avons définis ci-dessus effectuent leur travail dans le bon ordre : d'abord la recherche, puis la mise en forme. Cela permet de créer un processus prévisible et fiable pour répondre à la question d'un visiteur.
   Comment : il s'agit d'un SequentialAgent, un type spécial d'agent qui ne réfléchit pas par lui-même. Son seul rôle est d'exécuter une liste de sub_agents (le chercheur et le formateur) dans une séquence fixe, en transmettant automatiquement la mémoire partagée de l'un à l'autre.
6. Assemblez le workflow principal : ajoutez ce dernier bloc de code en bas de agent.py pour définir root_agent :

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

   Le framework ADK utilise root_agent comme point de départ pour toutes les nouvelles conversations. Son rôle principal est d'orchestrer l'ensemble du processus. Il agit comme le contrôleur initial qui gère le premier tour de la conversation.
   

Fichier agent.py complet

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.

Le fichier complet doit se présenter comme suit :

import os
import logging
import google.cloud.logging
from dotenv import load_dotenv

from google.adk import Agent
from google.adk.agents import SequentialAgent
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")

# 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 Wikipedia Tool
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())
)

# 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=[
        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 }
    """
)

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

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

Passons maintenant au déploiement.

8. Préparer l'application pour le déploiement

Vérifier la structure finale

Avant de déployer votre projet, vérifiez que son répertoire contient les fichiers appropriés.

• Assurez-vous que votre dossier zoo_guide_agent se présente comme suit :

  zoo_guide_agent/
  ├── .env
  ├── __init__.py
  ├── agent.py
  └── requirements.txt
  

Configurer les autorisations IAM

Une fois votre code local prêt, l'étape suivante consiste à configurer l'identité que votre agent utilisera dans le cloud.

1. Dans le terminal, chargez les variables dans votre session d'interface système.

   source .env
   

   Remarque : Si votre session Cloud Shell est actualisée ou si vous ouvrez un nouvel onglet de terminal, vous devrez peut-être exécuter à nouveau source .env pour recharger ces variables.

2. Créez un compte de service dédié à votre service Cloud Run afin qu'il dispose de ses propres autorisations spécifiques. Collez le code suivant dans le terminal :

   gcloud iam service-accounts create ${SA_NAME} \
       --display-name="Service Account for lab 2 "
   

   En créant une identité dédiée pour cette application spécifique, vous vous assurez que l'agent ne dispose que des autorisations exactes dont il a besoin, au lieu d'utiliser un compte par défaut avec un accès trop étendu.
3. Attribuez le rôle Utilisateur Vertex AI au compte de service, ce qui lui permet d'appeler les modèles de Google.

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

9. 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. Vous utiliserez la commande adk deploy cloud_run, un outil pratique qui automatise l'ensemble du workflow de déploiement. Cette commande unique met votre code en package, crée une image de conteneur, la transfère vers Artifact Registry et lance le service sur Cloud Run, le rendant accessible sur le Web.

1. Exécutez la commande suivante dans le terminal pour déployer votre agent.

   # Run the deployment command
   uvx --from google-adk \
   adk deploy cloud_run \
     --project=$PROJECT_ID \
     --region=europe-west1 \
     --service_name=zoo-tour-guide \
     --with_ui \
     . \
     -- \
     --labels=dev-tutorial=codelab-adk \
     --service-account=$SERVICE_ACCOUNT
   

   La commande uvx permet d'exécuter des outils de ligne de commande (publiés en tant que packages Python) sans nécessiter leur installation globale.

   Remarque : L'exécution de la commande de déploiement ci-dessous prendra quelques minutes.

2. Si le message suivant s'affiche :

   Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region 
   [europe-west1] will be created.
   
   Do you want to continue (Y/n)?
   

   Si c'est le cas, saisissez Y et appuyez sur ENTRÉE.
3. Si le message suivant s'affiche :

   Allow unauthenticated invocations to [your-service-name] (y/N)?.
   

   Saisissez y, puis appuyez sur ENTRÉE. Cela permet les appels non authentifiés pour cet atelier afin de faciliter les tests.

   Remarque : Toute personne disposant de l'URL aura accès à cet agent. Cette option est donc idéale pour les tests.

   Une fois l'exécution réussie, la commande fournit l'URL du service Cloud Run déployé. (Elle devrait ressembler à ceci : https://zoo-tour-guide-123456789.europe-west1.run.app.)
4. Copiez l'URL du service Cloud Run déployé pour la tâche suivante.

10. Tester l'agent déployé

Maintenant que votre agent est actif sur Cloud Run, effectuez un test pour vérifier que le déploiement a réussi et que l'agent fonctionne comme prévu. Vous utiliserez l'URL du service public (par exemple, https://zoo-tour-guide-123456789.europe-west1.run.app/) pour accéder à l'interface Web de l'ADK et interagir avec l'agent.

1. Ouvrez l'URL publique du service Cloud Run dans votre navigateur Web. Comme vous avez utilisé --with_ui flag, l'UI de développement ADK devrait s'afficher.
2. En haut à droite, activez Token Streaming.
    Vous pouvez maintenant interagir avec l'agent du zoo.
3. Saisissez hello et appuyez sur Entrée pour démarrer une nouvelle conversation.
4. Observez le résultat. L'agent doit répondre rapidement en vous saluant, par exemple :

   "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?"
   

5. Posez des questions à l'agent, par exemple :

   Where can I find the polar bears in the zoo and what is their diet?
   

   

Présentation du flux d'agents

Votre système fonctionne comme une équipe multi-agents intelligente. 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'agent d'accueil du zoo (bureau d'accueil)

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

• 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, "je veux en savoir plus sur les 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 super-chercheur)

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 capacité d'utilisation d'outils du modèle de langage pour déterminer s'il a besoin de :
  • des informations générales issues du Web (via l'API Wikipédia) ;
  • ou des deux, pour les questions complexes.

3. Le formateur de 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 informations 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.

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

1. Documentation ADK
2. Créer des outils personnalisés pour les agents ADK

11. Nettoyer l'environnement

Pour éviter que les ressources utilisées lors de ce tutoriel soient facturées sur votre compte Google Cloud, supprimez le projet contenant les ressources, ou conservez le projet et supprimez chaque ressource individuellement.

Supprimer les services et les images Cloud Run

Si vous souhaitez conserver le projet Google Cloud, mais supprimer les ressources spécifiques créées dans cet atelier, vous devez supprimer à la fois le service en cours d'exécution et l'image de conteneur stockée dans le registre.

• Exécutez les commandes suivantes dans le terminal :

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

Supprimer le projet (facultatif)

Si vous avez créé un projet spécifiquement pour cet atelier et que vous ne prévoyez pas de l'utiliser à nouveau, le moyen le plus simple d'effectuer un nettoyage consiste à supprimer l'intégralité du projet. Cela garantit la suppression complète de toutes les ressources (y compris le compte de service et les artefacts de compilation masqués).

• Dans le terminal, exécutez la commande suivante (remplacez [YOUR_PROJECT_ID] par l'ID de votre projet) :

  gcloud projects delete $PROJECT_ID
  

  La suppression d'un projet est irréversible. Avant de continuer, assurez-vous que ce projet n'est pas utilisé pour d'autres tâches.

12. Félicitations

Vous avez réussi à créer et à déployer une application d'IA multi-agent sur Google Cloud.

Récapitulatif

Dans cet atelier, vous êtes passé d'un répertoire vide à un service d'IA en direct et accessible au public. Voici un aperçu de ce que vous avez créé :

• Vous avez créé une équipe spécialisée : au lieu d'une IA générique, vous avez créé un "chercheur" pour trouver des faits et un "formateur" pour peaufiner la réponse.
• Vous leur avez fourni des outils : vous avez connecté vos agents au monde extérieur à l'aide de l'API Wikipédia.
• Vous avez déployé votre code : vous avez pris votre code Python local et l'avez déployé en tant que conteneur sans serveur sur Cloud Run, en le sécurisant avec un compte de service dédié.

Points abordés

• Comment structurer un projet Python pour le déploiement avec l'ADK.
• Découvrez comment implémenter un workflow multi-agent à l'aide de [SequentialAgent](https://google.github.io/adk-docs/agents/workflow-agents/sequential-agents/).
• Intégrer des outils externes tels que l'API Wikipédia
• Comment déployer un agent sur Cloud Run à l'aide de la commande adk deploy.

13. Enquête

Résultat :

Comment allez-vous utiliser ce tutoriel ?

Je vais le lire uniquement Je vais le lire et effectuer les exercices