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 allez utiliser l'Agent Development Kit (ADK) pour créer un agent 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.

De gauche à droite, un lion, deux pingouins, une personne portant un chapeau de safari, un éléphant et un ours se tiennent dos au spectateur, regardant une grande fusée rouge et blanche s'élancer dans un ciel bleu avec des nuages blancs. Deux plus petites fusées sont également visibles au loin. La scène se déroule dans un enclos de zoo avec une clôture en bois et des falaises rocheuses.

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

Prérequis

Un projet Google Cloud avec facturation activée.

Points abordés

Structurer un projet Python pour le déployer avec 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.
Configurer une authentification sécurisée de service à service à l'aide de rôles IAM
Comment supprimer les ressources Cloud pour éviter d'accumuler des coûts

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 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. Nous gérons 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 fonctionnalités

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 (l'application est mise à l'échelle sur zéro instance, ce qui est économique).
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 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 (avec une précision à 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.

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 des frais supplémentaires.
Les nouveaux utilisateurs peuvent bénéficier d'un essai sans frais pour bénéficier d'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

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

5. Définir votre projet

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

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

7. Préparer votre environnement de développement

Créez le répertoire.

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

Installer les éléments requis

Exécutez la commande suivante dans le terminal pour créer le fichier requirements.txt.
```
cloudshell edit requirements.txt
```
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
```
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.
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.

8. Créer un workflow d'agent

Créer un fichier `init.py`

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.
Ajoutez le code suivant au nouveau fichier __init__.py :
```
from . import agent
```

Créer le fichier `agent.py`

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

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 depuis l'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.

Définissez les outils : un agent n'est efficace que s'il dispose des bons outils. Ajoutez le code suivant à la fin 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 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 la requête 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 de session par un agent peuvent être lues par l'agent suivant dans le workflow.
- 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.

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 interprète le prompt de l'utilisateur à partir de l'State partagé, interroge l'outil Wikipédia et détermine celui qu'il doit utiliser pour trouver la réponse.
Le rôle de l'agent response_formatter est la présentation. Son rôle est de transformer les données brutes collectées par l'agent de recherche (transmises via l'état de session) en réponse conviviale et conversationnelle en utilisant les compétences linguistiques du LLM.

Définissez l'agent Workflow : ajoutez ce bloc de code à la fin 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 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 nous avons définis ci-dessus interviennent dans le bon ordre : d'abord la recherche, puis la mise en forme. Il garantit que le processus consistant à répondre aux questions des visiteurs est fiable et rigoureux.
Comment ? Il s'agit d'un SequentialAgent, un type d'agent spécifique qui ne réfléchit pas par lui-même. Son seul rôle est d'exécuter une liste de sub_agents (l'agent de recherche et l'agent de mise en forme) dans un ordre fixe, en transmettant automatiquement la mémoire partagée de l'un à l'autre.

Assembler le workflow principal : ajoutez ce dernier bloc de code à la fin 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 le processus global. Il agit comme le contrôleur initial qui gère le premier tour de la conversation.

Trois robots sont représentés : un robot d'accueil à gauche écrit sur un bloc-notes avec une bulle de pensée représentant un lion, un robot chercheur au centre est assis à un bureau avec un ordinateur affichant des données et une flèche de requête pointant vers lui, et un robot présentateur à droite sourit en tenant un graphique intitulé "Données analysées", avec une flèche pointant vers lui depuis le robot chercheur. Des girafes et des éléphants sont visibles en arrière-plan, et des palmiers encadrent la scène.

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.

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

Maintenant que votre code local est prêt, vous devez configurer l'identité que votre agent utilisera dans le cloud.

Dans le terminal, chargez les variables dans votre session shell.
```
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.
Créez un compte de service dédié à votre service Cloud Run afin qu'il dispose de sa propre autorisation spécifique. 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.

Attribuez au compte de service le rôle Utilisateur Vertex AI, qui lui donne l'autorisation 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"

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

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

# Run the deployment command
uvx --from google-adk==1.14.0 \
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.

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.

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 peut accéder à cet agent. Il est donc recommandé de réserver cette approche aux 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.)
Copiez l'URL du service Cloud Run déployé pour la tâche suivante.

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

Ouvrez l'URL publique du service Cloud Run dans votre navigateur Web. Comme vous avez utilisé --with_ui flag, vous devriez voir l'UI de développement ADK.
En haut à droite, activez Token Streaming.
Vous pouvez maintenant interagir avec l'agent du zoo.
Saisissez hello et appuyez sur Entrée pour démarrer une nouvelle conversation.

Observez le résultat. L'agent doit répondre rapidement en présentant son message de bienvenue, qui devrait ressembler à ceci :

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

Posez des questions à l'agent, par exemple :

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

Capture d'écran de l'agent ADK effectuant une séquence d'actions : add_prompt_to_state, transfer_to_agent, wikipedia et get_animals_by_species.

La première réponse indique : "Je ne peux pas vous dire où trouver les ours polaires dans ce zoo en particulier, mais je peux vous parler de leur régime alimentaire." La deuxième réponse indique : "Les ours polaires se trouvent dans l'exposition arctique, sur le chemin polaire. Je ne parviens pas à récupérer d'informations sur son régime alimentaire avec les outils disponibles. La troisième réponse, la plus complète, indique : "Je serais ravi de vous parler de nos ours polaires ! Vous pouvez trouver nos ours polaires à l'exposition sur l'Arctique, sur le chemin polaire. Nous avons trois ours polaires ici : Snowflake, qui a sept ans. Blizzard, qui a cinq ans. Iceberg, qui a neuf ans. Les ours polaires sont principalement carnivores. Ils sont spécialisés dans la prédation des phoques, en particulier des phoques annelés. Ils mangent également des morses, des bélugas et certains animaux terrestres."

Explication du flux de l'agent

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'accueil du zoo ("La réception")

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

3. L'outil de mise en forme 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 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 :

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

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

Structurer un projet Python pour le déployer avec l'ADK
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.

14. Enquête

Résultat :

Comment allez-vous utiliser ce tutoriel ?

Je vais le lire uniquement

Je vais le lire et effectuer les exercices

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

1. Introduction

Prérequis

Points abordés

Prérequis

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

Principales fonctionnalités

Exécute des conteneurs partout :

Scaling automatique :

Sans état par défaut :

Compatible avec n'importe quel langage ou framework :

Payez seulement ce que vous utilisez :

3. Configuration du projet

Compte Google

Se connecter à la console Google Cloud

Activer la facturation

Configurer un compte de facturation personnel

Créer un projet (facultatif)

4. Ouvrir l'éditeur Cloud Shell

5. Définir votre projet

6. Activer les API

Présentation des API

7. Préparer votre environnement de développement

Créez le répertoire.

Installer les éléments requis

Configurer des variables d'environnement

8. Créer un workflow d'agent

Créer un fichier __init__.py

Créer le fichier agent.py

Fichier agent.py complet

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

Vérifier la structure finale

Configurer les autorisations IAM

10. Déployer l'agent à l'aide de la CLI ADK

11. Tester l'agent déployé

Explication du flux de l'agent

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

2. Le chercheur complet ("Le superchercheur")

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

12. Nettoyer l'environnement

Supprimer les services et les images Cloud Run

Supprimer le projet (facultatif)

13. Félicitations

Récapitulatif

Points abordés

14. Enquête

Comment allez-vous utiliser ce tutoriel ?

Créer un fichier `init.py`

Créer le fichier `agent.py`

Fichier `agent.py` complet