google/adk-python : construire des agents en Python, du Agent isolé au Workflow en graphe

Le problème : l'orchestration d'agents écrite à la main

Un agent seul tient dans quelques lignes. Dès qu'il faut router vers un spécialiste, fan-out vers plusieurs branches, puis fan-in des résultats, le code d'orchestration devient un enchaînement de conditions et d'appels asynchrones qui n'a plus rien à voir avec la logique métier. ADK attaque ce point précis avec deux classes. Agent décrit ce qu'un modèle doit faire : nom, model, instruction. Workflow décrit comment les agents s'enchaînent, sous forme de graphe. Le public visé est l'ingénieur qui veut versionner cette orchestration dans un dépôt Python plutôt que dans un fichier de configuration propriétaire. Le README positionne le projet comme model-agnostic et deployment-agnostic tout en étant optimisé pour Gemini, ce qui annonce la limite : l'intégration la plus profonde reste celle de l'écosystème Google.

Un graphe d'exécution, pas une chaîne d'appels

Le mécanisme central est un runtime de workflow. Le README énumère ce que ce moteur prend en charge : routage, fan-out/fan-in, boucles, retry, gestion d'état, nœuds dynamiques, human-in-the-loop et workflows imbriqués. L'exemple du README montre la forme minimale : un Workflow nommé root_agent reçoit une liste edges, où chaque entrée est un tuple qui va de START à un premier agent, puis à un second. La donnée produite par generate_fruit_agent alimente generate_benefit_agent, et la consigne du premier agent est explicite sur le format attendu : renvoyer uniquement le nom du fruit. Ce détail compte, car un graphe ne corrige pas une sortie mal contrainte en amont. À côté du graphe, la Task API ajoute une délégation structurée entre agents, avec un mode multi-tours, un mode mono-tour à sortie contrôlée et des agents-tâches utilisables comme nœuds de workflow. Le README ne détaille pas la forme exacte des objets échangés entre nœuds, donc la manière dont l'état circule concrètement reste à vérifier dans la documentation.

Installation et contraintes de dépendances

L'installation stable passe par pip install google-adk, avec Python 3.10 ou plus récent. Le README recommande une variante avec fichier de contraintes pour se protéger des dépendances transitives, avec des fichiers couvrant Python 3.10 à 3.14. La commande donnée en exemple télécharge constraints-3.10.txt, installe le paquet avec l'option -c, puis supprime le fichier. C'est un point à ne pas sauter : sans ce fichier, vous acceptez les résolutions de dépendances du moment. Les intégrations optionnelles s'ajoutent via pip install "google-adk[extensions]". Pour les correctifs non encore publiés, le README propose pip install git+https://github.com/google/adk-python.git@main, en précisant que cette version de développement peut contenir des changements expérimentaux ou des bugs absents de la release stable. La cadence annoncée est d'environ deux semaines entre versions.

Exécuter et déboguer en local

Deux commandes suffisent pour lancer un agent. adk run path/to/my_agent ouvre une interface en ligne de commande interactive. adk web path/to/agents_dir démarre une interface web, que le README présente comme capable de pointer vers un répertoire contenant plusieurs agents ou directement vers le dossier d'un seul agent. Cette interface sert à tester, évaluer et déboguer. Elle constitue l'argument le plus concret du projet pour un développeur seul : on obtient une boucle de test sans écrire de serveur. À l'inverse, elle ne remplace pas une suite de tests automatisés, et le README ne décrit pas de format de scénario d'évaluation exportable. Le déploiement, lui, est présenté comme un passage par conteneur, avec Cloud Run ou Vertex AI Agent Engine comme cibles citées.

La rupture 1.x vers 2.0

C'est l'information la plus lourde de conséquences du README, et elle est signalée comme telle : ADK 2.0 introduit des changements cassants dans l'API des agents, le modèle d'événements et le schéma de session. La compatibilité est asymétrique. Les sessions produites par ADK 2.0 restent lisibles par ADK 1.28 et au-delà, les champs supplémentaires étant ignorés, mais elles sont incompatibles avec les versions 1.x antérieures. Autrement dit, un retour arrière vers une version 1.x ancienne après avoir écrit des sessions en 2.0 n'est pas prévu. Pour un projet déjà en production sur une version 1.x ancienne, cela impose soit de migrer vers 1.28 ou plus avant de passer en 2.0, soit de conserver deux environnements distincts. Le README ne fournit pas de guide de migration dans l'extrait disponible, seulement l'avertissement.

Confirmation d'outils et surface d'intégration

Le point le plus intéressant pour un usage en entreprise est le flux de confirmation d'outils, décrit comme un mécanisme human-in-the-loop qui encadre l'exécution d'un outil par une confirmation explicite et une saisie personnalisée. Cela concerne directement les outils qui écrivent : envoyer un message, modifier une ressource, déclencher une action externe. La documentation y consacre une page dédiée, ce qui suggère que le mécanisme est configurable et pas seulement un interrupteur global. Côté intégration, le README liste les outils préconstruits, les fonctions personnalisées, les spécifications OpenAPI et les outils MCP. La présence de MCP est notable : elle offre une porte de sortie vers des serveurs d'outils écrits hors de l'écosystème Google, ce qui limite le verrouillage sur ce point précis. Le README ne précise pas quelles fonctionnalités exigent Gemini, donc le degré réel d'indépendance du modèle reste à établir par la documentation.

Ce qu'ADK n'est pas

Le README mentionne une fonction Agent Config permettant de construire des agents sans code, mais tout le reste du projet est explicitement code-first : la logique, les outils et l'orchestration s'écrivent en Python. Si votre besoin est de laisser des utilisateurs non développeurs composer des agents dans une interface, ADK n'est pas l'outil adapté, et le README renvoie vers sa propre page Agent Config plutôt que vers une solution no-code complète. Deuxième cas défavorable : une application mono-agent avec un seul appel de modèle. Le moteur de workflow, la Task API et la gestion d'état n'apportent alors rien, et vous payez la surface d'API d'un framework pour un script de quelques lignes. Troisième cas : une équipe déjà engagée sur LangGraph ou CrewAI, où la réécriture de l'orchestration vers des objets Agent et Workflow a un coût difficile à justifier par le seul argument du graphe.

Alternatives et différences d'approche

LangGraph modélise l'orchestration comme un graphe d'états explicite, où vous déclarez un schéma d'état typé et des fonctions de transition entre nœuds. ADK expose lui aussi des edges, mais le README insiste sur le fait que l'état, le retry et le human-in-the-loop sont pris en charge par le runtime plutôt que décrits par vous. La différence pratique est le degré de contrôle : avec LangGraph vous définissez la structure d'état, avec ADK vous définissez surtout les agents et leurs liens. CrewAI prend un autre chemin, celui d'équipes d'agents avec rôles, objectifs et délégation en langage naturel. La Task API d'ADK couvre une partie de ce besoin, la délégation entre agents, mais sous forme d'appels structurés avec un mode mono-tour à sortie contrôlée, pas de rôles conversationnels. Le choix se joue donc sur ce que vous voulez écrire vous-même : le graphe et l'état, ou les agents et leurs instructions.

Conclusion éditoriale

ADK convient aux équipes qui veulent décrire l'orchestration d'agents dans du Python versionnable, avec un runtime de workflow en graphe et une couche de confirmation d'outils. Il ne convient pas à qui doit rester sur une base ADK 1.x sans plan de migration : la release note indique que les sessions 2.0 sont lisibles par ADK 1.28+ mais incompatibles avec les versions 1.x antérieures. Avant d'adopter, vérifiez d'abord le contenu réel du fichier constraints-3.10.txt correspondant à votre version de Python, puis testez la lecture de vos sessions existantes sur la version 1.28 ou supérieure.

Sources officielles

1. google/adk-python on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases