Qu’est-ce qu’un subagent et comment l’utiliser ?

Un sous-agent travaille dans son propre contexte et vous renvoie le résultat

Quand vous confiez un gros travail à un agent de codage, il y a deux façons de faire : la conversation principale fait tout elle-même, ou elle confie une partie du travail à un sous-agent (subagent). Le sous-agent traite cette partie dans son propre contexte ; les fichiers qu’il lit et les tests qu’il lance n’encombrent pas la conversation principale.

La documentation de Cursor le dit en deux phrases : « Intermediate output stays in the subagent. The parent only sees the final summary. » Au 18 octobre 2026, cinq outils ont des sous-agents : Claude Code, Codex d’OpenAI, Cursor, Gemini CLI de Google et GitHub Copilot. Claude Code, Cursor et Copilot parlent de la fenêtre de contexte propre au sous-agent ; Gemini CLI parle d’une boucle de contexte séparée, et Codex lance les agents en parallèle puis rassemble leurs résultats en une seule réponse.

Les sous-agents sont donc utiles pour deux types de travail : les tâches dont la sortie est volumineuse (lancer des tests, parcourir des logs, lire des dizaines de fichiers) et les recherches indépendantes les unes des autres. Les exemples viennent du dépôt que nous utilisons tous les jours pour développer diffox ; nous y travaillons avec Claude Code.

Le sous-agent ne voit pas votre conversation, la consigne doit donc tout dire

L’erreur la plus fréquente avec un sous-agent est de supposer qu’il sait ce qui s’est dit dans la conversation principale. Selon la documentation de Claude Code, le sous-agent démarre avec une nouvelle fenêtre de contexte : il ne voit ni votre historique de conversation, ni les skills déjà appelés, ni les fichiers que Claude a lus. Au départ, voici ce dont il dispose :

La consigne doit donc dire d’elle-même l’objectif, les fichiers que le sous-agent peut toucher et ce qu’il doit rapporter. Ce que vous appelez « cette erreur » dans la conversation principale n’existe pas pour le sous-agent ; écrivez le chemin du fichier, le message d’erreur et la sortie attendue. La documentation de Cursor dit la même chose : les sous-agents démarrent avec un contexte vide et n’ont pas accès à l’historique de conversation précédent. Les documentations de Codex, de Gemini CLI et de Copilot n’en parlent pas ; quel que soit l’outil, écrire une consigne qui se comprend toute seule reste la voie sûre. La documentation de Codex conseille en outre de demander au sous-agent un résumé plutôt que ses sorties intermédiaires.

Où définir un sous-agent, et quand est-il appelé ?

Dans les cinq outils, un sous-agent se définit dans un fichier, au niveau du projet ou de l’utilisateur. Les outils se distinguent surtout sur un point : l’agent principal délègue-t-il le travail de lui-même ?

Source : la documentation des sous-agents de chaque outil, 18 octobre 2026. Dans Codex, la définition est un fichier TOML ; dans les autres outils, un fichier Markdown avec un en-tête YAML. L’agent navigateur de Gemini CLI est désactivé par défaut. La liste des agents intégrés de Copilot varie d’une page à l’autre : la page de référence en compte sept, le guide pratique quatre.

C’est la troisième colonne qui fait la différence. Dans Codex, elle dépend du niveau d’effort : la page des modèles indique que le niveau le plus élevé, Ultra, mène le travail en le répartissant entre des sous-agents ; la page des sous-agents, elle, dit que Codex en local lance un sous-agent sur une demande directe comme « lance deux agents », ou sur une consigne écrite dans AGENTS.md ou dans un skill. Dans les quatre autres outils, l’agent principal peut aussi déléguer de lui-même ; la documentation de Copilot précise en outre que le modèle peut tout aussi bien faire le travail lui-même, sans déléguer.

Les définitions passent d’un outil à l’autre : Cursor lit aussi les dossiers .claude/agents/ et .codex/agents/ (à nom égal, .cursor/ l’emporte), et Copilot CLI lit aussi .claude/agents/. Un fichier placé sous .claude/agents/ est donc lu par Claude Code, Cursor et Copilot CLI ; mais les documentations ne garantissent pas que les champs du frontmatter fonctionnent de la même façon dans les trois.

Le 18 juin 2026, Google a cessé de servir Gemini CLI aux utilisateurs gratuits et aux abonnés Google AI Pro et Ultra, et les a orientés vers Antigravity CLI ; avec une clé d’API payante ou une licence d’entreprise, vous pouvez continuer à utiliser Gemini CLI. Nous avons lu la documentation d’Antigravity sur les sous-agents le 28 octobre 2026. Les sous-agents se définissent dans .agents/agents/ pour un projet et dans ~/.gemini/config/agents/ pour l’utilisateur. L’agent principal confie une tâche d’après la description du sous-agent ; trois agents sont intégrés : research, browser et self. Un sous-agent ne reçoit pas l’historique de conversation de l’agent principal et part d’un contexte vierge ; si sa définition ne donne pas de modèle, il utilise celui de l’agent principal. On peut imbriquer des sous-agents jusqu’à 10 niveaux.

Un bon sous-agent a une tâche précise, peu d’outils et un rapport court à rendre

Le fichier de définition fixe trois choses : quand le sous-agent est appelé (la description), à quoi il a accès (les outils) et ce qu’il renvoie (le prompt). Dans Claude Code, il ressemble à ceci ; les champs obligatoires sont name et description :

---
name: test-runner
description: Lance les tests et ne rapporte que ceux qui échouent
tools: Read, Grep, Glob, Bash
model: haiku
---

Lance la suite de tests. Rapporte uniquement les tests en échec, chacun
avec son message d'erreur. Ne modifie aucun fichier.

• La description sert de déclencheur. Claude Code et Gemini CLI délèguent le travail en lisant la description. Écrivez-y non pas ce qu’est l’agent, mais quand il faut l’appeler.
• Limitez les outils. Dans Claude Code, le champ tools restreint les outils que le sous-agent peut utiliser ; si vous ne le remplissez pas, il hérite de tous les outils ouverts aux sous-agents. Ne donnez pas d’outil d’écriture à un agent qui doit seulement lire.
• Les permissions viennent de l’agent principal. Dans Codex, le sous-agent hérite des permissions, du fournisseur et des serveurs MCP de l’agent principal ; le fichier de définition ne peut pas les changer. Le sandbox et les paramètres d’approbation sont aussi ceux de l’agent principal.
• Demandez un rapport court. Que la dernière phrase du prompt dise ce qu’il faut renvoyer : les tests en échec, les fichiers trouvés, une décision. Si une longue sortie intermédiaire revient dans la conversation principale, l’intérêt du sous-agent est perdu.
• Vous pouvez désactiver l’usage automatique. Dans l’agent cloud de Copilot, un agent dont la définition contient disable-model-invocation: true ne s’exécute que si on le sélectionne à la main. Dans Copilot, le prompt d’un agent personnalisé peut compter au plus 30 000 caractères.

Le modèle, le parallélisme et l’imbrication varient d’un outil à l’autre

Si vous n’indiquez pas de modèle dans la définition, le sous-agent tourne, selon la documentation, avec le modèle de l’agent principal dans Claude Code, Codex, Cursor et Copilot. La page des sous-agents de Gemini CLI dit la même chose, mais la page des modèles de la même documentation indique que la commande /model et l’option --model ne changent pas le modèle des sous-agents ; les deux ne concordent pas tout à fait. Combien de sous-agents peuvent tourner en même temps, et si un sous-agent peut en lancer un autre : cela dépend de l’outil.

Source : la documentation des sous-agents de chaque outil, 18 octobre 2026. « Non précisé dans la documentation » : dans les pages que nous avons lues ce jour-là, nous n’avons trouvé aucune phrase qui donne cette information. La page de référence de Copilot CLI donne une profondeur de 4 dans la section des variables d’environnement, et de 6 dans le tableau des limites. Par défaut, Gemini CLI limite chaque sous-agent à 30 tours et 10 minutes.

Claude Code cherche le modèle à quatre endroits, dans cet ordre : le paramètre model de l’appel, le champ model de la définition, la variable d’environnement CLAUDE_CODE_SUBAGENT_MODEL, puis le modèle de la conversation principale. Ce qui se passe quand la limite est atteinte est écrit aussi : tant que 20 sous-agents tournent, aucun nouveau ne peut démarrer, et l’erreur dit à Claude de ne pas réessayer. Gemini CLI interdit les appels imbriqués pour éviter les boucles infinies et une consommation excessive de tokens.

Dans la plupart des outils, monter l’effort ne lance pas plus de sous-agents

Les cinq outils ont un paramètre qui fixe combien le modèle réfléchit avant de répondre : l’effort, ou niveau de raisonnement. Son lien avec les sous-agents tient en deux questions : le sous-agent hérite-t-il du niveau de l’agent principal, et peut-il choisir le sien ?

Source : la documentation des modèles et des sous-agents de chaque outil, 18 octobre 2026. Dans Cursor, le nom des niveaux change selon le modèle.

Les documentations de Claude Code, de Cursor, de Gemini CLI et de Copilot ne relient pas l’effort au nombre de sous-agents. La documentation de Claude Code décrit ainsi la différence observée à un niveau élevé : « tested more edge cases and verified more of its work before answering. It also made more choices on its own. » Elle ne parle pas du nombre de sous-agents. Dans Copilot, les sous-agents en parallèle ne dépendent pas de l’effort, mais d’un mode à part : avec la commande /fleet, c’est l’agent principal qui décide s’il peut découper le travail.

L’exception, c’est le niveau le plus élevé de Codex, ultra. La page des modèles écrit la même phrase pour la CLI, l’application et l’IDE : « Ultra mode goes beyond a single-agent run. It uses subagents to accelerate complex work. » Dans ChatGPT Work aussi, Ultra permet de déléguer spontanément à des sous-agents le travail qui s’y prête. Aux autres niveaux, selon la page des sous-agents, Codex en local lance un sous-agent quand vous le demandez, ou quand AGENTS.md ou un skill le dit.

Avec ultracode, Claude Code répartit le travail entre des dizaines de sous-agents

Dans le curseur /effort de Claude Code, à côté des niveaux d’effort, il y a aussi un interrupteur ultracode. La documentation ne le présente pas comme un niveau, mais comme une option à part : « a Claude Code setting rather than a model effort level ». Quand il est activé, Claude planifie, sans que vous le demandiez, un workflow dynamique pour chaque tâche conséquente : il écrit un script qui découpe le travail et pilote les sous-agents, et un environnement d’exécution lance ce script en arrière-plan ; pendant ce temps, votre session continue de répondre.

Il y a quatre façons de l’activer :

• Pour une seule tâche : écrivez le mot ultracode dans votre prompt ; le niveau d’effort de la session ne change pas. Le mot ne compte que dans les prompts que vous écrivez vous-même.
• Pour toute la session : /effort ultracode, ou l’interrupteur du curseur.
• Au lancement : claude --effort ultracode ; le niveau d’effort passe aussi à xhigh.
• Pour chaque session : "ultracode": true dans le fichier de configuration.

Le prix à payer est écrit noir sur blanc dans la documentation : chaque requête consomme plus de tokens et prend plus de temps ; avec un abonnement, vous atteignez plus tôt la limite de session ou la limite hebdomadaire. Quand ultracode est activé, la limite de 20 sous-agents ne s’applique pas ; le workflow a ses propres limites : par défaut 16 agents en même temps, et au plus 1 000 agents par exécution. Quand ultracode est désactivé, plus de 25 agents ou une estimation de 1,5 million de tokens déclenchent l’avertissement « Large workflow » ; quand il est activé, cet avertissement n’apparaît pas non plus.

Les workflows dynamiques sont arrivés fin mai 2026 et ont été annoncés comme « research preview » dans le récapitulatif hebdomadaire ; le 18 octobre 2026, la page des workflows ne portait aucune mention de statut. Ne les confondez pas avec deux choses au nom proche : ultrathink demande seulement une réflexion plus poussée pour ce tour et ne change pas le niveau d’effort ; /code-review ultra est une commande à part qui lance des agents de review dans le cloud, et Claude ne la lance jamais de lui-même.

Les sous-agents peuvent-ils se parler entre eux ?

Le résultat d’un sous-agent revient à celui qui l’a appelé ; c’est commun aux cinq outils. Ils se distinguent sur trois questions : les sous-agents peuvent-ils s’écrire entre eux, l’agent principal peut-il écrire après coup à un sous-agent en cours ou terminé, et existe-t-il une fonction d’équipe ?

Source : la documentation de chaque outil, 18 octobre 2026. Dans Copilot, pour écrire aux agents frères, la communication partagée entre frères doit être activée ; la documentation ne dit pas comment l’activer.

La fonction agent teams de Claude Code pousse cette idée le plus loin : une session dirige l’équipe, les membres sont des sessions distinctes, chacun travaille dans sa propre fenêtre de contexte, et ils s’écrivent par leur nom. Pas de message à tout le monde d’un coup : chaque destinataire reçoit son propre message. Le critère de la documentation : « Use subagents when you need quick, focused workers that report back. Use agent teams when teammates need to share findings, challenge each other, and coordinate on their own. » Agent teams est expérimental, désactivé par défaut, et consomme plus de tokens, car chaque membre est une instance distincte de Claude.

Pouvoir s’écrire ne veut pas dire qu’il faut s’appuyer sur ces échanges. Le schéma le plus solide reste de découper le travail en parties indépendantes et de réunir les résultats dans l’agent principal. La documentation de fleet de Copilot dit la même chose : la coordination passe par un état explicite, et non par une mémoire partagée implicite, et les sous-agents ne gardent pas d’état d’un appel à l’autre ; donnez à chacun un contexte complet.

Pour travailler en parallèle sans risque, chaque agent a son worktree et ses fichiers

Des sous-agents qui ne font que lire peuvent travailler côte à côte dans le même répertoire. Le problème commence quand plusieurs agents modifient des fichiers et font des commits : ils partagent le même répertoire, la même branche et le même index git. C’est un problème de git, quel que soit l’outil que vous utilisez. Notre dépôt a quatre règles pour cela.

Un worktree séparé. Dans Claude Code, si vous écrivez isolation: worktree dans la définition, le sous-agent reçoit un worktree temporaire, c’est-à-dire un répertoire de travail séparé du dépôt ; si le sous-agent se termine sans rien modifier, ce worktree est supprimé automatiquement. Selon la documentation, ce worktree part par défaut de la branche par défaut du dépôt, et non de la branche sur laquelle vous travaillez.

Des fichiers séparés. Pour les agents qui partagent le même répertoire, notre règle est la suivante : chacun ne commite que ses propres chemins (git commit --only <chemins>), car un git commit nu prend tout l’index, y compris le travail préparé par un autre agent. Quand vous découpez le travail, donnez à chaque agent son propre ensemble de fichiers.

Une consigne qui se suffit à elle-même. Dans Claude Code et Cursor, le sous-agent ne voit pas votre historique de conversation ; la consigne doit dire d’elle-même l’objectif, les fichiers qu’il peut toucher et ce qu’il doit rapporter. Les hooks du fichier de configuration, eux, s’appliquent d’office : dans Claude Code, le hook PreToolUse s’exécute aussi avant les appels d’outils du sous-agent.

Le nettoyage. Un worktree qui contient des modifications reste sur le disque. Le 27 août 2026, 41 worktrees s’étaient accumulés dans notre dépôt, dont 37 venus d’un seul tour de review. Comme ce désordre vient des workflows et non des personnes, c’est là aussi qu’a été placée la solution : chaque session s’ouvre avec un script qui supprime les branches des pull requests fusionnées et les worktrees dont le travail est terminé.

Un sous-agent n’est pas toujours utile

Un sous-agent préserve le contexte, mais il construit le sien à partir de zéro ; écrire la consigne et lire le résultat ont aussi un coût. La documentation de Claude Code recommande de rester dans la conversation principale dans ces cas :

• Il faut beaucoup d’allers-retours. Vous allez corriger le travail ensemble, étape par étape.
• Les étapes partagent le même contexte. La planification, l’implémentation et les tests s’appuient sur les mêmes informations.
• Le changement est petit et ciblé. Quelques lignes dans un fichier.
• La rapidité compte. Le sous-agent part de zéro, et rassembler le contexte prend du temps.

Un sous-agent est à sa place sur un travail qui répond seul à une seule question : « lance les tests et rapporte ceux qui échouent », « qui appelle ce module ? », « compare ces trois bibliothèques ». La review de diffox repose aussi sur cette idée : elle répartit la revue de code par IA entre des agents spécialisés, et chacun regarde le changement avec sa propre question. Nous expliquons comment ils sont choisis dans notre article sur l’architecture.