Sous-agents ou agent teams : lequel choisir dans Claude Code

Mis à jour le 2026-11-03

Claude Code peut faire travailler plusieurs agents de deux façons : avec des sous-agents, ou avec des agent teams. Ce guide t’aide à choisir. Les agent teams sont expérimentaux et désactivés par défaut : tant que tu ne les actives pas, Claude ne crée aucune équipe. Pour l’équipe qui coordonne des sous-agents, lis le guide Chief of Staff. Pour des fichiers à copier, lis les exemples de sous-agents. Retour à l’accueil.

En bref

Commence par des sous-agents. Un sous-agent fait une tâche ciblée et renvoie son résultat : c’est le bon choix quand seul ce résultat compte.

Passe aux agent teams quand les coéquipiers doivent partager leurs découvertes, se contester et se coordonner entre eux : une revue sous plusieurs angles, ou un débogage avec des hypothèses concurrentes. Ce choix consomme nettement plus de jetons, et les agent teams restent expérimentaux.

Les sous-agents

Un sous-agent est un agent lancé par la session principale pour une tâche précise. Il démarre avec sa propre fenêtre de contexte, travaille seul, puis renvoie un résultat à l’appelant. La session principale reçoit ce résultat, et non toutes les lectures de fichiers qui y ont mené.

Un sous-agent nommé peut aussi écrire à d’autres agents. Mais, tant que les agent teams ne sont pas activés, il reste un agent ordinaire qui rend compte à l’appelant. Le format d’un fichier d’agent est décrit dans la documentation officielle des sous-agents.

Les agent teams

Une agent team est une équipe de plusieurs instances de Claude Code. La session qui la dirige est le team lead : il coordonne, attribue les tâches et synthétise. Chaque coéquipier travaille dans sa propre fenêtre de contexte, de façon totalement indépendante, et peut écrire directement aux autres.

La liste de tâches partagée indique l’état de chaque tâche (en attente, en cours, terminée) et ses dépendances. Un coéquipier réserve une tâche avant de la prendre, grâce à un verrou sur le fichier.
La boîte aux lettres transporte les messages entre agents.
Un coéquipier charge le même contexte projet qu’une session normale : CLAUDE.md, serveurs MCP et skills. Il reçoit le prompt de lancement du lead, mais pas l’historique de ce lead.

Pour lancer une équipe, décris en langage naturel la tâche et les coéquipiers voulus. Exemple tiré de la documentation :

Spawn three teammates to explore this from different angles: one on UX, one on technical architecture, one playing devil's advocate.

Tu peux aussi lancer un coéquipier à partir d’une définition de sous-agent existante, par exemple security-reviewer : ses champs tools et model s’appliquent, pas skills. Les détails sont dans la documentation officielle des agent teams.

Statut expérimental

Les agent teams sont expérimentaux et désactivés par défaut. Sans l’activation décrite plus bas, Claude ne lance ni ne propose de coéquipiers.

Comparer sur cinq critères

La documentation officielle compare les deux sur cinq critères :

Contexte : chaque sous-agent a sa propre fenêtre, et ses résultats reviennent à l’appelant. Chaque coéquipier a sa propre fenêtre, totalement indépendante.
Communication : les sous-agents renvoient un résultat à l’appelant. Les coéquipiers s’écrivent directement.
Coordination : avec des sous-agents, l’agent principal gère tout. Avec les agent teams, les coéquipiers se coordonnent entre eux, par messages et par une liste de tâches partagée.
Idéal pour : des tâches ciblées où seul le résultat compte, pour les sous-agents ; un travail complexe qui demande discussion et collaboration, pour les agent teams.
Coût en jetons : plus faible avec les sous-agents, car leurs résultats résumés entrent dans le contexte principal. Plus élevé avec les agent teams, car chaque coéquipier est une instance de Claude.

La documentation résume ainsi : des sous-agents pour des travailleurs rapides et ciblés qui rendent compte, des agent teams quand les coéquipiers doivent partager leurs découvertes, se contester et se coordonner seuls.

Quand choisir l’un ou l’autre

Les agent teams valent leur coût dans les cas que la documentation cite :

Recherche et revue : plusieurs angles en parallèle, avec des coéquipiers qui peuvent se contredire.
Modules ou fonctionnalités indépendants : un coéquipier par morceau.
Débogage avec des hypothèses concurrentes : chaque coéquipier suit une piste, et les autres la contestent.
Coordination entre couches : front, back et tests, chacun dans son périmètre.

La documentation met aussi en garde : les agent teams ajoutent de la coordination et consomment nettement plus de jetons qu’une session unique. Pour des tâches séquentielles, des modifications du même fichier ou beaucoup de dépendances, une session unique ou des sous-agents sont plus efficaces.

Activer les agent teams

Les agent teams sont désactivés par défaut. Pour les activer dans une seule session, place la variable dans l’environnement :

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

Pour les activer pour un projet, ajoute la variable sous la clé env de .claude/settings.json. Ce fichier contient peut-être d’autres réglages : ajoute seulement cette clé.

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Effet de bord sur les sous-agents

Une fois les agent teams activés, un sous-agent que Claude nomme peut démarrer comme coéquipier, sauf fork ou isolation sur l’appel. Claude nomme parfois des sous-agents de lui-même : une équipe peut donc se former sans que tu l’aies demandée. Pour revenir aux seuls sous-agents, mets la variable à 0.

En mode non interactif, avec l’option -p ou dans l’Agent SDK, Claude ne lance pas de coéquipiers : un sous-agent nommé reste alors un sous-agent ordinaire. Les agent teams demandent donc une session interactive.

Bonnes pratiques et limites

Ces points viennent de la documentation sur les bonnes pratiques et les limites.

Commence avec 3 à 5 coéquipiers. Le coût en jetons croît avec chacun, et la documentation note que trois coéquipiers bien ciblés font souvent mieux que cinq dispersés.
Vise 5 à 6 tâches par coéquipier. Donne dans le prompt de lancement assez de contexte : un coéquipier n’hérite pas de l’historique du lead.
Évite que deux coéquipiers modifient le même fichier. Commence par de la recherche ou de la revue plutôt que par de l’implémentation en parallèle.
Une équipe par session. Pas d’équipe imbriquée : un coéquipier ne lance pas de coéquipiers, et le lead ne change pas.
/resume et /rewind ne restaurent pas les coéquipiers en mode in-process, qui est le mode par défaut. Ne compte pas sur eux pour reprendre une équipe.
Le statut des tâches peut être en retard. Le mode à panneaux séparés demande tmux ou iTerm2 ; le mode par défaut fonctionne dans tout terminal.

Et avec Swarmbuilder

Swarmbuilder ne configure pas d’agent team. Il génère des sous-agents dans .claude/agents/ et un Chief of Staff, lancé par claude --agent chief-of-staff. C’est le modèle sous-agents décrit plus haut, et il fonctionne sans activer les agent teams.

Les définitions générées peuvent aussi servir de types de coéquipiers si tu actives les agent teams. Attention alors : les sous-agents que le Chief nomme peuvent démarrer comme coéquipiers, comme décrit dans la section d’activation.

Pour la structure du Chief, lis le guide Chief of Staff. Pour des fichiers complets à copier, lis les exemples de sous-agents. Retour à l’accueil.