Claude Code : exécuter les sous-agents sur un autre modèle, les confier à Sonnet ou Haiku (réglages et mesures)

Vous voulez garder la session principale de Claude Code sur Opus 5, avec un effort élevé. Mais faire tourner sur ce même modèle des tâches comme la traduction ou la vérification d'un grand nombre de fichiers, c'est du gaspillage. D'où la question : peut-on faire tourner uniquement les sous-agents sur Sonnet ou Haiku ?

La réponse courte : oui. Le modèle d'un sous-agent est choisi indépendamment de la session principale, et vous pouvez le changer avec le modèle indiqué à l'appel, avec le champ model du fichier de définition ou avec une variable d'environnement. L'effort, lui aussi, peut prendre une valeur différente pour chaque sous-agent.

Dans cet article, je fais le point sur le fonctionnement décrit par la documentation officielle au 15 septembre 2026, puis je présente ce qui s'est passé quand j'ai réellement lancé des sous-agents sur d'autres modèles et vérifié les journaux de conversation. J'ai confié la même traduction à Opus 5, Sonnet 5 et Haiku 4.5, deux fois chacun, et comparé le temps, le coût et la qualité de la traduction.

1. Ce qui est possible : un modèle et un effort différents de la session principale

Un sous-agent est un exécutant doté de son propre contexte, que Claude Code lance pour lui confier une partie du travail. Il ne partage pas l'historique de conversation avec la session principale et, une fois terminé, ne lui renvoie que son résultat (la différence avec les équipes d'agents est traitée dans Subagents vs Agent Teams dans Claude Code).

Pour ces sous-agents, la documentation officielle indique que les deux éléments suivants se règlent séparément.

Autrement dit, une combinaison comme « session principale sur Opus 5 avec l'effort high, traducteur sur Sonnet 5 avec l'effort medium » se construit telle quelle, dans le cadre du fonctionnement officiel. Pour ce que signifie l'effort lui-même, voir Claude Code : le réglage effort (low–max + Ultracode).

Source : documentation officielle Claude Code, « Create custom subagents » (Supported frontmatter fields), « Model configuration » (ordre de priorité de l'effort)

2. L'ordre dans lequel le modèle est choisi

Comme le montre la figure en début d'article, le modèle d'un sous-agent est le premier qui s'applique dans cet ordre : le modèle indiqué à l'appel, puis le champ model du fichier de définition, puis la variable d'environnement CLAUDE_CODE_SUBAGENT_MODEL, puis le modèle de la session principale. Trois points méritent attention.

Premièrement, l'ordre dépend de la version. Avant la v2.1.251, la variable d'environnement était tout en haut et écrasait même le modèle indiqué à l'appel et le champ model du fichier de définition (y compris inherit). Si vous avez écrit model: sonnet dans une définition et que cela semble sans effet, vérifiez d'abord votre version et vos variables d'environnement.

Deuxièmement, il existe un réglage distinct pour tout aligner sur un seul modèle. La variable d'environnement seule ne s'impose pas aux sous-agents dont le fichier de définition contient un model. Pour les forcer tous, définissez CLAUDE_CODE_SUBAGENT_MODEL_FORCE à 1 en plus de CLAUDE_CODE_SUBAGENT_MODEL (v2.1.257 et versions ultérieures).

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

Une fois le forçage activé, le champ model des fichiers de définition est ignoré, y compris pour les Explore et Plan intégrés, et Claude ne peut plus indiquer de modèle lorsqu'il appelle un sous-agent. Il y a deux exceptions qui restent sur le modèle de la session principale : le fork, qui reprend toute la conversation, et une skill en model: inherit exécutée dans un sous-agent.

Troisièmement, la cible de sonnet et opus dépend du fournisseur. Même en écrivant le même sonnet, le modèle obtenu change comme suit.

Source : documentation officielle Claude Code, « Model configuration » (tableau au 15 septembre 2026). Pour figer une version précise, écrivez l'identifiant de modèle complet plutôt qu'un alias

Si les paramètres gérés de votre organisation restreignent les modèles utilisables (availableModels), le model des sous-agents et la variable d'environnement sont eux aussi concernés.

3. Comment le configurer (cinq façons)

1. L'écrire dans un fichier de définition (pour un rôle qui doit toujours utiliser le même modèle)

Le plus pratique est de créer un fichier de définition par rôle. Placé dans le dossier .claude/agents/ du projet, il se partage via git ; pour l'utiliser dans tous vos projets, placez-le dans ~/.claude/agents/.

---
name: translator
description: Traduit en anglais les articles écrits en japonais. À utiliser quand une traduction est demandée
model: sonnet
effort: medium
tools: Read, Write, Grep
---
Vous êtes traducteur d'articles techniques. Ne modifiez ni les balises ni les attributs HTML,
et rendez uniquement le texte visible en anglais naturel.

Quand plusieurs définitions portent le même nom, la priorité va dans cet ordre : paramètres gérés de l'organisation, --agents au lancement, projet, utilisateur, plugins. Depuis la v2.1.198, la commande /agents n'ouvre plus d'écran de création : demandez à Claude de créer le fichier, ou écrivez-le vous-même.

2. L'indiquer à l'appel (pour changer juste cette fois)

Même sans définition, Claude peut indiquer un modèle quand il lance un sous-agent. Si vous demandez dans la conversation quelque chose comme « confie cette vérification à un sous-agent Haiku », Claude lance le sous-agent en ajoutant ce modèle à l'appel. Cette indication l'emporte sur le fichier de définition. Pour vérifier qu'elle a bien été ajoutée, utilisez la méthode de la section 5.

3. Fixer une valeur par défaut avec une variable d'environnement (pour changer d'un coup tout ce qui n'a pas de modèle indiqué)

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "sonnet"
  }
}

Écrite dans env de settings.json, elle s'applique aux sous-agents dont le modèle n'a pas été décidé autrement. Selon la documentation officielle, les membres d'une équipe d'agents et les agents de workflow sont aussi concernés. En revanche, cela seul ne change pas le modèle des Explore et Plan intégrés (section 4).

4. Le passer avec --agents au lancement (pour cette session seulement)

claude --agents '{
  "translator": {
    "description": "Translates Japanese articles into English.",
    "prompt": "You are a technical translator. Keep all HTML tags.",
    "model": "sonnet",
    "effort": "medium"
  }
}'

Rien n'est enregistré dans un fichier : la définition n'existe que le temps de la session.

5. Le définir dans le Claude Agent SDK

from claude_agent_sdk import ClaudeAgentOptions, AgentDefinition

options = ClaudeAgentOptions(
    agents={
        "translator": AgentDefinition(
            description="Translates Japanese articles into English.",
            prompt="You are a technical translator. Keep all HTML tags.",
            tools=["Read", "Write"],
            model="sonnet",
            effort="medium",
        ),
    }
)

Dans l'AgentDefinition du SDK aussi, model accepte un alias, inherit ou un identifiant de modèle complet. Si vous ne l'indiquez pas, c'est l'ordre ci-dessus qui décide. Par ailleurs, la documentation officielle explique qu'Opus 5 délègue plus volontiers du travail aux sous-agents que les modèles précédents, et présente des réglages pour plafonner le nombre de sous-agents simultanés (20 par défaut) et le montant dépensé.

Source : documentation officielle Claude Code, « Create custom subagents » (emplacements et priorité, --agents, changement de /agents, variables d'environnement), « Model configuration » (champ d'application de CLAUDE_CODE_SUBAGENT_MODEL), « Subagents in the SDK » (AgentDefinition, réglages de plafond)

4. Sur quels modèles tournent les sous-agents intégrés

Même sans rien définir vous-même, Claude Code est livré avec plusieurs sous-agents. Voici leurs modèles.

Source : documentation officielle Claude Code, « Create custom subagents » (Built-in subagents, au 15 septembre 2026)

Depuis la v2.1.198, Explore ne tourne plus systématiquement sur Haiku. Il reprend le modèle de la session principale, avec Opus comme plafond sur la Claude API. Si la session principale est sur un modèle supérieur comme Fable, Explore tourne sur Opus ; si elle est sur Sonnet ou Haiku, il tourne sur ce modèle. Pour le remettre sur Haiku, la documentation officielle propose de créer un fichier de définition nommé Explore contenant model: haiku (votre propre définition l'emporte sur le sous-agent intégré du même nom).

Pour changer le modèle d'Explore et de Plan avec la variable d'environnement, il faut aussi définir CLAUDE_CODE_SUBAGENT_MODEL_FORCE, vu à la section 2.

5. Mesure n° 1 : a-t-il vraiment tourné sur ce modèle ?

J'ai vérifié que tout se passe comme documenté dans mon environnement (session principale sur Opus 5, effort high). J'ai confié au sous-agent intégré general-purpose la même petite tâche, « lire le README et le résumer en trois lignes », de trois façons : avec le modèle indiqué à sonnet, à haiku, et sans modèle indiqué.

Il y a deux façons de vérifier. Pendant l'exécution, la liste de /tasks affiche le modèle du sous-agent (c'est indiqué dans la documentation officielle). Une fois terminé, regardez le message.model de chaque réponse dans les fichiers agent-*.jsonl du dossier subagents/ de vos journaux de conversation locaux. L'emplacement des journaux et la façon de les lire sont détaillés dans Claude Code : mesurer la consommation par session.

Source : mes propres mesures (15 septembre 2026, application desktop sous Windows. Toutes les réponses de chaque sous-agent enregistraient le même modèle)

Chacun a tourné sur le modèle indiqué, et celui sans modèle indiqué a repris celui de la session principale. Le fichier agent-*.meta.json du même dossier ne conserve la valeur demandée, par exemple "model": "sonnet", que lorsqu'un modèle a été indiqué.

6. Mesure n° 2 : des dizaines de milliers de tokens rien que pour démarrer

Les mêmes journaux ont révélé autre chose. Un sous-agent lit des dizaines de milliers de tokens dès sa toute première réponse, avant même de commencer le travail. Son propre prompt système, les définitions des outils, CLAUDE.md et le reste sont chargés en premier.

Source : mes propres mesures (15 septembre 2026. Nombre de tokens de la première réponse de chaque sous-agent. Toutes les écritures allaient dans le cache de 5 minutes)

On peut tirer trois enseignements de ces chiffres.

Premièrement, entre sous-agents d'un même modèle, la partie commune du début est lue depuis le cache. Au deuxième lancement, environ 45 000 tokens ont été lus en cache pour Sonnet 5 (0,1 fois le prix de l'entrée). La documentation officielle indique elle aussi que les requêtes d'un même modèle qui commencent de la même façon partagent le cache. À l'inverse, le cache est distinct pour chaque modèle, et les sous-agents ne lisent pas non plus le cache de la session principale (parce que le contenu du début diffère).

Deuxièmement, même avec un abonnement, le cache des sous-agents expire au bout de 5 minutes. D'après la documentation officielle, dans le cadre d'un forfait, la conversation principale a droit à 1 heure, mais les sous-agents à 5 minutes. Si vous attendez plus de 5 minutes avant de lancer le sous-agent suivant, tout recommence par une écriture. Pour passer à 1 heure, définissez le paramètre subagentPromptCacheTtl ou la variable d'environnement CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL à 1h (v2.1.242 et versions ultérieures). Pour en décider sous-agent par sous-agent, écrivez dans le fichier de définition, sous experimental, la clé cacheTtl (v2.1.248 et versions ultérieures ; tant qu'un abonnement Claude puise dans les crédits d'utilisation supplémentaires (usage credits), la valeur 1h indiquée à cet endroit est ignorée). L'écriture dans le cache de 1 heure coûte 2 fois le prix de l'entrée (1,25 fois pour le cache de 5 minutes).

Troisièmement, pour un même texte, Haiku 4.5 affiche moins de tokens. Selon la page officielle des tarifs, les modèles Claude 4.7 et suivants utilisent un nouveau tokenizer qui compte environ 30 % de tokens de plus pour un même texte. Haiku 4.5 appartient à une génération antérieure à 4.7 et ne figure pas parmi les modèles qui utilisent le nouveau tokenizer. Si l'on compare directement les chiffres du tableau, Haiku paraît plus léger qu'il ne l'est réellement.

Si vous répartissez de petites tâches entre de nombreux sous-agents, ce « coût du simple démarrage » s'ajoute pour chacun. En confiant le travail à un modèle moins cher, ce coût baisse lui aussi, et pas seulement celui du travail.

Source : documentation officielle Claude Code, « How Claude Code uses prompt caching » (cache par modèle, sous-agents et cache, durée de vie du cache), Claude Platform Docs, « Pricing » (tokenizer, multiplicateurs du cache), documentation officielle Claude Code, « Create custom subagents » (omitClaudeMd)

7. Mesure n° 3 : la même traduction confiée deux fois à trois modèles

J'ai mis à l'épreuve l'idée de départ, « ne descendre de gamme que pour la traduction ». J'ai choisi une section de la version japonaise d'un article de ce site (6 265 caractères de HTML, avec un tableau, des cartes de chiffres et des extraits de code) et confié à chaque modèle la tâche de la traduire en anglais sans modifier la structure des balises, deux fois chacun avec les mêmes instructions, soit six exécutions au total. Opus 5 et Sonnet 5 ont utilisé l'effort high, repris de la session principale (Haiku 4.5 ne prend pas en charge l'effort).

Source : mes propres mesures (15 septembre 2026. Coût au prix catalogue, calculé en multipliant les nombres de tokens des journaux de conversation par les tarifs officiels. La sortie n'est pas comptée : voir la note ci-dessous)

La colonne du coût n'inclut pas la sortie, parce que les nombres de tokens de sortie des journaux n'étaient pas fiables. Dans un cas, une réponse qui avait écrit dans un fichier une traduction d'environ 8 800 caractères était enregistrée avec 18 tokens de sortie. Le prix de la sortie par million de tokens est de 25 $ pour Opus 5, 10 $ pour Sonnet 5 et 5 $ pour Haiku 4.5, et chaque traduction anglaise faisait environ 8 500 à 8 900 caractères.

J'ai vérifié moi-même la qualité des traductions, en les comparant phrase par phrase à l'original japonais.

• Aucun contresens dans les six exécutions. Les valeurs chiffrées, les tableaux et les liens internes étaient eux aussi correctement conservés. Cela dit, un texte riche en chiffres et en listes à puces fait partie des plus faciles à traduire
• Les différences portaient sur la lisibilité et l'homogénéité des termes. À la 1re exécution, Haiku 4.5 mélangeait « my » et « the author's » pour la première personne, et à la 2e, il produisait des tournures raides comme « G from 9th rises to 6th ». Sonnet 5 écrivait un anglais naturel, mais a orthographié « subagent » en « Sub-agent » la 1re fois et en « Subagent » la 2e : la graphie variait d'une exécution à l'autre. Opus 5 a gardé une terminologie cohérente les deux fois
• Le plus lent a été le moins cher, Haiku 4.5. Les deux exécutions de Sonnet 5 ont différé en durée de près du simple au double. Avec si peu d'exécutions, prenez le classement de vitesse comme une simple indication

8. L'effet sur le coût et sur les limites d'utilisation

Ce que rapporte le passage des sous-agents à un modèle moins cher se raisonne différemment selon que vous payez l'API à l'usage ou utilisez un abonnement comme Pro ou Max.

API facturée à l'usage : le rapport des prix s'applique directement

Source : Claude Platform Docs, « Pricing » (par million de tokens, au 15 septembre 2026. Le prix de lancement de Sonnet 5 est devenu son prix définitif)

Le prix unitaire de Sonnet 5 représente les deux cinquièmes de celui d'Opus 5, et celui de Haiku 4.5 un cinquième. Dans les mesures de la section 7, le coût de l'entrée et du cache était d'environ la moitié de celui d'Opus 5 pour Sonnet 5, et d'environ un cinquième pour Haiku 4.5. Si Haiku 4.5 reste proche du rapport des prix, Sonnet 5 ressort plus cher que ce rapport (deux cinquièmes). C'est que le nombre de réponses et la quantité lue à chaque réponse différaient d'un modèle à l'autre (Sonnet 5 : 4 et 6 réponses ; Opus 5 : 4 les deux fois. Pour Haiku 4.5, la différence de tokenizer s'y mêle aussi).

Abonnement : certaines limites ne reviennent pas en changeant de modèle

Sur Pro et Max, la limite de session et la limite hebdomadaire sont communes à tous les modèles. Une fois qu'elles sont épuisées, changer de modèle avec /model ne vous permet pas de continuer. À côté, il existe des limites par famille de modèles, comme la « limite Opus » et la « limite Sonnet », et c'est seulement quand vous atteignez l'une d'elles que vous pouvez continuer en passant à un modèle d'une autre famille.

🟡 Dans quelle mesure les limites du forfait durent plus longtemps quand les sous-agents tournent sur Sonnet ou Haiku n'a pas été publié. Le rapport des prix de l'API donne un ordre d'idée, mais rien n'indique que les limites se consomment dans cette même proportion. Pour voir quels sous-agents consomment le plus, consultez la répartition du forfait dans /usage (parts par skill, sous-agent, plugin et serveur MCP).

Source : documentation officielle Claude Code, « Error reference » (You've hit your session limit : limites communes à tous les modèles et limites par famille de modèles), « Manage costs effectively » (répartition du forfait dans /usage)

9. Quelles tâches confier à un modèle moins cher

À titre indicatif, la documentation officielle indique que Sonnet traite très bien la plupart des tâches de code pour moins cher qu'Opus, qu'il vaut mieux réserver Opus aux décisions d'architecture complexes et au raisonnement en plusieurs étapes, et que pour les tâches simples de sous-agent il faut indiquer model: haiku dans le fichier de définition. Elle recommande aussi Sonnet pour les membres d'une équipe d'agents.

Sur cette base, voici trois éléments pour décider, tirés des mesures de la section 7 et de mon usage sur ce site.

En cas de doute, le plus sûr est de confier une seule de vos tâches habituelles au modèle moins cher et de comparer le résultat avec celui de votre modèle actuel. Il suffit de modifier une ligne, le model du fichier de définition, pour essayer, et de revenir en arrière aussitôt si cela ne convient pas. Si ce que vous voulez répartir, c'est le modèle de la session principale plutôt que celui d'un sous-agent, en utilisant Opus uniquement pour la planification et Sonnet pour l'implémentation, c'est ce que fait opusplan : voir Qu'est-ce qu'opusplan dans Claude Code ?

FAQ

Q1. Si je change le /model de la session principale en cours de conversation, les sous-agents changent-ils aussi ?
Les sous-agents dont le modèle est décidé par l'indication à l'appel, par le champ model du fichier de définition (autre que inherit) ou par la variable d'environnement ne changent pas. Ceux qui n'ont rien de tout cela, et ceux dont le fichier de définition indique inherit, suivent le modèle de la session principale. Notez que changer le modèle de la session principale oblige à reconstruire le cache de la session principale.

Q2. Puis-je baisser uniquement l'effort en gardant le modèle ?
Oui. Écrivez par exemple effort: medium dans le fichier de définition : cet effort ne s'applique que pendant l'exécution de ce sous-agent. Toutefois, si la variable d'environnement CLAUDE_CODE_EFFORT_LEVEL est définie, c'est elle qui l'emporte.

Q3. Sur Amazon Bedrock, quel modèle obtient-on avec model: sonnet ?
Selon la documentation officielle au 15 septembre 2026, Sonnet 4.5. Sur l'Anthropic API, c'est Sonnet 5 : un même fichier de définition donne donc un résultat différent selon le fournisseur. Pour figer la version, écrivez l'identifiant de modèle complet.

Q4. Vaut-il mieux passer le cache des sous-agents à 1 heure ?
Cela dépend de votre usage. Si vous lancez souvent le même type de sous-agent à plus de 5 minutes d'intervalle, cela réduit les écritures répétées. En revanche, l'écriture dans le cache de 1 heure coûte 2 fois le prix de l'entrée (1,25 fois pour 5 minutes) : si vous ne faites tourner des sous-agents que par courtes rafales, le cache de 5 minutes revient moins cher. Les réglages pour un cache de 1 heure et leurs conditions sont présentés à la section 6.

Q5. J'ai indiqué un modèle, mais j'ai l'impression qu'il n'est pas pris en compte.
Vérifiez dans cet ordre : (1) que CLAUDE_CODE_SUBAGENT_MODEL_FORCE n'est pas activé (le modèle du fichier de définition est alors ignoré), (2) que vous n'êtes pas sur une version antérieure à la v2.1.251 avec la variable d'environnement définie, (3) que les paramètres gérés de votre organisation autorisent ce modèle. Pour savoir sur quel modèle il a réellement tourné, utilisez /tasks pendant l'exécution, ou le message.model des journaux de conversation une fois terminé.

Sources

• Claude Code Docs — Create custom subagents (champs du fichier de définition, ordre de choix du modèle et différences selon la version, CLAUDE_CODE_SUBAGENT_MODEL_FORCE, sous-agents intégrés, emplacements et priorité, --agents, omitClaudeMd, vérification avec /tasks)
• Claude Code Docs — Model configuration (cible des alias, champ d'application de CLAUDE_CODE_SUBAGENT_MODEL, priorité de l'effort, availableModels)
• Claude Code Docs — How Claude Code uses prompt caching (cache par modèle, durée de vie pour les sous-agents, subagentPromptCacheTtl et réglage via la variable d'environnement et le fichier de définition)
• Claude Code Docs — Manage costs effectively (repères pour choisir un modèle, recommandation de Sonnet pour les membres d'une équipe d'agents, répartition dans /usage)
• Claude Code Docs — Error reference (limites communes à tous les modèles et limites par famille de modèles)
• Claude Code Docs — Subagents in the SDK (model et effort dans AgentDefinition, Opus 5 et réglages de plafond)
• Claude Code Docs — Orchestrate teams of Claude Code sessions (comment est choisi le modèle des membres d'une équipe d'agents)
• Claude Platform Docs — Pricing (tarifs par modèle, multiplicateurs du cache, tokenizer)

Articles liés

• Subagents vs Agent Teams dans Claude Code : ce qu'est un sous-agent
• Claude Code : le réglage effort (low–max + Ultracode) : ce que signifie l'effort
• Claude Code : mesurer la consommation par session : comment lire les journaux de conversation
• Claude Code : qu'est-ce qui dévore vraiment votre contexte ? : pourquoi CLAUDE.md est lu à chaque fois
• Qu'est-ce qu'opusplan dans Claude Code ? : mettre la session principale sur Opus uniquement pendant le mode planification
• 10 astuces Claude Code pour économiser les tokens : d'autres postes à réduire