1. Objectifs de l'atelier
Bienvenue dans la masterclass ADK : votre parcours dans les systèmes multi-agents
Vous êtes sur le point de découvrir le monde passionnant des agents d'IA. Oubliez les chatbots simples qui se contentent de répondre aux questions. Nous explorons en détail Agent Development Kit (ADK)
pour créer des systèmes autonomes sophistiqués capables de raisonner, de planifier et d'utiliser des outils pour accomplir des tâches complexes.
À la fin de ce tutoriel, vous serez en mesure de :
- Créez votre premier agent d'IA : passez de zéro à un agent entièrement fonctionnel capable de comprendre les besoins d'un utilisateur, d'utiliser des outils comme la recherche Google et de générer des réponses détaillées et utiles.
- Maîtrisez les outils personnalisés : exploitez tout le potentiel des agents en les connectant à vos propres fonctions et API personnalisées. Vous allez apprendre à votre agent à récupérer des données en temps réel, comme des prévisions météo.
- Construire des systèmes multi-agents : découvrez le modèle Agent-as-a-Tool, un concept révolutionnaire dans lequel les agents délèguent des tâches à d'autres agents spécialisés, créant ainsi une équipe d'experts en IA qui travaillent ensemble.
- Orchestrez des workflows complexes : allez au-delà de la simple délégation et maîtrisez des modèles avancés tels que les routeurs, les chaînes séquentielles, les boucles et l'exécution parallèle pour créer des applications robustes, efficaces et intelligentes capables de gérer presque toutes les requêtes.
- Donnez de la mémoire à vos agents : comprenez le rôle essentiel de la mémoire conversationnelle, qui permet à vos agents de gérer les questions complémentaires, d'apprendre des commentaires et de gérer les tâches en plusieurs étapes de manière fluide.
C'est parti ! 🚀
2. Configurer une clé API GCP et Gemini
Configurer votre projet GCP et votre clé API Gemini
Pour alimenter nos agents d'IA, nous avons besoin de deux éléments : un projet Google Cloud pour fournir la base et une clé API Gemini pour accéder aux puissants modèles de Google.
Étape 1 : Activez le compte de facturation
- Réclamez votre compte de facturation avec un crédit de 5 $, dont vous aurez besoin pour votre déploiement. Assurez-vous d'utiliser votre compte Gmail.
Étape 2 : Créer un projet GCP
- Accédez à la console Google Cloud et créez un projet.
- Accédez à la console Google Cloud et créez un projet.
- Ouvrez le panneau de gauche, cliquez sur
Billing
et vérifiez si le compte de facturation est associé à ce compte GCP.
Si cette page s'affiche, cochez la case manage billing account
, puis sélectionnez l'essai Google Cloud et associez-le.
Étape 3 : Générez votre clé API Gemini
Avant de pouvoir sécuriser une clé, vous devez en avoir une.
- Accédez à Google AI Studio : https://aistudio.google.com/.
- Connectez-vous avec votre compte Gmail.
- Cliquez sur le bouton Obtenir une clé API, généralement situé dans le volet de navigation de gauche ou en haut à droite.
- Dans la boîte de dialogue Clés API, cliquez sur "Créer une clé API dans un nouveau projet".
- Choisissez le nouveau projet que vous avez créé et pour lequel un compte de facturation est configuré.
- Une clé API sera générée pour vous. Copiez immédiatement cette clé et stockez-la temporairement dans un endroit sûr (comme un gestionnaire de mots de passe ou une note sécurisée). Il s'agit de la valeur que vous utiliserez dans les étapes suivantes.
3. Session 1 : Votre premier agent avec Runner
Commençons par les bases. Ici, nous créons notre premier agent simple, day_trip_agent
. L'objectif de cet agent est de générer un itinéraire de voyage d'une journée complète en fonction de la demande d'un utilisateur, y compris des considérations budgétaires. Cet exemple présente les trois composants principaux de toute interaction d'agent dans l'ADK :
- Agent : cerveau de l'opération. Il est défini par ses instructions (sa personnalité et sa mission), le modèle d'IA qu'il utilise (comme Gemini) et les outils auxquels il peut accéder.
- Session : mémoire de la conversation. Elle stocke l'historique des interactions (messages utilisateur et réponses de l'agent), ce qui permet un dialogue continu.
- Exécuteur : moteur qui exécute la tâche. Il prend l'agent et la session, traite la nouvelle requête de l'utilisateur et orchestre les étapes pour générer une réponse.
➡️ Où le trouver dans le notebook
👉 Cela correspond aux cellules sous Partie 1 : Votre premier agent – Le Génie des excursions d'une journée 🧞.🌟
- Définition de l'agent : recherchez la fonction
create_day_trip_agent()
. C'est là que l'agent est défini. Notez la chaîne d'instructions détaillée : il s'agit de la requête qui indique à l'agent comment se comporter. Nous lui fournissons également son premier outil : la recherche Google. - Fonction d'assistance : la fonction d'assistance
run_agent_query()
est définie ici. Nous utiliserons cet utilitaire tout au long du notebook pour simplifier l'exécution des requêtes. - Test Run : la fonction
run_day_trip_genie()
simule un utilisateur demandant une excursion d'une journée "abordable" et "relaxante". L'agent utilise ses instructions et l'outil de recherche Google pour trouver des lieux adaptés et créer un itinéraire au format Markdown.
➡️ Action : examinez l'invite d'instructions pour day_trip_agent
. Voyez comment la demande de voyage "abordable" dans la requête de test est directement liée à la consigne de l'agent "Être attentif au budget".
4. Session 2 : Outils personnalisés 🛠️
Bien que la recherche Google soit puissante, le véritable potentiel des agents d'IA se révèle lorsque vous les connectez à vos propres sources de données, API ou logique personnalisée. Dans cette section, nous allons créer un outil personnalisé à partir d'une fonction Python simple.
La partie la plus importante d'un outil de fonction est sa docstring. L'ADK analyse automatiquement la docstring pour comprendre ce que fait l'outil, les paramètres qu'il accepte (Args) et ce qu'il renvoie (Returns). Le grand modèle de langage (LLM) lit cette description pour décider quand et comment utiliser l'outil.
➡️ Où le trouver dans le notebook
👉 Cela correspond aux cellules sous 2.1 The Simple FunctionTool: Calling a Real-Time Weather API. 🌟
- Définition de l'outil : la fonction
get_live_weather_forecast(location: str)
est au cœur de notre outil personnalisé. Il prend un nom de ville, appelle l'API publique National Weather Service et renvoie un dictionnaire avec la température et les prévisions. - Définition de l'agent : l'agent weather_agent est créé et équipé de notre nouvel outil en transmettant
tools=[get_live_weather_forecast]
lors de son initialisation. Les instructions de l'agent lui indiquent explicitement d'utiliser cet outil avant de suggérer des activités de plein air. - Exécution test : la requête "Je veux faire de la randonnée près du lac Tahoe. Quel temps fait-il ?" déclenche directement l'utilisation de l'outil
get_live_weather_forecast
par l'agent, car ses instructions l'exigent.
➡️ Action : Lisez la docstring de la fonction get_live_weather_forecast
et les instructions pour weather_agent
. Notez la relation directe entre eux.
5. Session 3 : Agent-as-a-Tool 🧑🍳
Pourquoi créer un agent monolithique unique quand vous pouvez créer une équipe de spécialistes ? Le modèle Agent-as-a-Tool
est un moyen efficace de créer des systèmes complexes dans lesquels un agent principal, souvent appelé Orchestrateur ou Routeur, délègue des tâches à d'autres agents plus spécialisés.
Ce modèle vous permet de créer des agents modulaires et réutilisables. Par exemple, vous pouvez avoir un agent expert en requêtes de base de données, un autre expert en écriture créative et un troisième qui joue le rôle d'un concierge sympathique. Le rôle de l'orchestrateur est de comprendre la demande de l'utilisateur et de l'acheminer vers le spécialiste approprié.
➡️ Où le trouver dans le notebook
👉 Cela correspond aux cellules sous 2.2 L'agent en tant qu'outil : consulter un spécialiste 🧑🍳.🌟
Cet exemple crée un système d'agents sophistiqué et multicouche :
- Les spécialistes
- :
- food_critic_agent : agent hautement spécialisé qui ne fournit que des suggestions de restaurants.
- db_agent : agent fictif qui simule l'interrogation d'une base de données pour obtenir des informations sur les hôtels.
- concierge_agent : un agent de niveau intermédiaire qui agit comme un concierge poli. Il est essentiel qu'il dispose de
food_critic_agent
comme outil propre.
- L'orchestrateur (
trip_data_concierge_agent
) : il s'agit de l'agent de premier niveau avec lequel l'utilisateur interagit. Ses instructions en font un "planificateur de voyage principal". Il dispose de deux outils qui appellent les autres agents :- call_db_agent : fonction qui appelle
db_agent
. - call_concierge_agent : fonction qui appelle
concierge_agent
.
- call_db_agent : fonction qui appelle
- Le flux : l'exécution du test dans
run_trip_data_concierge()
démontre la chaîne de délégation complète.- Un utilisateur demande à l'orchestrateur un hôtel et un restaurant à proximité.
- Les instructions de l'orchestrateur lui indiquent d'abord d'utiliser l'outil
call_db_agent
pour obtenir des données sur les hôtels. - L'orchestrateur utilise ensuite l'outil
call_concierge_agent
pour obtenir une recommandation. - Une fois la requête reçue,
concierge_agent
utilise son propre outil,food_critic_agent
, pour obtenir une idée de restaurant.
La réponse du critique gastronomique est renvoyée au concierge, qui la met en forme de manière polie et la renvoie à l'orchestrateur, qui la présente enfin à l'utilisateur.
➡️ Action : tracez le flux d'exécution dans l'exécution du test sous run_trip_data_concierge()
. Observez comment les sorties d'impression TOOL CALLED
affichent la chaîne de délégation de l'orchestrateur aux spécialistes. Il s'agit d'une chaîne de commandement séquentielle.
6. Session 4 : Mémoire de l'agent 🧠
Un agent réellement intelligent doit faire plus que simplement répondre à des requêtes ponctuelles. Elle doit se souvenir de la conversation, comprendre le contexte et s'adapter aux commentaires. Pour cela, il faut gérer correctement les sessions. Un "agent en boucle" est un agent engagé dans une boucle de conversation continue, alimentée par sa mémoire.
Lorsque vous utilisez le même objet de session pour plusieurs requêtes séquentielles, l'agent peut "voir" l'intégralité de l'historique de la conversation. Cela lui permet de répondre à des questions complémentaires, de se corriger en fonction des commentaires et de planifier des tâches en plusieurs étapes.
➡️ Où le trouver dans le notebook
👉 Cela correspond aux cellules de la section Part 3: Agent with a Memory - The Adaptive Planner 🗺️. 🌟
- Définition de l'agent : la fonction
create_multi_day_trip_agent()
définit un agent conçu pour planifier un voyage de manière progressive. Ses instructions mettent l'accent sur la mémorisation du contexte, la gestion des commentaires et la planification au jour le jour.
Scénario 3a : Agent AVEC mémoire (✅)
Ce test est exécuté dans la fonction run_adaptive_memory_demonstration()
.
- Un seul
trip_session
est créé et réutilisé pendant trois tours consécutifs. - Tour 1 : l'utilisateur lance la planification d'un voyage de deux jours.
- Tour 2 : l'utilisateur donne son avis ("Je ne suis pas un grand fan des châteaux"). Comme l'agent se souvient du tour 1, il comprend quelle partie du plan doit être modifiée et propose une alternative.
- Tour 3 : L'utilisateur confirme la modification et demande la prochaine étape. L'agent se souvient de tout et planifie le deuxième jour.
Scénario 3b : Agent SANS mémoire (❌)
Ce test est exécuté dans la fonction run_memory_failure_demonstration()
.
Cela démontre l'importance cruciale de la gestion des sessions en commettant une erreur intentionnellement. Une session est créée pour chaque tour.
- Tour 1 : l'utilisateur lance le trajet dans session_one. L'agent répond correctement.
- Tour 2 : l'utilisateur demande à planifier le jour 2, mais la requête est envoyée dans une toute nouvelle session_two. Comme cette nouvelle session n'a pas d'historique, l'agent est confus. Il a perdu la mémoire ! Il ne sait pas quel voyage est en cours de planification.
Action : Compare les réponses de l'agent dans run_adaptive_memory_demonstration()
et run_memory_failure_demonstration()
. Il s'agit du concept le plus important du notebook : une conversation continue nécessite une session continue.
7. Session 5 : L'agent de routage 🚏
Un seul agent ne peut pas tout faire. Pour répondre aux demandes utilisateur vraiment complexes, nous avons besoin d'une équipe d'agents spécialisés. Mais comment savoir quel agent utiliser pour une requête donnée ? C'est là qu'intervient l'agent de routeur.
L'agent de routeur agit en tant qu'agent "maître" ou répartiteur. Son seul objectif est d'analyser une requête utilisateur entrante et de déterminer quel agent spécialisé (ou workflow d'agents) est le mieux adapté à la tâche. Il ne répond pas lui-même à la requête, mais la transmet simplement à l'agent en aval approprié.
Par exemple, une requête sur "les meilleurs sushis" doit être envoyée à un foodie_agent, tandis qu'une question sur les "concerts ce week-end" doit être traitée par un weekend_guide_agent
.
➡️ Où trouver cette information dans le notebook :
👉 Ce concept est au cœur de l'ensemble du notebook, mais il est d'abord présenté dans la partie 1 : Multi-Agent Mayhem – Workflows séquentiels 🧠→🤖→🤖 🌟
- Définitions des agents : la cellule de code définit plusieurs agents spécialisés (day_trip_agent, foodie_agent, transportation_agent) et, surtout, l'agent router_agent. Portez une attention particulière à l'invite d'instructions pour l'agent router_agent. Il est explicitement indiqué qu'il ne doit renvoyer que le nom du meilleur agent pour la tâche.
- Logique d'exécution : la fonction run_sequential_app montre comment appeler d'abord l'agent de routeur pour obtenir une décision (chosen_route), puis utiliser cette décision dans un bloc
if/elif
pour exécuter l'agent spécialisé approprié.
8. Session 6 : SequentialAgent ⛓️
Certaines tâches nécessitent plusieurs étapes dans un ordre spécifique. Par exemple : "Trouve-moi les meilleurs sushis de Palo Alto, puis dis-moi comment m'y rendre." Il s'agit d'un processus en deux étapes : d'abord, trouver le restaurant, puis obtenir l'itinéraire.
L'ADK fournit un moyen simple et efficace de gérer cela avec SequentialAgent. Il s'agit d'un agent de workflow spécial qui exécute une liste de sous-agents dans un ordre prédéfini.
La magie réside dans l'état partagé. La sortie d'un agent de la séquence peut être automatiquement enregistrée dans un dictionnaire d'état partagé, puis utilisée comme entrée pour l'agent suivant. Cela élimine la nécessité d'un code manuel complexe pour transmettre des informations entre les étapes.
➡️ Où trouver cette information dans le notebook :
👉 Ce point est abordé dans la partie 2 (La méthode ADK) : le chaos multi-agents avec SequentialAgent 🧠→⛓️→🤖. 🌟
- Refactoring de l'agent : dans la première cellule de code de cette section, notez les principales modifications apportées à
foodie_agent
ettransportation_agent
:foodie_agent
comporte désormais unoutput_key="destination"
. Cela indique à l'ADK d'enregistrer sa réponse finale dans une variable nomméedestination
dans l'état partagé.transportation_agent
comporte désormais le code de substitution{destination}
dans son invite d'instructions. L'ADK insère automatiquement la valeur de l'état partagé dans cet espace réservé.
- Définir le workflow :
find_and_navigate_agent
est défini comme un SequentialAgent, avec ses sous-agents définis sur [foodie_agent
,transportation_agent
], ce qui garantit qu'ils s'exécutent dans cet ordre précis. - Exécution simplifiée : examinez la fonction
run_sequential_app
dans cette section. La logique complexeif/elif
a disparu !find_and_navigate_agent
est désormais traité comme une unité appelable unique, et l'ADK gère automatiquement les étapes séquentielles internes.
9. Session 7 : LoopAgent 🔁
Tous les problèmes n'ont pas une solution simple et immédiate. Parfois, nous devons proposer une solution, la critiquer et l'affiner jusqu'à ce qu'elle réponde à une contrainte spécifique.
Pour ce faire, l'ADK propose LoopAgent
. Cet agent de workflow exécute de manière répétée une séquence de sous-agents jusqu'à ce qu'une condition spécifique soit remplie. Cette approche est idéale pour créer des agents "perfectionnistes" capables de planifier, de critiquer et d'améliorer leur propre travail.
Le diagramme montre que Planner Agent
crée d'abord un plan. Ensuite, nous saisissons LoopAgent
. La commande Critic Agent
vérifie le plan. S'il est défectueux, Refiner Agent
crée une nouvelle version et la boucle se répète. Si le plan est correct, Refiner Agent
appelle l'outil exit_loop
, et le plan final validé est renvoyé.
➡️ Où trouver cette information dans le notebook :
👉 Pour en savoir plus, consultez Idées itératives avec LoopAgent 🧠→🔁→🤖. 🌟
- Agents principaux : le workflow utilise un
planner_agent
, uncritic_agent
et unrefiner_agent
. - Définition de la boucle :
refinement_loop
est défini comme un LoopAgent qui orchestrecritic_agent
,refiner_agent
etsets max_iterations=3
. - Condition de sortie : la boucle se termine lorsque
critic_agent
approuve le plan, ce qui amènerefiner_agent
à appeler l'outilexit_loop
personnalisé.
10. Session 8 : ParallelAgent ⚡️
L'efficacité est essentielle. Si un utilisateur demande plusieurs informations sans rapport les unes avec les autres en même temps, l'exécution de ces recherches une par une serait lente.
La solution est ParallelAgent
. Cet agent de workflow exécute une liste de sous-agents simultanément. Une fois toutes les tâches parallèles terminées, leurs résultats peuvent être rassemblés et synthétisés en une seule réponse complète.
Ce diagramme montre le ParallelAgent
qui prend une seule requête et divise le travail en trois pistes simultanées. museum_finder
, concert_finder
et restaurant_finder
s'exécutent en même temps. Une fois les trois tâches terminées, leurs résultats individuels (enregistrés dans l'état partagé) sont combinés et transmis à l'agent de synthèse final, qui les regroupe en une seule réponse.
➡️ Où trouver cette information dans le notebook :
👉 Ce workflow est décrit en détail dans la section Puissance parallèle avec ParallelAgent 🧠→⚡️→🤖🤖🤖. 🌟
- Agents spécialisés : trois agents spécialisés sont définis, chacun avec une output_key unique (par exemple, museum_result).
- Workflow parallèle : parallel_research_agent est défini comme ParallelAgent, avec les trois agents de recherche listés comme sous-agents.
- Étape de synthèse : après l'étape parallèle, un agent de synthèse final rassemble tous les résultats de l'état partagé à l'aide d'espaces réservés (
{museum_result}
,{concert_result}
, etc.) pour mettre en forme un résumé clair.
11. Annexe : ADK Web – 🍎 Pour Mac/Linux
Ce guide vous explique comment configurer et exécuter l'agent de planification d'excursions ADK sur votre ordinateur local.
Prérequis
- Python 3.8 ou version ultérieure
- Python 3.9 ou version ultérieure : installe google-adk==1.5.0 (dernière version avec toutes les fonctionnalités)
- Python 3.8 : installe google-adk==0.3.0 (version compatible)
- Clé API Google AI Studio
- Connexion Internet
Étape 1 : Cloner le dépôt
Ouvrez le terminal et exécutez :
git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic
Étape 2 : Configurer l'environnement virtuel et installer les dépendances
Option A : Configuration automatique (recommandée)
# Run the setup script
chmod +x setup_venv.sh
./setup_venv.sh
Option B : Configuration manuelle
# Create virtual environment
python3 -m venv .adk_env
# Activate virtual environment
source .adk_env/bin/activate
# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt
Étape 3 : 🔥 IMPORTANT - Créez des variables d'environnement
⚠️ Ne passez pas cette étape ! Créez un fichier .env
dans le répertoire agent/
:
# Create the .env file
touch agent/.env
# Open it in your default text editor
open agent/.env
Ajoutez les lignes suivantes au fichier :
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
🚨 CRITIQUE : Remplacez your_actual_api_key_here
par votre clé API.
Étape 4 : Activez l'environnement virtuel (s'il n'est pas déjà actif)
source .adk_env/bin/activate
(.adk_env)
devrait s'afficher au début de l'invite du terminal.
Étape 5 : Exécutez l'interface Web ADK
adk web
Étape 6 : Ouvrez votre navigateur
- Ouvrez votre navigateur et accédez à l'URL affichée dans le terminal (généralement
http://localhost:8000
). - Dans le menu déroulant en haut à gauche, sélectionnez
agent
. - Commencez à discuter avec votre agent de planification d'excursion d'une journée !
Vous verrez une conversation comme celle-ci :
Désactiver l'environnement
Lorsque vous avez terminé de travailler sur le projet :
deactivate
Cette commande fonctionne de la même manière sur Mac/Linux et Windows. Vous remarquerez que le préfixe (.adk_env)
disparaît de l'invite du terminal.
Dépannage sur Mac
- Python introuvable : utilisez
python3
au lieu depython
. - Autorisation refusée : exécutez
chmod +x setup_venv.sh
avant d'exécuter le script.
12. Annexe : ADK Web – 🪟 Pour les utilisateurs Windows
Ce guide vous explique comment configurer et exécuter l'agent de planification d'excursions ADK sur votre ordinateur local.
Prérequis
- Python 3.8 ou version ultérieure
- Python 3.9 ou version ultérieure : installe google-adk==1.5.0 (dernière version avec toutes les fonctionnalités)
- Python 3.8 : installe google-adk==0.3.0 (version compatible)
- Clé API Google AI Studio
- Connexion Internet
Étape 1 : Cloner le dépôt
Ouvrez l'invite de commande ou PowerShell, puis exécutez la commande suivante :
git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic
Étape 2 : Configurer l'environnement virtuel et installer les dépendances
Option A : Configuration automatique (recommandée)
# Run the setup script in Command Prompt
setup_venv.bat
Option B : Configuration manuelle
Pour l'invite de commande :
# Create virtual environment
python -m venv .adk_env
# Activate virtual environment
.adk_env\Scripts\activate
# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt
Pour PowerShell :
# Create virtual environment
python -m venv .adk_env
# Activate virtual environment
.adk_env\Scripts\Activate.ps1
# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt
Étape 3 : 🔥 IMPORTANT - Créez des variables d'environnement
⚠️ Ne passez pas cette étape ! Créez un fichier .env
dans le répertoire agent/
:
# Create the .env file
type nul > agent\.env
# Open it in Notepad
notepad agent\.env
Ajoutez les lignes suivantes au fichier :
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
🚨 CRITIQUE : Remplacez your_actual_api_key_here
par votre clé API.
Étape 4 : Activez l'environnement virtuel (s'il n'est pas déjà actif)
Invite de commande :
.adk_env\Scripts\activate
PowerShell :
.adk_env\Scripts\Activate.ps1
(.adk_env)
devrait s'afficher au début de votre requête.
Étape 5 : Exécutez l'interface Web ADK
adk web
Étape 6 : Ouvrez votre navigateur
- Ouvrez votre navigateur et accédez à l'URL affichée dans le terminal (généralement
http://localhost:8000
). - Dans le menu déroulant en haut à gauche, sélectionnez
agent
. - Commencez à discuter avec votre agent de planification d'excursion d'une journée !
Dépannage Windows
- Erreur liée à la règle d'exécution PowerShell : exécutez
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Vous verrez une conversation comme celle-ci :
Désactiver l'environnement
Lorsque vous avez terminé de travailler sur le projet :
deactivate
Cette commande fonctionne de la même manière sur Mac/Linux et Windows. Vous remarquerez que le préfixe (.adk_env)
disparaît de l'invite du terminal.