Créer des agents IA avec ADK : orchestrer les workflows d'agents

1. Présentation

Pour répondre à une demande de voyage soumise à plusieurs contraintes (par exemple, concevoir un itinéraire d'une journée complète à Kyoto pour moins de 100 $, axé sur les temples historiques et la cuisine locale, sans aucune galerie d'art moderne), il faut extraire les contraintes, rechercher des attractions et des restaurants en même temps, assembler un programme détaillé et vérifier le plan final. S'appuyer sur un seul agent monolithique doté de nombreux outils peut entraîner l'omission d'étapes de vérification ou le non-respect des exclusions. C'est pourquoi l'orchestration coordonne des sous-agents spécialisés via des contrôleurs de workflow déterministes.

Dans cette troisième partie de la série Créer des agents IA avec ADK, vous allez créer un planificateur de voyage multi-agent autonome sur Agent Platform à l'aide des contrôleurs de workflow d'Agent Development Kit (ADK) 2 (SequentialAgent, ParallelAgent et LoopAgent). En trois étapes progressives (sans configuration d'espace de travail pour la partie 1 ou 2), vous allez coordonner six agents spécialisés optimisés par gemini-3.8-flash avec un état de session partagé (output_key), une exécution google_search simultanée et une boucle d'amélioration itérative de type "maker-checker".

Vous débutez avec ADK ? Si vous ne connaissez pas du tout les concepts d'agent d'IA générative et Google Agent Development Kit (ADK), nous vous recommandons de commencer par suivre les cours Créer des agents IA avec ADK : les bases et Créer des agents IA avec ADK : exploiter les outils.

Vous souhaitez explorer les workflows de graphes ADK 2 ? Après avoir terminé cet atelier de programmation, passez à la partie 4, Créer des agents IA avec ADK : orchestrer des workflows de graphes, pour unifier l'orchestration séquentielle, parallèle (JoinNode) et cyclique (Event(route=...)) dans un seul graphe Workflow déclaratif.

Prérequis

• Comprendre les concepts de l'IA générative
• Maîtriser les bases de la programmation Python
• Connaissance des principes fondamentaux des agents IA et de Google ADK

Objectifs

• Comment créer un projet ADK 2 multi-agent à partir de zéro
• Concevoir une équipe d'agents spécialisés qui partagent l'état de la session à l'aide de output_key
• Utiliser SequentialAgent pour exécuter des sous-agents dans un pipeline déterministe par étapes
• Utiliser ParallelAgent pour exécuter simultanément des agents de recherche indépendants afin de réduire la latence
• Utiliser l'escalade LoopAgent et ToolContext pour implémenter une boucle d'affinement itérative de type "maker-checker"
• Combiner des modèles séquentiels, parallèles et en boucle dans un workflow multi-agent hiérarchique

Ce dont vous avez besoin

• Un compte Google (utilisez un compte @gmail.com personnel si vous demandez des crédits pour l'atelier)
• Un lien de crédit d'atelier fourni par votre formateur (ainsi que l'appareil photo d'un téléphone pour scanner le QR code) ou un compte de facturation Cloud actif
• Google Chrome (nous vous recommandons d'utiliser une fenêtre de navigation privée pour éviter de mélanger vos comptes personnel et professionnel)

Conseil pour la navigation privée : Ouvrez cet atelier de programmation dans une fenêtre de navigation privée pour que tous les liens vers la console Cloud et Cloud Shell s'ouvrent dans la même session.

2. Profiter de crédits Google Cloud (facultatif)

Si vous participez à un atelier avec un lien de crédit d'événement, demandez votre crédit Google Developer Program pour provisionner un compte de facturation sans carte de crédit.

Vous utilisez votre propre compte de facturation ? Passez à la section Créer un projet Google Cloud (facultatif) (ou Configurer votre environnement si vous avez déjà un projet). Si vous avez besoin d'un nouveau compte de facturation sans crédits d'événement, consultez Créer un compte de facturation Cloud ou Essai sans frais de Google Cloud.

Demander votre crédit pour l'événement

⚠️ Utilisez un compte Gmail personnel : les comptes Google Workspace d'entreprise ou scolaires ne peuvent pas demander de crédits pour les ateliers.

1. Ouvrez le lien du crédit de l'atelier dans une fenêtre de navigation privée et connectez-vous avec votre compte @gmail.com.
2. Sur la page Demander votre avantage, cliquez sur Demander un crédit :

3. Si vous êtes invité à créer un profil Google Developer Program, remplissez le formulaire.
4. Lorsque l'option Scanner pour confirmer que vous êtes une personne s'affiche, scannez le QR code avec votre téléphone et effectuez la validation (actualisez la page et cliquez à nouveau sur Demander un crédit si le QR code ne s'affiche pas) :

5. Vérifiez que le message Votre demande de crédit pour l'événement a bien été validée ! s'affiche, puis cliquez sur Ouvrir le compte de facturation :

🔍 Vérifiez votre travail

La configuration du compte de facturation prend jusqu'à trois minutes :

1. Ouvrez Google Cloud Billing (ou copiez l'URL dans votre fenêtre de navigation privée), puis sélectionnez Vos comptes de facturation :

https://console.cloud.google.com/billing

2. Actualisez la page jusqu'à ce que l'état de votre compte GDP Credit soit Actif :

3. Créer un projet Google Cloud (facultatif)

Créez un projet Google Cloud dédié afin que toutes les ressources de cet atelier de programmation restent isolées et faciles à nettoyer.

Vous avez déjà un projet ? Si vous disposez déjà d'un projet pour lequel la facturation est activée ou d'un projet d'atelier préprovisionné, passez à la section Configurer votre environnement.

1. Ouvrez Créer un projet (ou copiez l'URL dans votre fenêtre de navigation privée) :

https://console.cloud.google.com/projectcreate

2. Saisissez les détails de votre projet :
   • Nom du projet : par exemple, google-cloud-workshop
   • Compte de facturation (si affiché) : sélectionnez GDP Credit (ou votre compte de facturation actif).
   • Ressource parente : Aucune organisation (ou votre organisation, si nécessaire)
3. Notez l'ID du projet généré sous le nom du projet, puis cliquez sur Créer :

🔍 Vérifiez votre travail

Cliquez sur Notifications dans la barre d'outils en haut à droite, puis sur Sélectionner un projet une fois la création du projet terminée :

4. Configurer votre environnement

Configurez Google Cloud Shell, activez l'API Agent Platform et créez un environnement virtuel Python 3.12 isolé avec uv.

Vous avez déjà suivi les ateliers 1 et 2 ? (Fast-Track) : si l'ID de votre projet Google Cloud et l'API Agent Platform sont déjà configurés dans cette session Cloud Shell, passez à Créer un environnement virtuel Python et installer ADK pour que ~/adk-agents/.venv soit créé correctement.

Conseil pour le terminal local : Vous exécutez les commandes sur une machine locale plutôt que dans Cloud Shell ? Exécutez gcloud auth application-default login une fois, remplacez les commandes cloudshell edit filename par votre éditeur préféré (par exemple, code filename ou nano filename) et ouvrez http://localhost:8000 directement dans votre navigateur.

Configurer Cloud Shell

1. Cliquez sur Activer Cloud Shell (>_) dans la barre d'outils de la console Google Cloud ou ouvrez directement Google Cloud Shell (ou copiez l'URL dans votre fenêtre de navigation privée) :

https://shell.cloud.google.com/?show=ide,terminal

2. Si vous y êtes invité, cliquez sur Autoriser :

3. Sélectionnez l'ID de votre projet Google Cloud actif dans le menu numéroté de votre terminal :

unset CLOUDSDK_CORE_PROJECT
PS3="Select your project (e.g. 1): "
select PROJECT_ID in $(gcloud projects list --format="value(projectId)"); do
  [ -n "$PROJECT_ID" ] && gcloud config set project "$PROJECT_ID" && break
done

Un résultat semblable à celui-ci s'affiche (les projets sans tag affichent également une ligne d'informations [environment: untagged]) :

1) google-cloud-workshop-4210
2) my-cloud-project-8812
Select your project (e.g. 1): 1
Updated property [core/project].

Vérifiez que l'ID de projet sélectionné apparaît en jaune dans l'invite Cloud Shell :

Activer les API requises

Activez l'API Agent Platform pour que vos agents ADK puissent appeler des modèles Gemini :

gcloud services enable aiplatform.googleapis.com

Un résultat semblable à celui-ci s'affiche :

Operation "operations/acat.p2-..." finished successfully.

Créer un environnement virtuel Python et installer ADK

Pourquoi uv ? Écrit en Rust, uv crée des environnements Python et installe des packages en quelques secondes. Pour en savoir plus, consultez la documentation sur uv.

Créez l'espace de travail ~/adk-agents et activez un environnement virtuel Python 3.12 :

cd ~
mkdir -p adk-agents && cd ~/adk-agents

which uv >/dev/null 2>&1 || curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

uv venv .venv --python 3.12
source .venv/bin/activate

Vérifiez que le préfixe (.venv) s'affiche au début de l'invite de votre terminal :

Installez ADK 2 dans l'environnement virtuel actif :

uv pip install --no-cache "google-adk==2.14.0"

🔍 Vérifiez votre travail

Vérifiez la version de la CLI adk installée :

adk --version

Un résultat semblable à celui-ci s'affiche :

adk, version 2.14.0

Conseil pour récupérer la session : Si l'onglet Cloud Shell se déconnecte ou si vous ouvrez un nouveau terminal plus tard, revenez à votre espace de travail et réactivez l'environnement virtuel en exécutant cd ~/adk-agents && source .venv/bin/activate.

5. Créer l'agent de planification de voyage

Une fois votre environnement prêt, utilisez la commande adk create intégrée d'ADK pour générer les fichiers de démarrage de votre package d'agent travel_planner.

Générer le package de démarrage

Exécutez adk create à partir de votre répertoire ~/adk-agents :

cd ~/adk-agents
adk create travel_planner

Lorsque vous y êtes invité dans le terminal, sélectionnez les options de configuration suivantes (si vous êtes invité à saisir Enable telemetry? [Y/n]: lors de la première exécution, appuyez sur Entrée ou saisissez n, puis appuyez sur Entrée) :

1. Choisissez un modèle pour l'agent racine : saisissez 2 pour sélectionner gemini-3.8-flash (l'option 1 sélectionne gemini-3.5-flash), puis appuyez sur Entrée.
2. Choisissez un backend : saisissez 2 pour sélectionner le backend Agent Platform de Google Cloud (option 2 dans le menu de la CLI ci-dessous), puis appuyez sur Entrée.
3. Saisissez l'ID du projet Google Cloud : confirmez l'ID de votre projet affiché entre crochets en appuyant sur Entrée.
4. Saisissez la région Google Cloud : saisissez global, puis appuyez sur Entrée.

adk create écrit GOOGLE_GENAI_USE_ENTERPRISE=1, l'ID de votre projet et GOOGLE_CLOUD_LOCATION=global dans travel_planner/.env, de sorte que vos identifiants restent configurés lorsque vous mettrez à jour agent.py ultérieurement.

🔍 Vérifiez votre travail

Un résultat semblable à celui-ci s'affiche :

Choose a model for the root agent:
1. gemini-3.5-flash
2. gemini-3.8-flash
3. Other models (fill later)
Choose model (1, 2, 3): 2
1. Google AI
2. Vertex AI
3. Login with Google
Choose a backend (1, 2, 3): 2

You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai

Enter Google Cloud project ID [google-cloud-workshop-4210]:
Enter Google Cloud region [us-central1]: global

Agent created in /home/your_username/adk-agents/travel_planner:
- .env
- .gitignore
- __init__.py
- agent.py

⚠️  WARNING: Secrets (like GOOGLE_API_KEY) are stored in .env.

Next steps:
- Chat with your agent in the terminal: adk run travel_planner
- Or in the browser: adk web .
- Have your coding agent evaluate and deploy it: uvx google-agents-cli setup
  (other install options: https://adk.dev/get-started/agents-cli/)

Ouvrez le dossier actuel dans l'éditeur de code Cloud Shell pour pouvoir inspecter et modifier les fichiers à côté de votre terminal :

which cloudshell >/dev/null 2>&1 && cloudshell workspace ~/adk-agents || true

Remarque sur le redémarrage du terminal : L'exécution de cloudshell workspace recharge la vue de l'éditeur Cloud Shell. Une fois le volet du terminal actualisé, réactivez votre environnement virtuel avant de continuer :

cd ~/adk-agents
source .venv/bin/activate

Tester l'agent unique par défaut

Avant de créer des workflows agentiques multi-agents, lancez l'UI de développement ADK pour observer comment l'agent unique par défaut répond à une requête générale de planification de voyage :

cd ~/adk-agents
adk web --allow_origins "*"

Ouvrez l'UI de développement dans votre navigateur à l'aide de l'aperçu sur le Web de Cloud Shell :

1. Cliquez sur l'icône Aperçu sur le Web dans la barre d'outils en haut à droite de Cloud Shell.
2. Sélectionnez Modifier le port, saisissez 8000, puis cliquez sur Modifier et prévisualiser.

Une fois l'UI Web d'ADK chargée, envoyez un message de salutation, par exemple "hello, what can you do?" ou "Help me plan a trip to Japan" :

Notez que l'agent root_agent unique répond directement en une seule passe, sans extraction structurée des préférences, recherche en direct sur le Web ni vérification du budget.

Une fois les tests terminés, appuyez sur Ctrl + C dans votre terminal Cloud Shell pour arrêter le serveur adk web et revenir à l'invite de commande.

6. Créer un workflow SequentialAgent

Vous allez maintenant créer votre premier modèle d'orchestration : un workflow linéaire optimisé par SequentialAgent. Dans un pipeline séquentiel, les sous-agents s'exécutent dans un ordre strict. Le premier spécialiste extrait les paramètres structurés et les enregistre dans l'état de session partagé à l'aide de output_key="user_preferences", et le second spécialiste lit {user_preferences} à partir de l'état partagé pour rédiger l'itinéraire.

Créer les spécialistes initiaux (specialists.py)

Ouvrez un nouveau fichier nommé specialists.py dans travel_planner/ :

cloudshell edit ~/adk-agents/travel_planner/specialists.py

Collez le code suivant dans travel_planner/specialists.py pour définir user_profiler_agent et itinerary_synthesizer_agent (en important ToolContext et google_search au préalable pour les étapes suivantes) :

from google.adk import Agent
from google.adk.tools import ToolContext, google_search

# --- Specialist 1: The User Profiler ---
user_profiler_agent = Agent(
    name="user_profiler_agent",
    description="Extracts travel preferences and constraints from user input.",
    instruction="""
        Extract destination, duration (default 1 day), budget, interests, and exclusions.
        Return a single JSON object with keys: "destination", "duration", "budget", "interests", "exclusions".
    """,
    output_key="user_preferences",  # Saves output to state['user_preferences']
)

# --- Specialist 2: The Synthesizer ---
itinerary_synthesizer_agent = Agent(
    name="itinerary_synthesizer_agent",
    description="Compiles preferences and research into a final Markdown itinerary.",
    instruction="""
        You are an elite Travel Concierge. Write a Markdown itinerary with an itemized USD and local currency cost breakdown using:
        - User Preferences: {user_preferences}
        - Activities (if available): {activity_recommendations?}
        - Restaurants (if available): {restaurant_recommendations?}
    """,
    output_key="final_itinerary",
)

Héritage de modèle et transmission d'état dans l'ADK : les sous-agents dans SequentialAgent, ParallelAgent et LoopAgent héritent automatiquement du model configuré sur root_agent dans agent.py (gemini-3.8-flash). Vous définissez donc MODEL à un seul endroit au lieu de répéter model= sur chaque spécialiste. Définir output_key="user_preferences" sur user_profiler_agent stocke sa réponse sous session.state["user_preferences"], que les agents suivants injectent avec {user_preferences} (un ? de fin tel que {activity_recommendations?} marque un espace réservé d'état facultatif jusqu'à ce qu'il soit renseigné).

Câbler le pipeline séquentiel (workflows.py)

Créez un fichier nommé workflows.py dans travel_planner/ pour orchestrer les spécialistes :

cloudshell edit ~/adk-agents/travel_planner/workflows.py

Ajoutez la définition SequentialAgent suivante à travel_planner/workflows.py :

from google.adk.agents import SequentialAgent
from .specialists import (
    user_profiler_agent,
    itinerary_synthesizer_agent,
)

# 1. SEQUENTIAL PHASE: A linear two-step workflow
master_travel_agent = SequentialAgent(
    name="master_travel_agent",
    description="Orchestrates the end-to-end travel planning process for trip and itinerary requests.",
    sub_agents=[
        user_profiler_agent,         # Step 1: Extract constraints into user_preferences
        itinerary_synthesizer_agent,  # Step 2: Draft itinerary from user_preferences
    ],
)

Connecter le workflow à root_agent (agent.py)

Enregistrez maintenant master_travel_agent en tant que sous-agent de root_agent. Ouvrez travel_planner/agent.py :

cloudshell edit ~/adk-agents/travel_planner/agent.py

Remplacez le contenu du fichier travel_planner/agent.py par le code suivant :

from google.adk import Agent
from .workflows import master_travel_agent

MODEL = "gemini-3.8-flash"

root_agent = Agent(
    model=MODEL,
    name="root_agent",
    description="A helpful assistant for user questions.",
    instruction=(
        "Greet the user and delegate any travel or trip planning requests "
        "to master_travel_agent."
    ),
    sub_agents=[master_travel_agent],
)

🔍 Vérifiez votre travail

Démarrez l'UI Web ADK depuis votre terminal :

cd ~/adk-agents
adk web --allow_origins "*"

Ouvrez l'aperçu sur le Web sur le port 8000 et saisissez le prompt suivant :

Help me plan a trip to Kyoto

Un résultat semblable au flux d'exécution suivant doit s'afficher dans la vue Événements :

1. root_agent -> calls transfer_to_agent(agent_name="master_travel_agent")
2. user_profiler_agent -> outputs JSON {"destination": "Kyoto", "duration": "1 day", ...} to state['user_preferences']
3. itinerary_synthesizer_agent -> reads {user_preferences} and outputs the formatted Markdown itinerary

Cliquez sur un badge d'événement (ou sur l'icône State: final_itinerary), puis accédez à l'onglet State (État) dans le panneau d'inspection de gauche pour vérifier que user_preferences et final_itinerary sont tous deux renseignés dans l'état de la session.

Lorsque vous avez terminé d'inspecter la trace, appuyez sur Ctrl + C dans votre terminal pour arrêter adk web.

7. Effectuer des recherches avec ParallelAgent

Bien que le workflow séquentiel sépare clairement l'extraction des préférences de la rédaction de l'itinéraire, ses recommandations reposent toujours uniquement sur les connaissances statiques du modèle issues de l'entraînement. Vous pouvez ancrer l'itinéraire dans des données Web en direct en ajoutant deux chercheurs dédiés optimisés par l'outil google_search intégré :

• activity_finder_agent : trouve trois attractions spécifiques correspondant à la destination et aux centres d'intérêt de l'utilisateur, ainsi que le prix estimé des billets.
• restaurant_finder_agent : trouve trois restaurants locaux bien notés et leur coût estimé par personne.

Comme la recherche d'attractions et la recherche de restaurants ne dépendent pas l'une de l'autre, les exécuter l'une après l'autre fait perdre du temps. À la place, vous allez encapsuler les deux chercheurs dans un ParallelAgent (parallel_research_agent) afin qu'ADK exécute les deux workflows de recherche Google simultanément et renseigne {activity_recommendations?} et {restaurant_recommendations?} avant de passer à itinerary_synthesizer_agent.

Ajouter les spécialistes de la recherche parallèle à specialists.py

Ouvrez travel_planner/specialists.py :

cloudshell edit ~/adk-agents/travel_planner/specialists.py

Ajoutez les deux spécialistes de la recherche Google suivants en bas de travel_planner/specialists.py (juste en dessous de itinerary_synthesizer_agent) :

# --- Specialist 3: The Activity Finder ---
activity_finder_agent = Agent(
    name="activity_finder_agent",
    description="Finds 3 attractions matching the user's destination and interests.",
    instruction="""
        Based on {user_preferences}, use google_search to find 3 specific attractions (including budget-friendly options).
        Return a JSON list with keys: "attraction_name", "estimated_cost_local", "estimated_cost_usd", "notes".
    """,
    tools=[google_search],
    output_key="activity_recommendations",
)

# --- Specialist 4: The Restaurant Finder ---
restaurant_finder_agent = Agent(
    name="restaurant_finder_agent",
    description="Finds 3 restaurants matching the destination and budget.",
    instruction="""
        Based on {user_preferences}, use google_search to find 3 highly-rated restaurants across price points.
        Return a JSON list with keys: "restaurant_name", "cuisine", "estimated_cost_local", "estimated_cost_usd".
    """,
    tools=[google_search],
    output_key="restaurant_recommendations",
)

Bonus : Réutiliser get_fx_rate de l'atelier 2 (facultatif) : dans Créer des agents IA avec ADK : exploiter les outils, vous avez écrit une fonction Python get_fx_rate(base: str, target: str) simple pour récupérer les taux de change en direct depuis https://hexarate.paikama.co/api/rates/latest. En isolant google_search sur les deux spécialistes de la recherche (activity_finder_agent et restaurant_finder_agent) et en associant tools=[get_fx_rate] directement à itinerary_synthesizer_agent, chaque agent reste concentré sur une seule tâche (et la répartition reste portable même sur les anciens modèles Gemini, tandis que les modèles Gemini 3 et versions ultérieures permettent également de combiner des outils intégrés comme google_search avec des fonctions personnalisées sur un seul agent).

Insérer ParallelAgent dans workflows.py

Ouvrez travel_planner/workflows.py :

cloudshell edit ~/adk-agents/travel_planner/workflows.py

Mettez à jour travel_planner/workflows.py pour définir parallel_research_agent à l'aide de ParallelAgent et placez-le entre user_profiler_agent et itinerary_synthesizer_agent :

from google.adk.agents import ParallelAgent, SequentialAgent
from .specialists import (
    activity_finder_agent,
    itinerary_synthesizer_agent,
    restaurant_finder_agent,
    user_profiler_agent,
)

# Parallel branch: Run activity and restaurant research simultaneously
parallel_research_agent = ParallelAgent(
    name="parallel_research_agent",
    description="Runs activity and restaurant research concurrently.",
    sub_agents=[
        activity_finder_agent,
        restaurant_finder_agent,
    ],
)

# Master pipeline: Profile -> Parallel Research -> Synthesize
master_travel_agent = SequentialAgent(
    name="master_travel_agent",
    description="Orchestrates the end-to-end travel planning process for trip and itinerary requests.",
    sub_agents=[
        user_profiler_agent,          # Step 1: Extract constraints
        parallel_research_agent,      # Step 2: Research activities & restaurants in parallel
        itinerary_synthesizer_agent,  # Step 3: Synthesize into an itinerary
    ],
)

🔍 Vérifiez votre travail

Lancez à nouveau adk web pour tester le pipeline de recherche parallèle :

cd ~/adk-agents
adk web --allow_origins "*"

Dans l'UI de l'aperçu sur le Web, envoyez le prompt suivant :

Help me plan a trip to Kyoto focused on historic temples and ramen

Un résultat semblable à la séquence suivante doit s'afficher dans la vue Événements :

1. user_profiler_agent -> writes state['user_preferences']
2. parallel_research_agent -> fans out concurrently:
   - activity_finder_agent invokes google_search -> writes state['activity_recommendations']
   - restaurant_finder_agent invokes google_search -> writes state['restaurant_recommendations']
3. itinerary_synthesizer_agent -> merges all three state keys into state['final_itinerary']

Inspecter la simultanéité dans l'UI Web ADK : basculez entre ces vues dans l'UI Web ADK pour vérifier l'exécution en parallèle :

1. Vue "Traces" : cliquez sur Traces en haut du volet de conversation (à côté d'Événements) et inspectez votre tour. Vous verrez des périodes qui se chevauchent pour activity_finder_agent et restaurant_finder_agent sous parallel_research_agent, ce qui réduit de près de moitié la latence totale de la recherche sur le Web par rapport à une exécution séquentielle.
2. Onglet "State" (État) : cliquez sur l'onglet State (État) dans le panneau de l'inspecteur de gauche pour inspecter le dictionnaire de la session en direct (user_preferences, activity_recommendations, restaurant_recommendations et final_itinerary).

Une fois les tests terminés, appuyez sur Ctrl + C dans votre terminal pour arrêter adk web.

8. Peaufiner des brouillons avec LoopAgent

Même avec des résultats de recherche en direct, le brouillon initial produit par itinerary_synthesizer_agent peut dépasser le budget total de l'utilisateur ou inclure accidentellement une catégorie exclue (par exemple, une galerie d'art moderne alors que l'utilisateur n'en voulait pas).

Pour garantir le respect des contraintes, vous allez ajouter une boucle d'affinement maker-checker à la fin du pipeline à l'aide de LoopAgent :

1. itinerary_critic_agent (le vérificateur) : audite {final_itinerary} par rapport à {user_preferences}. Il additionne les coûts estimés, vérifie chaque contrainte négative et écrit des instructions de révision spécifiques dans critique_feedback ou répond avec la phrase exacte "APPROVED".
2. itinerary_refiner_agent (The Maker / Exiter) : lit {critique_feedback}. Si la critique est égale à "APPROVED", il appelle l'outil exit_loop (tool_context.actions.escalate = True) pour sortir immédiatement de la boucle LoopAgent. Sinon, il révise {final_itinerary} pour corriger les problèmes signalés et écrase final_itinerary pour la prochaine passe.

Ajouter exit_loop, Critic et Refiner à specialists.py

Ouvrez travel_planner/specialists.py :

cloudshell edit ~/adk-agents/travel_planner/specialists.py

Ajoutez l'outil exit_loop (ToolContext), itinerary_critic_agent et itinerary_refiner_agent en bas de travel_planner/specialists.py :

def exit_loop(tool_context: ToolContext) -> dict:
    """Call ONLY when the critique is APPROVED to exit the refinement loop."""
    print(f"[Tool Call] exit_loop triggered by {tool_context.agent_name}")
    tool_context.actions.escalate = True
    return {"status": "approved", "message": "Itinerary approved. Exiting refinement loop."}


# --- Specialist 5: The Budget & Constraint Critic (Inside LoopAgent) ---
itinerary_critic_agent = Agent(
    name="itinerary_critic_agent",
    include_contents="none",
    description="Audits the itinerary draft against budget and negative constraints.",
    instruction="""
        Audit Current Itinerary ({final_itinerary}) against User Preferences ({user_preferences}).
        Verify that the USD total stays within the user's budget and no excluded venue types appear.
        If all checks pass, respond EXACTLY with the single word "APPROVED".
        Otherwise, output 1-2 concise revision instructions explaining what to swap or adjust.
    """,
    output_key="critique_feedback",
)

# --- Specialist 6: The Itinerary Refiner / Exiter (Inside LoopAgent) ---
itinerary_refiner_agent = Agent(
    name="itinerary_refiner_agent",
    include_contents="none",
    description="Refines the itinerary from critique feedback, or calls exit_loop when APPROVED.",
    instruction="""
        Review Auditor Critique ({critique_feedback}) for Current Itinerary ({final_itinerary}).
        If the critique is EXACTLY "APPROVED", call `exit_loop` immediately and return the itinerary unchanged.
        Otherwise, revise the draft using {activity_recommendations} and {restaurant_recommendations}
        so all USD budget and exclusion rules pass, and output ONLY the updated Markdown itinerary.
    """,
    tools=[exit_loop],
    output_key="final_itinerary",
)

Raccourci exit_loop intégré dans l'ADK : écrire vous-même exit_loop(tool_context: ToolContext) vous permet de consigner l'appel d'outil et de voir comment tool_context.actions.escalate = True signale à LoopAgent de s'arrêter. Dans les projets de production, vous pouvez également importer l'assistant intégré d'ADK directement via from google.adk.tools import exit_loop, qui définit tool_context.actions.escalate = True et tool_context.actions.skip_summarization = True pour vous.

Ajout de LoopAgent à workflows.py

Ouvrez travel_planner/workflows.py :

cloudshell edit ~/adk-agents/travel_planner/workflows.py

Mettez à jour travel_planner/workflows.py pour encapsuler itinerary_critic_agent et itinerary_refiner_agent dans un LoopAgent (max_iterations=3) et l'ajouter en tant que quatrième étape de master_travel_agent :

from google.adk.agents import LoopAgent, ParallelAgent, SequentialAgent
from .specialists import (
    activity_finder_agent,
    itinerary_critic_agent,
    itinerary_refiner_agent,
    itinerary_synthesizer_agent,
    restaurant_finder_agent,
    user_profiler_agent,
)

# Stage 2: Parallel research branch
parallel_research_agent = ParallelAgent(
    name="parallel_research_agent",
    description="Runs activity and restaurant research concurrently.",
    sub_agents=[
        activity_finder_agent,
        restaurant_finder_agent,
    ],
)

# Stage 4: Iterative Maker-Checker refinement loop
refinement_loop_agent = LoopAgent(
    name="refinement_loop_agent",
    description="Iteratively audits and refines the itinerary until constraints and budget are approved.",
    sub_agents=[
        itinerary_critic_agent,
        itinerary_refiner_agent,
    ],
    max_iterations=3,
)

# Master pipeline: Profile -> Parallel Research -> Synthesize -> Refinement Loop
master_travel_agent = SequentialAgent(
    name="master_travel_agent",
    description="Orchestrates the end-to-end travel planning process for trip and itinerary requests.",
    sub_agents=[
        user_profiler_agent,          # Stage 1: Extract constraints
        parallel_research_agent,      # Stage 2: Research activities & restaurants in parallel
        itinerary_synthesizer_agent,  # Stage 3: Draft initial itinerary
        refinement_loop_agent,        # Stage 4: Audit and refine until approved
    ],
)

🔍 Vérifiez votre travail

Démarrez adk web pour tester l'intégralité du workflow multi-agent :

cd ~/adk-agents
adk web --allow_origins "*"

Ouvrez l'UI de l'aperçu Web sur le port 8000, démarrez une nouvelle session et testez l'ensemble du système avec ce prompt à contraintes multiples sur Kyoto :

Design a full-day itinerary for Kyoto with a total budget of $100. My main interests are historical landmarks, temples, and authentic local cuisine. Please do not include any modern art museums or galleries.

Un résultat semblable à la séquence d'exécution suivante doit s'afficher dans la vue Événements et les journaux du terminal :

1. user_profiler_agent -> writes JSON with destination="Kyoto", budget="$100", exclusions=["modern art museums", "galleries"]
2. parallel_research_agent -> runs activity_finder_agent and restaurant_finder_agent in parallel
3. itinerary_synthesizer_agent -> produces initial draft in state['final_itinerary']
4. refinement_loop_agent:
   - itinerary_critic_agent -> audits USD budget and exclusions -> outputs "APPROVED" (or revision notes)
   - itinerary_refiner_agent -> triggers [Tool Call] exit_loop triggered by itinerary_refiner_agent and outputs the approved itinerary

Inspecter les itérations de boucle et l'escalade dans l'UI Web d'ADK :

1. Vue des événements : cliquez sur n'importe quel chip d'événement de itinerary_critic_agent ou itinerary_refiner_agent pour inspecter sa charge utile dans l'onglet Infos de gauche. Lorsque itinerary_refiner_agent appelle exit_loop, inspectez l'événement pour voir actions.escalate: true, le signal qui indique à LoopAgent d'arrêter l'itération avant d'atteindre max_iterations=3.
2. Onglet "State" : cliquez sur l'onglet State pour observer la mise à jour de state['critique_feedback'] et state['final_itinerary'] au fil des passes. Si le brouillon initial dépassait $100 USD, critique_feedback contient les instructions de révision de l'auditeur lors de la première passe avant que final_itinerary ne soit mis à jour avec des alternatives moins coûteuses et que critique_feedback ne passe à "APPROVED" lors de la deuxième passe.

Une fois les tests terminés, appuyez sur Ctrl + C dans votre terminal pour arrêter adk web.

9. Effectuer un nettoyage

Continuer la série ? Si vous prévoyez de continuer à tester votre projet dans les prochains ateliers, il vous suffit d'arrêter le processus adk web en cours d'exécution avec Ctrl + C. Vous pouvez ignorer les étapes de suppression ci-dessous.

Supprimer les fichiers du projet local

Pour supprimer le répertoire du projet adk-agents et l'environnement virtuel de votre dossier d'accueil Cloud Shell, exécutez la commande suivante :

cd ~
rm -rf ~/adk-agents

Désactiver l'API Agent Platform

Si vous n'avez plus besoin d'activer l'API Agent Platform dans votre projet, désactivez-la avec gcloud :

gcloud services disable aiplatform.googleapis.com --quiet

Supprimer l'intégralité du projet Google Cloud (facultatif)

⚠️ Action destructive : ne supprimez le projet Google Cloud que si vous avez créé un projet dédié exclusivement à cet atelier de programmation. La suppression d'un projet entraîne la suppression définitive de toutes les ressources qu'il contient. Cette action est irréversible.

PROJECT_ID=$(gcloud config get-value project)
gcloud projects delete "$PROJECT_ID" --quiet

🔍 Vérifiez votre travail

Vérifiez que ~/adk-agents a bien été supprimé :

test ! -d ~/adk-agents && echo "Workspace ~/adk-agents removed"

Un résultat semblable à celui-ci s'affiche :

Workspace ~/adk-agents removed

10. Félicitations

Félicitations ! Vous avez créé un système multi-agent hiérarchique avec Agent Development Kit (ADK) de Google, qui coordonne une équipe de six agents spécialisés dans des workflows séquentiels, parallèles et en boucle itérative.

Bilan de vos réalisations

• Communication structurée entre agents via l'état de session partagé (injection de modèles output_key et {state_variable})
• Création d'un pipeline déterministe étape par étape à l'aide de SequentialAgent
• Exécution simultanée d'agents de recherche Google Search indépendants à l'aide de ParallelAgent
• Implémentation d'une boucle de validation automatisée de type "maker-checker" à l'aide de LoopAgent et tool_context.actions.escalate = True

Étapes suivantes

• Passez à la partie 4 de la série, Créer des agents IA avec ADK : orchestrer des workflows de graphes, pour recréer ce planificateur de voyage avec les cycles unifiés Workflow, JoinNode et déterministes Event(route=...) d'ADK 2.
• Consultez la documentation officielle sur les agents de workflow ADK.
• Découvrez les systèmes multi-agents dans ADK.
• Rejoignez le programme GEAR (Gemini Enterprise Agent Ready) et le programme de certification pour accéder à des ateliers pratiques et à des parcours de formation.