Sous-agents Claude Code : économies et coût en tokens

Un sous-agent est un autre travailleur Claude lancé par Claude Code dans votre session. Il possède sa fenêtre de contexte, son prompt système et ses outils. Il lit, cherche et exécute des commandes dans cette fenêtre, puis ne renvoie que sa réponse finale. Claude délègue aussi spontanément, par exemple à l'agent Explore intégré lorsqu'il doit chercher dans le code.

Les sous-agents économisent donc de l'espace dans le contexte, pas forcément des tokens. La conversation principale reste courte parce que les lectures n'y arrivent jamais. Le total traité par tous les agents peut cependant augmenter : chacun paie sa préparation et ses recherches ; plusieurs agents simultanés multiplient ces dépenses.

Ce que paie un sous-agent

Il démarre sans l'historique de votre conversation, sans les skills déjà invoqués et sans les fichiers déjà lus par Claude. Il reçoit une mission rédigée par l'agent principal. Chacune de ses requêtes contient :

• →Son propre prompt système, plus court que celui de la session principale, et les outils qu'il peut appeler, outils MCP compris.
• →Vos fichiers CLAUDE.md et un instantané de l'état Git. Les agents intégrés Explore et Plan sautent ces deux éléments pour démarrer plus léger.
• →Le message de mission et le texte complet des skills préchargés par sa définition.

Il suit ensuite sa propre boucle d'agent. Chaque résultat d'outil, fichier lu et sortie de commande entre dans son contexte. L'étape suivante renvoie ce contexte devenu plus grand. Plus la recherche dure, plus cette boucle pèse face au coût de départ.

Le cache aide moins que dans le fil principal. Le préfixe du sous-agent est distinct, donc sa première requête ne peut relire le cache de votre conversation. Le cache qu'il construit dure cinq minutes par défaut, même si votre conversation principale bénéficie d'une heure sur abonnement. Le réglage subagentPromptCacheTtl peut le porter à une heure, avec un prix d'écriture plus élevé.

Enfin, son dernier message et une courte annexe indiquant durée et tokens reviennent au parent. Cette réponse entre dans votre conversation et sera renvoyée à chaque tour suivant. Un verdict de deux lignes y coûte donc moins qu'un rapport complet.

Ce qu'il épargne

L'économie correspond à tout ce que le sous-agent a lu ou exécuté sans l'ajouter à votre fil : douze fichiers ouverts pour trouver une fonction, des milliers de lignes de tests derrière trois erreurs. Dans la conversation principale, ce contenu resterait et repartirait à chaque tour jusqu'à /clear ou /compact. Le cache réduirait son tarif de relecture, mais il pèserait toujours sur les limites et remplirait la fenêtre où le modèle raisonne.

La documentation de Claude Code donne un exemple : un sous-agent de recherche lit environ 6 100 tokens de fichiers et ne renvoie que 420 tokens au fil principal. Ce dernier ne grossit que du résultat ; la lecture a bien été payée dans la fenêtre du sous-agent.

Un sous-agent gagne donc quand il écarte beaucoup de matière d'une session qui a encore de nombreux tours devant elle. Il perd quand la tâche est petite ou exige de relire ce que la conversation sait déjà.

Quand les sous-agents sont utiles

• →Explorer un code inconnu, dont la plupart des fichiers consultés ne seront finalement pas pertinents.
• →Réduire une opération bavarde à un verdict : erreurs d'un test, lignes utiles d'un journal ou réponse extraite d'une documentation.
• →Travailler dans une longue session : plus elle comporte de tours à venir, plus chaque token tenu hors du fil principal a de valeur.
• →Mener des recherches indépendantes en parallèle. Elles prennent le temps de la plus lente au lieu de la somme, ce qui économise du temps, pas des tokens : chaque agent paie son propre départ.
• →Confier la recherche, la synthèse et les vérifications à un modèle moins cher lorsqu'il sait les faire.

Quand ils gaspillent des tokens

• →Une petite modification ciblée. Si vous connaissez déjà le fichier, la préparation coûte plus que l'exploration évitée, et le sous-agent doit encore acquérir du contexte.
• →Une tâche qui dépend de l'historique déjà connu. Un nouvel agent relit les fichiers déjà lus par Claude. Les échanges fréquents et les phases qui partagent du contexte, comme planifier, implémenter et tester, conviennent mieux au fil principal.
• →Des recherches parallèles qui se chevauchent. Trois agents ayant besoin du même module le lisent chacun, puis leurs trois résultats entrent dans votre conversation.
• →De nombreux agents simultanés sur abonnement. Tous puisent dans les mêmes limites que le fil principal ; Claude Code précise que leur exécution simultanée multiplie les tokens.

La délégation peut être imbriquée. En septembre 2026, un sous-agent peut en lancer un autre, jusqu'à trois niveaux sous votre conversation par défaut ; vingt peuvent travailler simultanément. CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 bloque l'imbrication et CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS change la limite de concurrence.

Deux autres outils répondent à une partie du besoin. /btw traite une question annexe à partir de ce que contient déjà votre fil, sans outil, sans ajouter sa réponse à l'historique. /subtask crée un fork : un sous-agent qui hérite de la conversation et lit son cache. La documentation le dit moins coûteux qu'un agent neuf si la tâche a besoin du même contexte, même si le fork démarre aussi gros que la conversation.

Choisir un modèle moins cher

Un sous-agent personnalisé est un fichier Markdown dans .claude/agents/ pour un projet ou ~/.claude/agents/ pour tous, avec un en-tête YAML avant son prompt système. Le champ model accepte haiku, sonnet, opus, fable, un identifiant complet comme claude-opus-5-5 ou inherit. Pour rechercher, résumer ou lancer des contrôles, définissez model: haiku.

Claude Code choisit le modèle dans cet ordre : celui passé par Claude pour un appel, le champ model de la définition, la variable CLAUDE_CODE_SUBAGENT_MODEL, puis le modèle du fil principal. Ce dernier recours a un coût : passer à Opus avec /model fait aussi passer à Opus les sous-agents qui héritent du modèle.

L'agent Explore intégré n'utilise plus Haiku par défaut. Depuis Claude Code v2.1.198, il hérite du modèle de la session, plafonné à Opus sur l'API Claude. Un sous-agent personnalisé nommé Explore et doté de model: haiku remplace l'agent intégré ; ajoutez omitClaudeMd: true si vous ne voulez pas charger vos fichiers CLAUDE.md. CLAUDE_CODE_SUBAGENT_MODEL seul ne déplace ni Explore ni Plan ; CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 l'applique aussi à eux depuis v2.1.257.

En septembre 2026, les prix publics de l'API Anthropic sont de 1 $ par million de tokens d'entrée et 5 $ de sortie pour Haiku 4.5, contre 2 $ et 10 $ pour Sonnet 5, puis 4 $ et 20 $ pour Opus 5.5. Pour les abonnés, le centre d'aide indique qu'Opus consomme plusieurs fois plus par tour que Sonnet, et Sonnet plus que Haiku.

Une limite demeure : la fenêtre d'un sous-agent dépend de son modèle. Haiku 4.5 dispose de 200 000 tokens, Sonnet 5 et Opus 5.5 d'un million. Deux champs bornent aussi la dépense : maxTurns limite ses tours, et effort: low réduit l'effort de raisonnement sur Sonnet ou Opus sans modifier celui de la session principale.

$/tasks

Mesurer l'usage des sous-agents

Pour les totaux, utilisez les outils qui additionnent toutes les requêtes :

• →Sur Pro, Max, Team ou Enterprise, /usage attribue une part de l'usage récent aux sous-agents, skills, plugins et serveurs MCP. d et w basculent entre 24 heures et sept jours. Le calcul lit l'historique local, pas les autres machines ni claude.ai ; Prompt cache (main) ne couvre que le fil principal.
• →Dans un script, claude -p --output-format json renvoie total_cost_usd et une ventilation par modèle. D'après la documentation Agent SDK, usage compte seulement la boucle principale, alors que total_cost_usd et modelUsage comprennent les sous-agents.
• →Pour une équipe, les compteurs de tokens et de coût OpenTelemetry étiquettent chaque requête avec query_source, égal à subagent pour une délégation, ainsi qu'avec agent.name.
• →Le journal de chaque sous-agent, avec ses lectures et commandes, reste dans ~/.claude/projects/{project}/{sessionId}/subagents/ pendant 30 jours par défaut.

$/usage

Avant de déléguer

La recherche la moins chère, déléguée ou non, est celle qui n'a pas lieu. Nommez le fichier si vous le connaissez et posez une question étroite. Gardez courte la description de chaque sous-agent personnalisé : elle occupe le contexte principal, alors que son prompt système n'est chargé que lorsqu'il travaille.

Pour plafonner la part consacrée à l'exploration, capsul pilote le Claude Code auquel vous êtes déjà connecté, envoie ce que demande la tâche et s'arrête au budget choisi en indiquant ce qui a été écarté.

$capsul ask 'why does the session expire early' --budget 3000