Sommaire
Lorsque vous voulez répartir le travail entre plusieurs IA dans Claude Code, il existe deux mécanismes semblables mais distincts — les subagents et les Agent Teams. Les noms prêtent à confusion, mais leurs rôles et leurs modes de coordination sont fondamentalement différents. Cet article fait le point sur ce qu'est chacun, la différence décisive, lequel utiliser et comment — en s'appuyant sur la documentation officielle.
Trois points cruciaux d'emblée. (1) Les subagents sont une fonctionnalité intégrée — l'agent principal délègue une sous-tâche ciblée à un « assistant à contexte neuf » et ne récupère qu'un résumé (hiérarchique, éphémère). (2) Les Agent Teams sont une fonctionnalité expérimentale, à activer explicitement, désactivée par défaut. Elles ne fonctionnent qu'une fois que vous avez défini CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 — plusieurs sessions indépendantes se coordonnent en pairs via une liste de tâches partagée (de pair à pair, persistant). (3) La « profondeur d'imbrication de 5 niveaux » est une fonctionnalité des subagents ; les Agent Teams ne peuvent pas s'imbriquer (elles sont plates) — ne confondez pas les deux.
Hiérarchie, ou pairs ?
— déléguer et récupérer un résumé, ou se coordonner en égaux
Subagents : l'agent principal confie une tâche à un assistant et en récupère le résultat. Agent Teams : des pairs égaux se coordonnent via une liste de tâches partagée.
Les Teams sont une fonctionnalité expérimentale désactivée par défaut — CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 est obligatoire.
1. Ce que sont les subagents
Les subagents sont des agents spécialisés qui prennent en charge des types de travail précis au sein d'une même session. Selon la documentation officielle, « chaque subagent s'exécute dans sa propre fenêtre de contexte, avec un system prompt personnalisé et des permissions d'outils spécifiques. » L'agent principal délègue automatiquement en fonction de la description de chaque subagent, et le subagent travaille de façon autonome puis ne renvoie qu'un résumé à la conversation principale.
L'essentiel, c'est que « chaque subagent s'exécute dans un contexte neuf et séparé » — il ne voit ni votre historique de conversation ni les fichiers que vous avez déjà lus. Vous pouvez donc lui faire effectuer de lourdes recherches « à l'extérieur » et ne recevoir que la conclusion, sans inonder votre contexte principal de logs ou de sorties de tests. Gérez-les avec /agents (onglets Running / Library). Définissez-les dans .claude/agents/<name>.md avec un frontmatter YAML (name / description / tools / model). Les agents intégrés incluent Explore (Haiku, lecture seule), Plan et general-purpose. Les subagents peuvent s'imbriquer, jusqu'à 5 niveaux de profondeur (au niveau 5, l'Agent tool n'est pas transmis, de sorte qu'ils ne peuvent plus en engendrer d'autres). Pour une vue d'ensemble, voir Qu'est-ce qu'un système multi-agents.
2. Ce que sont les Agent Teams (expérimental, sous flag)
Les Agent Teams vous permettent de coordonner plusieurs sessions Claude Code en tant qu'« équipe ». L'une est le team lead (elle coordonne, attribue, synthétise) ; les autres sont des teammates — chacun sa propre session et son propre contexte indépendants — qui communiquent directement entre eux via une liste de tâches partagée et une mailbox. Contrairement aux subagents, vous pouvez dialoguer directement avec chaque teammate.
Important : les Agent Teams sont une fonctionnalité expérimentale, désactivée par défaut
La documentation officielle indique clairement que « les agent teams sont expérimentales et désactivées par défaut. » Pour les utiliser, définissez la variable d'environnement CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 (ou via le env de settings.json). Sans cela, aucune équipe n'est créée au démarrage et Claude ne proposera ni n'engendrera de teammates.
Notez que le changement de la v2.1.178 a seulement « supprimé l'étape de configuration TeamCreate/TeamDelete, de sorte qu'avec le flag activé chaque session dispose d'une équipe implicite » — il n'a pas « activé les teams par défaut. » Le flag reste obligatoire.
3. La différence décisive
Mis côte à côte, les deux ont des manières de se coordonner totalement différentes.
| Subagents | Agent Teams | |
|---|---|---|
| Coordination | Hiérarchique (le principal délègue, agrège les résultats) | De pair à pair (se coordonnent eux-mêmes via une liste de tâches partagée) |
| Communication | Rendent compte à l'appelant uniquement (ne se parlent jamais) | Les teammates s'échangent des messages directement entre eux via la mailbox |
| Persistance | Éphémère (renvoient un résumé une fois la tâche terminée) | Sessions indépendantes persistantes (vous les pilotez directement) |
| Contexte | Contexte propre et neuf ; le résumé revient au principal | Totalement indépendant (rien n'est résumé en retour automatiquement) |
| Coût en tokens | Relativement faible | Élevé (chaque teammate est une instance Claude distincte) |
| Statut | Intégré, toujours disponible | Expérimental, sous flag, désactivé par défaut |
| Imbrication | Les subagents s'imbriquent jusqu'à 5 niveaux | Pas d'imbrication (les teammates ne peuvent pas engendrer de teammates) |
En une phrase : Subagents = « l'agent principal confie une tâche ciblée à un assistant à contexte neuf et en récupère la conclusion (hiérarchique, éphémère, résumé seulement). » Agent Teams = « plusieurs sessions persistantes se coordonnent via une liste de tâches partagée et la messagerie, et vous pouvez piloter chacune (pairs, indépendantes). » Une erreur fréquente : l'« imbrication sur 5 niveaux » est une fonctionnalité des subagents, tandis que les Teams sont plates (sans imbrication).
4. Lequel utiliser
Choisissez selon l'objectif et vous ne vous tracasserez plus. La majorité du travail quotidien se gère très bien avec les subagents (ou une seule session).
Choisir selon l'objectif
· le travail est autonome et seul le résultat compte
· vous voulez limiter les outils ou un modèle moins cher
· les workers n'ont pas besoin de se parler
· l'exploration parallèle est payante (revue en parallèle / débogage à hypothèses concurrentes / multi-modules)
· vous voulez piloter chaque worker
(acceptez un coût plus élevé + le flag)
· vous avez besoin d'allers-retours fréquents
· elle touche les mêmes fichiers
· c'est une petite modification locale
Par défaut, optez pour « en cas de doute, une seule session ou des subagents. »
Ne recourez aux Agent Teams que pour du travail parallèle qui exige réellement une coordination entre pairs.
5. Aide-mémoire d'utilisation
Une référence rapide pour les commandes et la configuration.
# --- Subagents (intégrés) ---
/agents # gestionnaire (Running / Library)
.claude/agents/<name>.md # définition de projet (name/description/tools/model)
~/.claude/agents/<name>.md # définition utilisateur (tous les projets)
claude --agent code-reviewer # exécuter toute la session comme un subagent précis
@agent-<name> # @-mention pour l'invoquer explicitement
# --- Agent Teams (expérimental, sous flag) ---
# Activer via env (ou env de settings.json) ; DÉSACTIVÉ par défaut
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
# Puis décrire en langage naturel, p. ex. : « Lance trois teammates pour revoir la PR #142 :
# un pour la sécurité, un pour la performance, un pour la couverture de tests. »
# Affichage via teammateMode (par défaut in-process ; les panneaux fractionnés nécessitent tmux/iTerm2)Dans un fichier de définition de subagent, vous pouvez restreindre les outils avec tools ou router vers un modèle plus léger comme haiku grâce à model. Pour construire et concevoir des agents, voir Comment construire un système multi-agents et Comment construire un agent IA.
6. Points de vigilance sur les Agent Teams
Les Agent Teams sont puissantes, mais s'accompagnent de limites et d'un coût propres à leur stade expérimental. Sachez-le avant de les adopter.
(1) Une équipe par session, pas d'imbrication — les teammates ne peuvent pas engendrer de teammates, et le lead est fixe. (2) Forte consommation de tokens (chaque teammate est une instance Claude distincte) ; la recommandation est de 3 à 5 teammates. (3) Les teammates ne sont pas isolés dans des worktrees, donc s'ils touchent les mêmes fichiers ils s'écrasent mutuellement — répartissez les fichiers manuellement. (4) En tant que fonctionnalité expérimentale, il existe des limites comme /resume et /rewind qui ne restaurent pas les teammates in-process. (5) L'affichage en panneaux fractionnés nécessite tmux ou iTerm2 (certains terminaux, comme celui de VS Code, ne sont pas pris en charge). En bref, ne l'utilisez que lorsque le gain d'une coordination parallèle l'emporte sur le coût et l'effort.
Conclusion
Les subagents et les Agent Teams de Claude Code « répartissent tous deux le travail entre des IA », mais leurs modèles de coordination diffèrent. Les subagents sont intégrés — l'agent principal délègue une tâche ciblée à un assistant à contexte neuf et ne récupère qu'un résumé (hiérarchique, éphémère, ne se parlent pas, s'imbriquent jusqu'à 5 niveaux). Les Agent Teams sont une option expérimentale à activer, désactivée par défaut (nécessite CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1) — plusieurs sessions indépendantes se coordonnent en pairs via une liste de tâches partagée et la messagerie (persistantes, vous pilotez chacune, pas d'imbrication).
Comment choisir : « vous ne voulez que le résultat / vous ne voulez pas polluer le contexte → subagents », « travail parallèle où les workers doivent partager et se coordonner → Agent Teams », « séquentiel / mêmes fichiers / correctif rapide → une seule session. » Une confusion fréquente : l'« imbrication sur 5 niveaux » est une fonctionnalité des subagents ; les Teams sont plates. Et notez que la v2.1.178 a rationalisé le démarrage des équipes — elle ne les a pas « activées par défaut. » Les Teams sont coûteuses et expérimentales, alors réservez-les aux cas où la coordination est payante. À lire aussi : Qu'est-ce qu'un système multi-agents, comment en construire un, l'observabilité de l'IA.
FAQ
Q. En quoi les subagents et les Agent Teams diffèrent-ils ?
A. Leur coordination est fondamentalement différente. Les subagents sont hiérarchiques — l'agent principal délègue une tâche ciblée à un assistant à contexte neuf et ne récupère qu'un résumé (les assistants ne se parlent pas ; éphémères). Les Agent Teams sont de pair à pair — plusieurs sessions indépendantes se coordonnent via une liste de tâches partagée et une mailbox, et vous pouvez piloter chacune (persistantes). Les subagents sont intégrés ; les Agent Teams sont expérimentales et nécessitent un flag.
Q. Puis-je utiliser les Agent Teams tout de suite ?
A. Non — elles sont désactivées par défaut. Vous devez définir CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 dans l'env (ou le env de settings.json). La v2.1.178 a seulement rationalisé le démarrage (elle a « supprimé l'étape de configuration TeamCreate, de sorte qu'avec le flag activé chaque session dispose d'une équipe implicite ») — elle n'a pas « activé les teams par défaut. » Le flag reste obligatoire.
Q. À quoi se réfère « s'imbrique jusqu'à 5 niveaux » ?
A. Aux subagents. Un subagent peut engendrer ses propres subagents, jusqu'à 5 niveaux de profondeur (au niveau 5, il ne peut pas aller plus loin). Les Agent Teams ne peuvent pas s'imbriquer — les teammates ne peuvent pas engendrer de teammates, et seul le lead gère l'équipe. Ne confondez pas les deux.
Q. Je n'arrive pas à savoir lequel utiliser.
A. La plupart du temps, une seule session ou des subagents suffisent. Si vous ne voulez que le résultat et ne voulez pas qu'une sortie volumineuse inonde votre contexte principal, utilisez les subagents. Si les workers doivent partager leurs trouvailles, se vérifier mutuellement et s'auto-coordonner dans un travail parallèle (revue en parallèle, débogage à hypothèses concurrentes, développement multi-modules) et que vous voulez piloter chacun, utilisez les Agent Teams. Pour un travail séquentiel, des allers-retours fréquents ou la modification des mêmes fichiers, une seule session convient.
Q. À quoi dois-je faire attention avec les Agent Teams ?
A. Forte consommation de tokens (chaque teammate est une instance distincte ; 3 à 5 recommandés), une équipe par session sans imbrication, des teammates non isolés dans des worktrees qui entrent donc en conflit sur les mêmes fichiers (répartissez manuellement), des limites expérimentales sur /resume et /rewind, et des panneaux fractionnés nécessitant tmux/iTerm2. Ne l'utilisez que pour du travail parallèle où la coordination l'emporte sur le coût.
