google/adk-js : le SDK d'agents en TypeScript qui mise sur le code plutôt que sur la configuration
An open-source, code-first Typescript toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.
En bref
- De quoi s’agit-il ?
- ADK pour TypeScript est un kit d'agents publié sous Apache-2.0, qui se pilote depuis un fichier agent.ts et se lance via la CLI @google/adk-devtools. Le point à vérifier avant de l'adopter n'est pas la richesse des fonctionnalités, c'est la façon dont vous allez gérer la clé d'API et le déploiement.
- À qui s’adresse-t-il ?
- À adopter si votre équipe écrit du TypeScript et veut garder l'orchestration dans le dépôt, avec des schémas Zod comme seule source de vérité. À éviter si vous cherchez un graphe d'agents modifiable sans redéploiement, ou si la dépendance à une clé Google AI Studio et à des modèles Gemini n'est pas négociable.
- Puis-je l’utiliser commercialement ?
- Oui. Apache-2.0 est une licence permissive : vous pouvez utiliser, modifier et vendre un logiciel qui en dépend, à condition de conserver les mentions de droit d’auteur et de licence.
- Est-il encore maintenu ?
- Oui. Le dépôt a reçu de nouveaux commits au cours des dernières 24 heures.
- En quel langage est-il écrit ?
- Principalement TypeScript, d’après les statistiques de langage de GitHub.
Ces réponses reposent sur les données GitHub du projet (dernière synchronisation le 15 septembre 2026) et sur notre analyse. Elles ne constituent pas un avis juridique.
ANALYSE OPEN SOURCE APPROFONDIE
Le problème concret : l'orchestration d'agents écrite quelque part d'autre que votre dépôt
La plupart des outils d'agents demandent de décrire le comportement dans un format intermédiaire, un YAML ou un éditeur visuel, puis de faire le pont avec le code applicatif. ADK prend le chemin inverse. Le README annonce une approche code-first : le comportement de l'agent, l'orchestration et l'usage des outils sont définis directement dans du TypeScript. Le public visé est donc une équipe qui a déjà un dépôt Node.js, une revue de code, une CI, et qui ne veut pas ajouter une couche de configuration à synchroniser avec le reste. Le README va jusqu'à présenter cette approche comme ce qui rend possible le débogage, le versioning et le déploiement, ce qui est une manière de dire que le diff Git devient l'unité de revue d'un agent. C'est un choix qui a un coût : un agent décrit en code n'est pas modifiable par un utilisateur non technique, et toute modification passe par une revue et un redéploiement.
Un LlmAgent, des outils, et un schéma Zod comme contrat
Le mécanisme visible dans le README tient en un objet. On importe LlmAgent et GOOGLE_SEARCH depuis @google/adk, puis on exporte une constante rootAgent construite avec un nom, une description, un identifiant de modèle, une instruction et une liste d'outils. L'export nommé rootAgent n'est pas décoratif : c'est le point d'entrée que la CLI va chercher dans le fichier. Le modèle de l'exemple est gemini-flash-latest, et l'outil GOOGLE_SEARCH est un outil intégré, pas une fonction que vous écrivez. Pour les outils maison, la documentation annonce que les paramètres acceptent des schémas Zod v3 et v4 avec inférence de type à la compilation. C'est le point le plus intéressant du projet : le schéma qui décrit les arguments d'un outil sert à la fois au modèle et au compilateur TypeScript. L'orchestration multi-agents est présentée comme composable en workflows séquentiels, parallèles, en boucle et routés, avec délégation vers des agents distants via le protocole A2A. Aucun de ces détails d'implémentation n'est exposé dans le README, donc leur ergonomie réelle reste à constater sur les exemples du dépôt adk-samples.
Installation et lancement : deux paquets, une variable d'environnement, et un piège npx
Le prérequis est explicite : Node.js 20.19 ou plus récent. L'installation se fait en deux temps, avec le SDK en dépendance de production et les outils de développement en dépendance de développement. L'authentification passe par une variable GOOGLE_GENAI_API_KEY déposée dans un fichier .env à côté de l'agent, ou, en mode Vertex AI, par GOOGLE_GENAI_USE_VERTEXAI=1 accompagné de GOOGLE_CLOUD_PROJECT et GOOGLE_CLOUD_LOCATION, avec gcloud auth application-default login en amont. Le lancement se fait depuis le répertoire de l'agent, avec npx @google/adk-devtools run agent.ts pour la CLI interactive et npx @google/adk-devtools web pour l'interface de développement. Le README insiste sur un point qui mérite d'être répété : il faut toujours nommer le paquet. Écrire npx adk sans le scope télécharge et exécute un paquet adk sans rapport depuis le registre public. C'est le genre de détail qui se transforme en incident si personne ne l'a lu, et le fait que le README le signale suggère que le cas s'est déjà produit.
Ce que la documentation ne dit pas
Le README décrit des capacités, pas des garanties. Il annonce des bundles ESM, CommonJS et web, et la possibilité d'exécuter un agent dans Node.js ou directement dans le navigateur, sans expliquer comment les appels de modèle et les clés sont gérés côté navigateur, ce qui est précisément la question difficile. Il mentionne des outils intégrés pour Google Search, Google Maps, Vertex AI Search et le contexte d'URL, ainsi que la connexion de serveurs MCP et l'exécution de code, sans donner la liste des clés de configuration associées. La commande de déploiement adk deploy cloud_run est citée en une ligne, sans exemple de configuration ni de gestion des secrets. Enfin, le versionnement est inhabituel : les releases main-v2.0.0, integrations-v2.0.0 et devtools-v2.0.0 datent du 21 août 2026 et portent des noms de branches, ce qui indique une publication coordonnée par paquet plutôt qu'une version unique du projet. Avant de vous engager, vérifiez quelle version de @google/adk correspond à quelle version de @google/adk-devtools.
L'alternative : un runtime d'agent piloté par la configuration
Le concurrent direct n'est pas un autre SDK TypeScript, c'est une plateforme d'orchestration où le graphe d'agents vit en dehors du code. LangChain et LangGraph, par exemple, séparent la définition du graphe de son exécution et permettent de modifier les transitions sans toucher au code applicatif. La différence de fond est le lieu de la vérité. Avec ADK, la vérité est le fichier agent.ts versionné, et une modification de comportement suit le cycle de vie d'une pull request. Avec un graphe configuré, la vérité est dans la plateforme, et une modification peut être appliquée à chaud, au prix d'un écart possible entre ce qui tourne et ce qui est dans le dépôt. Aucune des deux approches n'est meilleure dans l'absolu : la première convient à une équipe d'ingénieurs qui veut relire et tester chaque changement, la seconde à une organisation qui doit ajuster un agent sans redéployer. ADK tranche clairement pour la première, et le README le revendique.
Licence et coût de maintenance
Le projet est publié sous Apache-2.0, avec un fichier LICENSE à la racine. Cette licence permet l'usage commercial, la modification et la redistribution, à condition de conserver les mentions de copyright et le texte de licence, et elle inclut une concession de brevet. Elle n'offre aucune garantie. Le coût de maintenance réel se lit ailleurs : la version 2.0.0 marque une rupture majeure par rapport à une 1.x, et le découpage en trois paquets publiés séparément signifie que les montées de version doivent être coordonnées entre le SDK et les outils de développement. Le README ne fournit ni politique de support, ni calendrier de dépréciation, ni guide de migration. Pour un projet en production, cela veut dire épingler les versions et lire les notes de release à chaque mise à jour, plutôt que de suivre la dernière publication.
Pour qui ce kit est un bon choix
ADK pour TypeScript s'adresse à une équipe qui écrit déjà du Node.js, qui a un pipeline de tests, et pour qui le typage des arguments d'outils est un vrai gain : le schéma Zod décrit une seule fois sert au modèle et au compilateur. Il s'adresse aussi à ceux qui veulent exécuter un agent dans un navigateur, puisque des bundles web sont annoncés, même si la documentation disponible ne détaille pas ce scénario. Il ne convient pas à une organisation qui doit laisser des non-développeurs ajuster le comportement d'un agent, ni à celle qui refuse de dépendre de l'écosystème Google pour l'authentification et les modèles. Le chemin le plus court pour se décider reste de créer un agent minimal, de lancer npx @google/adk-devtools web, et de regarder ce que l'interface affiche comme trace d'appel d'outil. Si cette trace ne vous suffit pas pour déboguer, l'approche code-first n'apportera pas le bénéfice attendu.
Conclusion éditoriale
À adopter si votre équipe écrit du TypeScript et veut garder l'orchestration dans le dépôt, avec des schémas Zod comme seule source de vérité. À éviter si vous cherchez un graphe d'agents modifiable sans redéploiement, ou si la dépendance à une clé Google AI Studio et à des modèles Gemini n'est pas négociable. Vérifiez d'abord que votre runtime Node dépasse 20.19, puis lancez npx @google/adk-devtools web sur l'agent d'exemple pour voir ce que la CLI attend réellement comme structure de projet.
Notes de la communauté