Schéma agent ADK avec mémoire et MCP

1. Objectifs de l'atelier

Bienvenue dans la Master Class ADK : votre voyage dans les systèmes multi-agents

Vous êtes sur le point de découvrir le monde passionnant des agents IA. Oubliez les chatbots simples qui ne font que répondre à des questions. Nous allons nous plonger dans l'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.

Cet atelier de programmation sera un parcours pratique, ce 1 dépôt GitHub contenant tout le code et les exemples de nos sessions. dépôt github

À la fin de ce tutoriel, vous serez en mesure de :

• Créer votre premier agent IA : passez d'un agent inexistant à un agent entièrement fonctionnel capable de comprendre les besoins d'un utilisateur, d'utiliser des outils tels que la recherche Google et de générer des réponses détaillées et utiles.
• Construire des systèmes multi-agents : découvrez le modèle "Agent en tant qu'outil", 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.
• Orchestrer 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.
• Donner 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 de suivi, d'apprendre des commentaires et de gérer les tâches en plusieurs étapes de manière transparente.
• Se connecter à MCP : connectez-vous à la boîte à outils MCP.

C'est parti ! 🚀

2. Configuration : obtenir votre clé API

Configuration de la clé API Google AI Studio

Cet atelier de programmation s'exécute entièrement sur une clé API Google AI Studio sans frais. Aucun projet Google Cloud, compte de facturation ni crédit n'est requis. Chaque session, y compris la mémoire (session 6) et MCP (session 7), s'exécute localement par rapport à votre clé. Chaque apprenant utilise sa propre clé. Le quota d'API est donc par personne et non partagé.

Ce dont vous aurez besoin :

• Python 3.9 ou version ultérieure (python3 --version pour vérifier)
• Un compte Google (pour créer la clé AI Studio)
• Un terminal : votre machine locale ou Cloud Shell fonctionnent tous les deux
• Environ 10 minutes

Pour alimenter nos agents IA, nous avons besoin d'une clé API Gemini de Google AI Studio. C'est le moyen le plus rapide de se lancer.

Étape 1 : Obtenir votre clé API Gemini depuis AI Studio (1 minute)

1. Ouvrez https://aistudio.google.com/app/apikey dans un nouvel onglet du navigateur.
2. Connectez-vous à l'aide de votre compte Google.
3. Cliquez sur "Créer une clé API" (en haut à droite).
4. Une boîte de dialogue s'ouvre avec un menu déroulant de projet :

• Si vous avez déjà créé un projet Google , sélectionnez-le, puis cliquez sur "Créer une clé API dans un projet existant"
• Si le projet ne figure pas dans la liste , cliquez sur "Créer un projet".

5. Copiez la clé API qui s'affiche. Elle commence par AIza... et comporte environ 40 caractères.

✏️ Collez-la dans un fichier que vous garderez en lieu sûr ; vous en aurez besoin à l'étape 4 ci-dessous.

Considérez la clé API comme un mot de passe. Ne la collez pas dans des chats publics, des captures d'écran ni ne l'intégrez dans un dépôt GitHub public.

Étape 2 : Cloner le dépôt (1 minute)

👉💻 Ouvrez votre terminal (ou Cloud Shell) et clonez le dépôt du tutoriel :

git clone https://github.com/cuppibla/adk_tutorial.git
cd ~/adk_tutorial

Étape 3 : Créer l'environnement virtuel et installer les dépendances

👉💻 Créez et activez un environnement virtuel nommé .adk_env, puis installez les dépendances :

python3 -m venv .adk_env
source .adk_env/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

(.adk_env) devrait s'afficher au début de votre invite de terminal.

Étape 4 : 🔥 IMPORTANT : Ajouter votre clé API

⚠️ Ne passez pas cette étape ! Créez un fichier .env à la racine du dossier adk_tutorial. Ce fichier alimente chaque session de cet atelier de programmation. Les sessions Web ADK (1 à 5) et les sessions de mémoire et MCP en ligne de commande (6 à 7) le lisent automatiquement.

👉💻 Créez le fichier .env avec votre clé (remplacez your_actual_api_key_here par la clé de l'étape 1) :

cat > .env <<'EOF'
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
EOF

Votre fichier ~/adk_tutorial/.env devrait maintenant contenir :

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 CRITIQUE : Remplacez your_actual_api_key_here par votre clé API provenant de l'étape 1 (elle commence par AIza...).

⚠️ Assurez-vous que GOOGLE_GENAI_USE_VERTEXAI est défini sur FALSE. Cela indique à ADK de s'authentifier avec votre clé API Google AI Studio au lieu de Vertex AI.

✅ Point de contrôle : Vous disposez d'un fichier .env dans ~/adk_tutorial/.env contenant votre clé AIza..., et votre invite de terminal affiche (.adk_env). Vous êtes prêt à créer des agents !

3. Session 1 : Votre premier agent dans ADK Web

Ouvrez ADK Web en exécutant :

cd ~/adk_tutorial
source .adk_env/bin/activate
adk web

Une fois les commandes exécutées, vous devriez voir dans votre terminal un résultat indiquant que le serveur Web ADK a démarré, comme ceci :

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8000.                         |
+-----------------------------------------------------------------------------+


INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

👉 Ensuite, ouvrez votre navigateur sur http://localhost:8000 pour accéder à l'UI de développement d'ADK.

Vous exécutez Cloud Shell au lieu d'une exécution locale ? Cliquez sur l'icône Aperçu sur le Web dans la barre d'outils Cloud Shell (généralement en haut à droite), sélectionnez Modifier le port, définissez le port sur 8000, puis cliquez sur "Modifier et afficher l'aperçu". Cloud Shell ouvre l'UI de développement d'ADK dans un nouvel onglet du navigateur.

👉 Votre rituel d'invocation est terminé et l'agent est maintenant en cours d'exécution. L'UI de développement d'ADK dans votre navigateur est votre connexion directe au familier.

Choisissez votre premier agent. Dans le menu déroulant en haut de l'UI, sélectionnez a_single_agent.

Vous pouvez sélectionner a_single_agent ici :

Vous pouvez voir le suivi ici :

👉 Prompt de test :

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art.

4. Session 2 : Agent de workflow : agent séquentiel, agent parallèle, agent en boucle

Ouvrez votre UI Web ADK en suivant les étapes de la session 1.

Agent parallèle

Choisissez l'agent de workflow parallèle. Dans le menu déroulant en haut de l'UI, sélectionnez b2_parallel_agent.

👉 Prompt de test :

Plan my trip to San Francisco, I want to find some good concert, restaurant and museum.

Vous pouvez sélectionner b2_parallel_agent ici :

Vous pouvez voir le suivi ici :

Agent séquentiel

Choisissez l'agent de workflow séquentiel. Dans le menu déroulant en haut de l'UI, sélectionnez b1_sequential_agent.

👉 Prompt de test :

Find a good sushi near Standford and tell me how to get there.

Vous pouvez sélectionner b1_sequential_agent ici :

Vous pouvez voir le suivi ici :

Agent en boucle

Choisissez l'agent de workflow en boucle. Dans le menu déroulant en haut de l'UI, sélectionnez b3_loop_agent.

👉 Prompt de test :

Plan a trip from Sunnyvale to San Francisco today.

Vous pouvez sélectionner b3_loop_agent ici :

Vous pouvez voir le suivi ici :

5. Session 3 : Agent personnalisé

Ouvrez votre UI Web ADK en suivant les étapes de la session 1.

Une fois votre UI Web ADK ouverte, sélectionnez c_custom_agent dans le menu déroulant.

👉 Prompt de test :

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art. Make sure within budget of 100 dollars.

Vous pouvez sélectionner c_custom_agent ici :

Vous pouvez voir le suivi ici :

6. Session 4 : Modèle d'orchestrateur : agent de routage

Ouvrez votre UI Web ADK en suivant les étapes de la session 1.

Une fois votre UI Web ADK ouverte, sélectionnez d_routing_agent dans le menu déroulant.

👉 Prompt de test :

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

Vous pouvez sélectionner d_routing_agent ici :

Vous pouvez voir le suivi ici :

7. Session 5 : Agent en tant qu'outil

Ouvrez votre UI Web ADK en suivant les étapes de la session 1.

Une fois votre UI Web ADK ouverte, sélectionnez e_agent_as_tool dans le menu déroulant.

👉 Prompt de test :

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

Vous pouvez sélectionner e_agent_as_tool ici :

Vous pouvez voir le suivi ici :

8. Session 6 : Agent avec mémoire à long terme

S'exécute entièrement en local. Cette session stocke la mémoire de conversation dans une base de données SQLite locale (sous ~/.adk/), de sorte que vos préférences persistent lors des redémarrages sans Google Cloud, facturation ni crédits requis. L'agent lit votre clé AI Studio à partir du fichier ~/adk_tutorial/.env que vous avez créé lors de la configuration.

👉💻 Testez votre mémoire à long terme en accédant au dossier et en utilisant le runner pour alimenter l'agent :

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 Prompt de test :

I like Art and Italian food.

Ensuite, mettez fin à la session en appuyant sur Ctrl+C. Redémarrez la session :

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 Prompt de test :

Plan a trip to San Francisco based on my preference.

✅ L'agent doit se souvenir de "Art et cuisine italienne" de l'exécution précédente. C'est la mémoire à long terme qui fonctionne entre les sessions.

9. Session 7 : Permettre à votre agent d'accéder à la puissance de MCP

S'exécute entièrement en local. Cette session démarre un serveur MCP Toolbox local qui lit une base de données SQLite locale (destinations.db). Aucun Google Cloud, facturation ni crédits ne sont requis. Le seul téléchargement externe est le fichier binaire MCP Toolbox Open Source.

Étape 1 : Préparer la base de données locale

👉💻 À partir de la racine du dépôt, créez l'exemple de base de données :

cd ~/adk_tutorial
source .adk_env/bin/activate
chmod +x setup_trip_database.py
./setup_trip_database.py

Cela crée destinations.db dans ~/adk_tutorial/.

⚠️ L'exemple de base de données ne contient que quatre villes : Paris, Rome, New York et Tokyo (types d'attractions : monument, musée, parc). Les prompts qui font référence à d'autres villes (par exemple, San Francisco ou Sunnyvale) renverront correctement aucun résultat, car ces lignes n'existent pas. Utilisez les quatre villes ci-dessus lorsque vous testez cette session.

Étape 2 : Installer et exécuter le serveur MCP Toolbox

👉💻 Téléchargez le fichier binaire MCP Toolbox pour votre système d'exploitation :

cd ~/adk_tutorial/mcp_tool_box
export VERSION=0.16.0

# Choose the line that matches your machine:
export OS=linux/amd64      # Cloud Shell or Linux (x86_64)
# export OS=darwin/arm64   # macOS Apple Silicon (M1/M2/M3)
# export OS=darwin/amd64   # macOS Intel

curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/$OS/toolbox

une fois le téléchargement terminé, exécutez

chmod +x toolbox

Vous ne savez pas quel Mac vous possédez ? Exécutez uname -m : arm64 = Apple Silicon, x86_64 = Intel. Sous Windows, téléchargez .../windows/amd64/toolbox.exe et exécutez-le à partir de PowerShell.

Étape 3

Dans un terminal , exécutez la commande suivante (laissez-la s'exécuter. L'agent s'y connecte sur http://127.0.0.1:7001) :

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/mcp_tool_box
./toolbox --tools-file "trip_tools.yaml" --port 7001

Dans un autre terminal , exécutez la commande suivante

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/g_agents_mcp
python main.py

👉 Prompts de test (utilisez les villes qui existent dans l'exemple de base de données : Paris, Rome, New York ou Tokyo) :

What are the top-rated things to do in Tokyo?

Show me the museums in Rome.

What can I do in New York for under 25 dollars?

Dépannage de la session 7

• "Connexion refusée" / l'agent ne trouve aucun outil : le serveur Toolbox du premier terminal n'est pas en cours d'exécution. Redémarrez-le et vérifiez qu'il écoute sur le port 7001.
• Chaque requête renvoie des résultats vides : vérifiez que vous avez exécuté l'étape 1 afin que ~/adk_tutorial/destinations.db existe et que votre prompt utilise l'une des quatre villes (Paris, Rome, New York, Tokyo).
• toolbox: cannot execute binary file sur macOS : vous avez téléchargé la version Linux. Réexécutez l'étape 2 avec OS=darwin/arm64 (Apple Silicon) ou OS=darwin/amd64 (Intel).