Créer un agent IA avec Google ADK

1. Introduction

Dans cet atelier de programmation, vous allez créer votre tout premier agent IA étape par étape à l'aide de l'Agent Development Kit (ADK) de Google et de Gemini. Vous allez créer un agent de rédaction de blog de base qui planifie et rédige du contenu, en mettant en évidence les concepts fondamentaux de raisonnement et d'action.

Objectifs de l'atelier

  • Configurez votre environnement de développement pour ADK.
  • Créez un système multi-agent avec un planificateur et un rédacteur.
  • Exécutez l'agent localement et interagissez avec lui via l'UI Web d'ADK.

Prérequis

  • Un navigateur Web tel que Chrome.
  • Python 3.10 ou version ultérieure installé sur votre ordinateur.
  • Une clé API Google AI Studio.

Cet atelier de programmation s'adresse aux développeurs de tous niveaux, y compris aux débutants.

Durée estimée : 30 minutes.

2. Guide visuel : Qu'est-ce qu'un agent IA ?

Avant de commencer à créer, comprenons rapidement ce que sont les agents d'IA et les schémas courants qu'ils suivent.

Qu'est-ce qu'un agent IA ?

what-are-ai-agents.png

Au niveau le plus simple, un agent est un logiciel qui ne se contente pas de répondre, mais qui peut prendre des décisions et agir. Au lieu de générer une seule réponse comme un chatbot traditionnel, il examine votre requête, détermine les étapes à suivre, appelle éventuellement une API, exécute du code, examine le résultat, puis décide de la prochaine étape.

foundation-reasoning-acting.png

L'une des explications les plus claires provient de l'étude ReAct : Synergizing Reasoning and Acting in Language Models. L'idée de ce document était simple, mais puissante : les modèles de langage ne doivent pas se contenter de générer du texte en une seule fois. Ils peuvent en fait raisonner étape par étape, effectuer une action comme appeler un outil ou une API, observer le résultat, puis décider de la prochaine étape.

Ce cycle de raisonnement, d'action, d'observation et d'ajustement est à la base du fonctionnement des agents d'IA modernes. Cette définition correspond à celle de Google Cloud : des systèmes dotés de capacités de raisonnement, de planification et de mémoire, avec suffisamment d'autonomie pour s'adapter et prendre des décisions au nom de l'utilisateur.

Trois modèles de comportement des agents

Tous les agents ne se comportent pas de la même manière. Vous pouvez les envisager selon trois grands types :

three-agent-behaviour-patterns.png

  1. Agents séquentiels : ils s'exécutent étape par étape, comme une chaîne de montage : étape 1, puis étape 2, puis étape 3. Ils sont prévisibles, mais rigides.
  2. Agents réactifs : ils prennent des décisions sur le moment. Ils examinent l'état actuel et se demandent : "Que dois-je faire ensuite ?" Peut-être l'outil A une fois, puis l'outil B la fois suivante. Ils sont flexibles, mais ne planifient pas à l'avance.
  3. Agents délibératifs ou de planification : ils font une pause pour élaborer un plan, puis l'exécutent. Pensez à la réservation d'un voyage : vous ne réservez pas un vol au hasard, vous choisissez des dates et des hôtels, vous ordonnez les étapes, puis vous les suivez.

Quelle est la "bonne" approche ? Cela dépend du problème. Pour les flux simples et prévisibles, l'approche séquentielle convient. Pour les tâches dynamiques, l'approche réactive est plus efficace. Pour les objectifs en plusieurs étapes avec des dépendances, vous avez besoin d'agents de planification.

Dans cet atelier, nous allons créer un agent délibératif/de planification qui crée d'abord un plan, puis rédige le post de blog.

3. Avant de commencer

Créer un compte et un projet Google Cloud

Pour déployer votre agent sur Google Cloud Run plus tard dans cet atelier, vous avez besoin d'un compte Google Cloud et d'un projet pour lequel la facturation est activée.

  1. Connectez-vous à la console Google Cloud. Créez un projet ou réutilisez-en un existant. Si vous ne possédez pas encore de compte Google, vous devez en créer un.
  2. Vous devez ensuite activer la facturation dans la console Cloud pour utiliser les ressources Cloud. L'exécution de cet atelier de programmation devrait coûter moins de quelques centimes. Les nouveaux utilisateurs de Google Cloud peuvent également bénéficier du programme d'essai sans frais pour bénéficier d'un crédit de 300 $.
  3. Notez votre ID de projet (un nom unique pour tous les projets Google Cloud). Vous en aurez besoin pour configurer et déployer l'agent.

Obtenir une clé API Google AI Studio

Pour utiliser les modèles Gemini, vous avez besoin d'une clé API provenant de Google AI Studio.

  1. Accédez à Google AI Studio.
  2. Cliquez sur Get API Key (Obtenir une clé API).
  3. Créez une clé ou utilisez-en une existante. Copiez la clé pour l'utiliser ultérieurement.

4. Créer la structure du projet d'agent Blog Writer

Dans cette étape, vous allez configurer le répertoire et les fichiers pour héberger le code de votre agent de rédaction de blogs sur votre machine locale.

1. Créer l'espace de travail de l'agent de rédaction de blogs

Ouvrez votre terminal et exécutez les commandes suivantes pour créer un répertoire dédié à votre agent de rédaction de blogs et y accéder :

mkdir bloggeragent
cd bloggeragent

2. Initialiser les fichiers de l'agent

Le framework Google ADK charge les workflows d'agent directement à partir du répertoire de votre projet. Créez les fichiers nécessaires directement à la racine de bloggeragent :

touch requirements.txt .env __init__.py agent.py

5. Installer les dépendances et configurer l'environnement

Dans cette étape, vous allez configurer un environnement virtuel Python, installer le framework Google ADK et configurer les variables d'environnement pour authentifier votre agent de blog avec le modèle Gemini.

1. Configurer les exigences de l'agent

Ouvrez le fichier requirements.txt dans le répertoire bloggeragent et spécifiez les packages nécessaires à l'agent de rédaction de blogs en y ajoutant les éléments suivants :

google-adk==2.2.0
python-dotenv

2. Créer un environnement virtuel pour l'agent

À partir du répertoire bloggeragent, créez et activez un environnement virtuel Python pour isoler les packages de l'agent :

python3 -m venv .venv
source .venv/bin/activate

3. Installer le framework ADK

Installez les dépendances définies dans votre fichier requirements.txt pour équiper votre espace de travail local avec le Google ADK :

pip install -r requirements.txt

4. Configurer les identifiants de l'API Agent

Ouvrez le fichier .env que vous avez créé dans la racine du projet et ajoutez votre clé API Gemini :

GOOGLE_API_KEY=your_api_key

Remplacez your_api_key par la clé que vous avez copiée depuis Google AI Studio.

6. Créer le rédacteur de blog multi-agents

Dans cette étape, vous allez implémenter le workflow principal de votre système d'agent de rédaction de blogs.

Au lieu d'un simple chatbot à requête unique, vous allez créer un système multi-agents complexe qui utilise des boucles d'autocorrection et la vérification des plans pour rédiger des articles techniques de haute qualité. Cela suit le schéma Délibératif/Planification dont nous avons parlé précédemment.

Présentation de l'architecture

img/agent-architecture.png

Voici comment les agents spécialisés de votre système interagissent :

Configurer init.py

Ouvrez __init__.py dans votre éditeur de texte et ajoutez l'importation suivante pour exposer le workflow de l'agent au runner :

from . import agent

Écrire le workflow de l'agent de rédaction de blogs

Ouvrez agent.py dans votre éditeur de code et ajoutez le code suivant, qui définit le planificateur, le rédacteur, les vérificateurs de validation et l'agent Blogger principal :

import os
import sys
from pathlib import Path
import datetime

from dotenv import load_dotenv
from google.adk.agents import Agent, LoopAgent
from google.adk.tools import agent_tool

# env config
load_dotenv()

MODEL = os.getenv("MODEL", "gemini-flash-latest")

# Sub-Agent: Planner
blog_planner = Agent(
   name="BlogPlanner",
   model=MODEL,
   description="Creates a practical, skimmable outline in Markdown.",
   instruction="""
You are a technical content strategist. Produce a clear Markdown outline with:
- Title
- Short intro
- 4–6 main sections (each with 2–3 bullets)
- Conclusion

If `codebase_context` exists in state, weave in specific sections/snippets.
Return only the outline in Markdown.
""",
   output_key="blog_outline",
)

class OutlineValidationChecker(Agent):
   def __init__(self):
       super().__init__(
           name="OutlineValidationChecker",
           model=MODEL,
           description="Validates that the outline is usable.",
           instruction="""
Check the outline in state `blog_outline`. If it has a title, intro, 4–6 sections, and a conclusion, respond exactly "ok".
Otherwise respond exactly "retry" and list missing pieces.
""",
           output_key="validation_result",
       )

robust_blog_planner = LoopAgent(
   name="RobustBlogPlanner",
   description="Retries planning if validation fails.",
   sub_agents=[blog_planner, OutlineValidationChecker()],
   max_iterations=3,
)

# Sub-Agent: Writer
blog_writer = Agent(
   name="BlogWriter",
   model=MODEL,
   description="Writes a technical blog post from the outline.",
   instruction="""
Write a complete Markdown article from the outline in `blog_outline`.

Guidelines:
- Audience: software engineers; skip basics and focus on practical insight.
- Explain both the 'how' and 'why'.
- Include concise code snippets when helpful.
- Follow the outline's structure (H2/H3).
- Output only the final article in Markdown (no fence around the whole post).
""",
   output_key="blog_post",
)

class BlogPostValidationChecker(Agent):
   def __init__(self):
       super().__init__(
           name="BlogPostValidationChecker",
           model=MODEL,
           description="Validates the final post.",
           instruction="""
Check `blog_post` for: intro, clear sections matching the outline, conclusion, and technical clarity.
If passes, respond "ok". Else respond "retry" with the specific fixes.
""",
           output_key="validation_result",
       )

robust_blog_writer = LoopAgent(
   name="RobustBlogWriter",
   description="Retries writing if validation fails.",
   sub_agents=[blog_writer, BlogPostValidationChecker()],
   max_iterations=3,
)

# Expose planner/writer as tools so the root agent can call them explicitly
planner_tool = agent_tool.AgentTool(agent=robust_blog_planner)
writer_tool  = agent_tool.AgentTool(agent=robust_blog_writer)

# Root Agent: Plan → Write 
root_agent = Agent(
   name="Blogger",
   model=MODEL,
   description="Minimal multi-agent blogger that plans and writes.",
   instruction=f"""
If the user gives a topic:
1) Call the planner tool to generate the outline.
2) Call the writer tool to produce the full draft.
3) End with 3 alternate titles and 2 tweet-length hooks.

Date: {datetime.datetime.now().strftime("%Y-%m-%d")}
""",
   tools=[
       planner_tool, # calls RobustBlogPlanner
       writer_tool,  # calls RobustBlogWriter
   ],
)

Comprendre l'architecture de l'agent

Décomposons les principaux composants du code que vous venez d'ajouter dans agent.py pour comprendre comment il implémente le workflow de planification et d'écriture multi-agents :

1. Sous-agent BlogPlanner

L'agent blog_planner est responsable de la planification du contenu. Il prend le sujet fourni par l'utilisateur et produit un plan structuré en Markdown (avec un titre, une introduction, 4 à 6 sections et une conclusion). Le plan est enregistré dans le dictionnaire d'état partagé sous la clé "blog_outline".

2. OutlineValidationChecker

L'agent OutlineValidationChecker sert de contrôle qualité. Il examine le "blog_outline" généré dans l'état. Si le plan est valide, il répond par "ok". Sinon, il renvoie "retry" avec une liste des éléments manquants.

3. Boucle RobustBlogPlanner

Pour éviter que l'agent produise des plans incorrects, nous encapsulons le planificateur et le vérificateur de validation dans un LoopAgent appelé robust_blog_planner. Si la validation échoue et renvoie "retry", la boucle exécute automatiquement le planificateur à nouveau, jusqu'à trois fois, ce qui garantit l'autocorrection avant de passer à l'étape suivante.

4. Sous-agent BlogWriter

Une fois le plan finalisé, l'agent blog_writer lit "blog_outline" à partir de l'état et génère l'article technique complet au format Markdown, en respectant la structure du plan et en l'adaptant aux ingénieurs logiciels.

5. Boucle BlogPostValidationChecker et RobustBlogWriter

Comme pour le plan, l'article final est validé par BlogPostValidationChecker pour s'assurer que toutes les sections clés sont présentes et claires. Le rédacteur et le vérificateur sont inclus dans la boucle robust_blog_writer, ce qui lui permet de s'autocorriger jusqu'à trois fois si le vérificateur détecte des problèmes.

6. Exposer des boucles en tant qu'outils

Nous encapsulons la boucle du planificateur (robust_blog_planner) et la boucle de l'écrivain (robust_blog_writer) en tant qu'outils (planner_tool et writer_tool) à l'aide de AgentTool. Cela permet à d'autres agents d'appeler ces workflows complexes comme s'il s'agissait d'outils simples.

7. Agent racine Blogger

root_agent (nommé Blogger) orchestre l'ensemble du workflow. Lorsqu'un thème lui est donné, ses instructions la guident pour :

  1. Appelez planner_tool pour générer le plan validé.
  2. Appelez writer_tool pour rédiger le brouillon en fonction de ce plan.
  3. Pour terminer, générez trois titres alternatifs et deux accroches pour des tweets.

Cette architecture en boucle multi-agents assure la fiabilité en détectant et en corrigeant les erreurs de mise en forme ou de structure du LLM avant d'afficher le résultat à l'utilisateur.

7. Exécuter et tester l'agent

Il est maintenant temps de voir votre agent en action !

1. Démarrer l'UI Web ADK

Assurez-vous d'être dans le répertoire racine du projet bloggeragent dans votre terminal et que votre environnement virtuel est actif (source .venv/bin/activate), puis démarrez l'interface Web :

adk web

2. Interagir avec l'agent

  1. Ouvrez votre navigateur et accédez à http://127.0.0.1:8000 (ou au port que vous avez spécifié).
  2. L'UI Web ADK devrait s'afficher avec l'agent Blogger chargé et sa présentation visuelle (montrant l'agent racine Blogger pointant vers les outils RobustBlogPlanner et RobustBlogWriter) :Graphique de l'agent Blogger de l'UI Web ADK
  3. Saisissez un thème technique dans la zone de message, puis appuyez sur Entrée. Voici quelques requêtes de test intéressantes que vous pouvez utiliser pour évaluer votre agent :
    • How to build an AI agent using planning loops
    • Explain the difference between REST and gRPC in microservices
    • A guide to using Python's asyncio for backend concurrency
    • Why developers should use Docker for local database setups
  4. Regardez la trace d'exécution dans l'UI. Vous verrez BlogPlanner créer le plan, OutlineValidationChecker le valider et BlogWriter rédiger la version finale en fonction du plan :Trace et sortie de conversation de l'UI Web de l'ADK

8. Déployer dans Cloud Run

Maintenant que vous avez vérifié que l'agent fonctionne en local, déployons-le sur Google Cloud Run pour que d'autres utilisateurs puissent l'utiliser.

Google Cloud Run est une plate-forme de calcul gérée qui permet d'exécuter des conteneurs sans état accessibles via des requêtes Web ou des événements Pub/Sub.

1. Conditions préalables au déploiement

Pour déployer l'agent de rédaction de blogs sur Cloud Run, vous devez installer et authentifier Google Cloud CLI (gcloud) sur votre machine locale :

  1. Installez Google Cloud CLI : si vous ne l'avez pas déjà fait, suivez le guide d'installation de Google Cloud CLI pour votre système d'exploitation (macOS, Windows ou Linux).
  2. Authentifiez votre terminal local : une fois installé, exécutez la commande suivante dans votre terminal pour vous connecter à votre compte Google Cloud :
    gcloud auth login
  3. Vérifiez l'authentification : assurez-vous que vous êtes bien connecté à votre compte et que vous pouvez accéder à vos ressources Google Cloud :
    gcloud auth list

2. Configurer un projet Google Cloud

Définissez votre projet actif dans le terminal :

gcloud config set project <YOUR_PROJECT_ID>

Activez les services Google Cloud nécessaires pour créer et déployer votre agent conteneurisé :

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

Étant donné que la commande de déploiement ADK utilise Google Cloud Build pour automatiser le processus de compilation, vous devez accorder au compte de service Compute par défaut l'autorisation d'utiliser Cloud Build.

Recherchez votre numéro de projet en exécutant la commande suivante :

gcloud projects describe <YOUR_PROJECT_ID> --format="value(projectNumber)"

Exécutez les commandes suivantes pour associer les rôles IAM requis (remplacez par l'ID de votre projet et par le numéro renvoyé par la commande ci-dessus).

  1. Accordez à Cloud Build l'autorisation de compiler votre conteneur :
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
  --member="serviceAccount:<PROJECT_NUMBER>-compute@developer.gserviceaccount.com" \
  --role="roles/cloudbuild.builds.builder"
  1. Accordez l'autorisation d'accès à Gemini Enterprise afin que l'agent déployé puisse appeler les modèles Gemini sans avoir besoin d'une clé API :
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
  --member="serviceAccount:<PROJECT_NUMBER>-compute@developer.gserviceaccount.com" \
  --role="roles/aiplatform.user"

3. Configurer des variables d'environnement locales

Pour simplifier la commande de déploiement et éviter les fautes de frappe, définissez l'ID de votre projet comme variable d'environnement dans votre session de terminal :

export PROJECT_ID="<YOUR_PROJECT_ID>"

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

L'interface de ligne de commande ADK fournit une commande simplifiée pour déployer votre agent sur Cloud Run.

Assurez-vous que votre environnement virtuel est actif et que vous vous trouvez dans le répertoire du projet bloggeragent, puis exécutez la commande de déploiement :

# Deploy using ADK
adk deploy cloud_run \
  --project=$PROJECT_ID \
  --region=us-east1 \
  --service_name=bloggeragent \
  --with_ui \
  . \
  -- \
  --set-env-vars GOOGLE_GENAI_USE_VERTEXAI=TRUE,MODEL=gemini-3.5-flash,GOOGLE_CLOUD_LOCATION=global

Lors du processus de déploiement, les deux questions suivantes s'affichent dans votre terminal :

  1. Confirmez la création du dépôt :
    Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region [us-east1] will be created.

Do you want to continue (Y/n)?
    Saisissez Y et appuyez sur Entrée.
  2. Autoriser l'accès non authentifié :
    Allow unauthenticated invocations to [bloggeragent] (y/N)?
    Saisissez y et appuyez sur Entrée (cela vous permet d'accéder publiquement à l'UI Web d'ADK dans votre navigateur).

5. Accéder à votre agent déployé

Une fois le déploiement terminé, la commande génère une URL. Ouvrez cette URL dans votre navigateur pour accéder à l'UI Web ADK en direct et accessible au public.

9. Effectuer un nettoyage

Pour éviter que les ressources créées lors de cet atelier de programmation ne soient facturées en permanence sur votre compte Google Cloud, supprimez-les.

1. Supprimer le service Cloud Run

Supprimez le service bloggeragent déployé :

gcloud run services delete bloggeragent --region=us-east1 --quiet

2. Supprimer le dépôt Artifact Registry

Supprimez le dépôt Docker créé pour stocker les images de conteneurs générées :

gcloud artifacts repositories delete cloud-run-source-deploy --location=us-east1 --quiet

3. Arrêter le serveur local

Pour arrêter le serveur ADK local, appuyez sur CTRL+C dans le terminal où il s'exécute, puis désactivez l'environnement virtuel :

deactivate

10. Félicitations

Félicitations ! Vous avez créé votre premier agent d'IA à l'aide de l'ADK et de Gemini de Google.

Connaissances acquises

  • Les concepts fondamentaux des agents d'IA (raisonnement et action).
  • Comment utiliser Google ADK pour créer un système multi-agents.
  • Découvrez comment exécuter et tester votre agent à l'aide de l'UI Web.

Étapes suivantes

  • Essayez d'ajouter des outils à votre agent (comme la recherche sur le Web ou les appels d'API).
  • Restez à l'écoute pour la vidéo 2, où nous intégrerons un serveur MCP.

Documents de référence