Aller au contenu principal

Régler l'effort : 5 niveaux, valeurs par défaut par modèle et le piège du cache

Intermédiaire

Le 22 juillet 2026, Anthropic a intégré effort à la configuration du modèle de Claude Managed Agents, bouclant la boucle sur un contrôle que la Messages API a discrètement fait passer à cinq niveaux. Si vous recopiez encore effort="high" au premier niveau de messages.create depuis un article de début 2026, votre requête semble valide, mais Claude peut ne pas honorer le champ que vous croyez : le paramètre vit désormais dans output_config, et l'API n'applique que les niveaux documentés sur la fiche du modèle.

Voici le guide pratique de réglage : où va réellement effort dans une requête, ce que font vraiment les cinq niveaux (ils changent le nombre d'appels d'outils, pas seulement la profondeur de réflexion), les valeurs par défaut par modèle qui surprennent, et le piège qui fait discrètement exploser la dépense — changer l'effort en cours de conversation invalide le cache de prompt.

What you'll learn
  • Placer correctement le champ effort — dans output_config sur la Messages API, dans l'objet model sur Managed Agents, via /effort ou CLAUDE_CODE_EFFORT_LEVEL dans Claude Code
  • Choisir un niveau de départ par modèle — high est le défaut de l'API sur la plupart des modèles mais PAS sur Opus 5.5 et Haiku 5.5, qui utilisent medium, et l'effort de départ recommandé varie encore (Sonnet 5.5 medium pour le code agentique, Sonnet 4.6 medium, Opus 4.7/4.8 xhigh, Fable 5.1 high)
  • Comprendre que l'effort affecte TOUS les tokens — texte, appels d'outils et (quand elle est active) réflexion — donc baisser l'effort réduit le nombre d'appels d'outils, pas seulement la verbosité
  • Éviter le piège du cache — faire varier l'effort dans une même conversation invalide le prompt caching et peut doubler la facture sans bruit
  • Connaître la surface d'effort de Claude Code — /effort, ultrathink (un seul tour), ultracode (xhigh + permission multiagent permanente), surcharge par la variable d'environnement CLAUDE_CODE_EFFORT_LEVEL

Les cinq niveaux (et la place d'« ultracode »)​

L'échelle d'effort au 22 juillet 2026 compte cinq valeurs acceptées par l'API :

NiveauCe qu'il faitQuand l'utiliser
lowLe plus efficace. Économie de tokens notable avec une certaine baisse de capacité. Moins d'appels d'outils, confirmations laconiques, aucun préambule.Classification simple, charges à gros volume, chat, UX sensible à la latence, sous-agents sur des tâches circonscrites
mediumÉquilibré. Économie de tokens modérée par rapport à high.Tâches agentiques demandant un équilibre entre vitesse, coût et qualité ; palier économique en dessous de high
highHaute capacité. Équivaut à omettre le paramètre — sur tous les modèles sauf Opus 5.5 et Haiku 5.5, dont le défaut est medium.Raisonnement complexe, code difficile, tâches agentiques où la qualité compte plus que la vitesse
xhighCapacité étendue pour le travail au long cours. Attendez-vous à une consommation de tokens nettement supérieure à high.Tâches agentiques et de code longues (30+ min), budgets de tokens en millions, refactorings profonds sur plusieurs fichiers
maxCapacité maximale absolue, sans contrainte sur la dépense de tokens.Uniquement les vrais problèmes de pointe. Peut sur-réfléchir sur les tâches à sortie structurée.

Ni max ni xhigh ne sont universels — vérifiez le niveau par rapport au modèle avant de livrer. xhigh est pris en charge sur Fable 5.1, Mythos 5.1, Fable 5, Mythos 5, Opus 5.5, Opus 5, Opus 4.8, Opus 4.7, Sonnet 5.5, Sonnet 5 et Haiku 5.5. max couvre tous ceux-là plus Mythos Preview, Opus 4.6 et Sonnet 4.6. Opus 4.5 prend en charge l'effort mais aucun des deux niveaux supérieurs. Selon les mots d'Anthropic : "Not every model that supports max supports xhigh."

Pro tip
  • Régler l'effort sur la valeur par défaut du modèle produit exactement le même comportement qu'omettre le paramètre — c'est 'high' sur la plupart des modèles, mais 'medium' sur Opus 5.5 et Haiku 5.5. Ne le définissez pas « pour être explicite » dans une conversation en cache, car écrire le champ sur certaines requêtes et pas sur d'autres invalide le cache.
  • 'ultracode' n'est pas un sixième niveau. C'est xhigh + une permission permanente pour Claude Code de lancer des workflows multiagents, accordée par des messages système en cours de conversation. L'API accepte cinq valeurs.

La structure du champ que la plupart des articles ont faux​

Les articles de début 2026 sur le paramètre effort montrent un champ au premier niveau :

# WRONG on current models — silently ignored or 400
client.messages.create(
    model="claude-opus-4-8",
    effort="medium",
    ...
)

L'API actuelle place effort dans un objet output_config, passé comme frère de messages/model :

Bon emplacement d'effort — Messages API

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
  model="claude-opus-4-8",
  max_tokens=4096,
  output_config={"effort": "medium"},
  messages=[{
      "role": "user",
      "content": "Analyse the trade-offs between microservices and monoliths."
  }],
)

print(response.content[0].text)

Sur Claude Managed Agents (le changement du 22 juillet 2026), effort se place dans l'objet model de l'agent à sa création. La session ne le définit pas — c'est la version de l'agent qui le fait.

Bon emplacement d'effort — Managed Agents (POST /v1/agents)

# Effort travels with the versioned agent config,
# not the per-run session. Every session pinned to
# this agent version runs at xhigh.

POST https://api.anthropic.com/v1/agents
{
"name": "code-reviewer",
"model": {
  "id": "claude-opus-4-8",
  "effort": "xhigh"
},
"system_prompt": "You review pull requests for security issues.",
"tools": [...],
"mcp_servers": [...]
}

L'effort n'est pas un contrôle de la réflexion​

C'est la seconde grande idée reçue. L'effort fonctionne que la réflexion soit activée ou non, et il modifie les tokens que Claude dépense sur des parties de la réponse qui ne sont pas de la réflexion :

  • Appels d'outils. Effort plus bas → moins d'appels d'outils. Claude regroupe les opérations en un seul appel, saute l'exploration facultative et passe à l'action sans préambule.
  • Longueur du texte. Effort plus bas → sortie plus concise. Confirmations laconiques après les appels d'outils plutôt que résumés détaillés. Moins de commentaires dans le code.
  • Profondeur de réflexion (quand la réflexion est active). Effort plus bas → saute entièrement la réflexion sur les prompts faciles ; réfléchit encore sur les vraiment difficiles, mais moins.

Ce dernier point compte : à effort low, Claude réfléchira quand même sur un problème de démonstration, parce que la tâche l'exige. L'effort est un signal comportemental, pas un budget de tokens strict. N'attendez pas de plafond ferme.

Le paramètre thinking et le paramètre effort répondent à des questions différentes. thinking décide si Claude produit des blocs de réflexion. effort décide de la quantité de travail investie dans toute la réponse — y compris la fréquence et la profondeur de la réflexion quand l'adaptive thinking est actif. Passer effort="adaptive" est une erreur fréquente ; adaptive est un mode de réflexion, pas un niveau d'effort.

Pro tip

Sur Opus 4.5 — le seul modèle à réflexion étendue uniquement qui prend en charge l'effort — vous réglez l'effort et budget_tokens ensemble. Choisissez le niveau d'effort adapté à votre tâche, puis dimensionnez le budget de tokens de réflexion selon la profondeur de raisonnement voulue. Tous les autres modèles compatibles avec l'effort utilisent l'adaptive thinking et n'acceptent pas budget_tokens.

Points de départ par modèle qui surprennent les équipes​

Le défaut de l'API est high sur la plupart des modèles compatibles avec l'effort — mais pas tous. Opus 5.5 et Haiku 5.5 utilisent medium par défaut. En plus, l'effort de départ recommandé par Anthropic varie selon le modèle, et c'est dans cet écart que les équipes sur- ou sous-dépensent.

Guided walkthrough1 of 9
  1. Opus 5.5 est le seul Opus dont le défaut est medium : une requête qui omet l'effort tourne donc un niveau PLUS BAS que le même code sur Opus 5. Si la qualité a baissé après migration, vérifiez cela en premier. L'adaptive thinking est toujours actif et ne peut pas être désactivé (thinking: {type: 'disabled'} renvoie 400 à tous les niveaux) : l'effort est donc votre seul contrôle sur la quantité de raisonnement et le coût de la requête. Refaites un balayage d'effort plutôt que de reporter les réglages — à niveau égal, il réfléchit davantage par tour que Opus 5.

Le piège du cache — celui qui double la facture sans bruit​

Le prompt caching offre des lectures de cache à une fraction du prix d'entrée standard (un dixième sur la plupart des modèles, moins sur les plus récents — voir Pricing). Changer le output_config.effort de premier niveau entre deux requêtes de la même conversation invalide le cache, exactement comme un changement de modèle : l'effort de premier niveau façonne le prompt rendu, donc une nouvelle valeur signifie qu'aucun préfixe en cache ne correspond. Sur un long contexte, c'est une relecture à plein tarif de tout votre historique, à chaque tour suivant.

L'échappatoire : l'effort par message (bêta)​

Les modèles les plus récents permettent de changer l'effort sans perdre le cache. Ajoutez un message role: "system" avec un content vide portant le nouveau niveau dans output_config.effort, et tout ce qui précède reste identique à l'octet près — le préfixe en cache correspond donc toujours.

Changer l'effort en cours de conversation sans défaut de cache

# Beta header required:
#   anthropic-beta: mid-conversation-output-config-2026-07-01

{
"model": "claude-fable-5-1",
"max_tokens": 4096,
"output_config": {"effort": "high"},
"messages": [
  {"role": "user", "content": "Plan a migration from SQLite to PostgreSQL."},
  {"role": "assistant", "content": "1. Export... 2. Create schema... 3. Import."},
  {"role": "system", "content": [], "output_config": {"effort": "low"}},
  {"role": "user", "content": "Summarize the plan in one sentence."}
]
}

Disponibilité au 19 octobre 2026 : sur la Claude API et Google Cloud, cela fonctionne sur Fable 5.1, Mythos 5.1, Opus 5.5, Opus 5, Sonnet 5.5 et Haiku 5.5 ; sur Amazon Bedrock, uniquement Fable 5.1, Mythos 5.1 et Opus 5.5. Il faut l'en-tête bêta mid-conversation-output-config-2026-07-01 — sans lui, un output_config par message renvoie 400 messages.N.output_config: Extra inputs are not permitted. Avec l'en-tête mais un modèle non pris en charge (dont Fable 5), vous obtenez 400 output_config.effort requires a model that supports per-turn effort; this model does not.

Deux modèles refusent de changer l'effort par tour une fois la réflexion figée : Sonnet 5.5 avec thinking: {"type": "between_tools"} et Haiku 5.5 avec thinking: {"type": "disabled"} renvoient 400 si un niveau par message diffère de celui en vigueur. Utilisez l'adaptive thinking pour faire varier l'effort dans ces cas.

Pour tout le reste, l'ancienne règle s'applique toujours — choisissez un niveau et tenez-vous-y :

Pro tip
  • Sur les modèles sans effort par message, faites varier l'effort ENTRE charges de travail, pas À L'INTÉRIEUR d'une conversation en cache. Choisissez le niveau au début de la conversation et gardez-le constant jusqu'à /clear.
  • Préférez l'effort par message à un changement de premier niveau même quand les deux fonctionnent : sur Fable 5.1, un basculement de premier niveau oriente aussi moins fiablement le modèle, car ses réponses précédentes ont été écrites au niveau précédent et il tend à rester cohérent avec elles.
  • Dans Claude Code, /effort en cours de session équivaut à changer de modèle — attendez-vous à un gros défaut de cache au tour suivant.
  • Si vous devez monter en profondeur pour un seul tour, utilisez 'ultrathink' dans Claude Code (un coup de pouce de raisonnement plus profond pour un tour) plutôt que /effort xhigh — cela évite de modifier la configuration de la session.
  • Si vous devez monter pour le reste de la session, faites-le tôt. Un changement au tour 3 coûte peu ; un changement au tour 30 relit 30 tours de contexte à plein tarif.

Le corollaire : définir effort="high" explicitement sur certaines requêtes en cache et l'omettre sur d'autres invalide le cache de la même façon — car les deux sont équivalents en comportement mais différents dans le texte. Choisissez une convention (toujours définir, ou toujours omettre) et tenez-vous-y.

Claude Code — la surface en CLI​

Claude Code expose l'effort sous forme de commande interactive, de drapeau de lancement et de variable d'environnement (la priorité la plus haute l'emporte, dans l'ordre inverse) :

# In-session (interactive slider, or direct)
/effort
/effort xhigh
/effort auto           # reset to model default

# At launch
claude --effort low

# Environment (overrides everything else)
CLAUDE_CODE_EFFORT_LEVEL=high claude

Deux commandes connexes méritent d'être connues, car ce ne sont pas des niveaux d'effort mais elles se comportent de façon voisine :

  • ultrathink — un coup de pouce de raisonnement plus profond pour un seul tour qui ne change pas l'effort de la session. Utilisez-le quand vous voulez que le prochain tour réfléchisse davantage sans invalider le cache de tous les tours suivants.
  • ultracode — règle xhigh pour toute la session et accorde à Claude Code la permission permanente de lancer des workflows multiagents (via des messages système en cours de conversation). L'API n'a pas de valeur ultracode — c'est une commodité de la CLI qui compose xhigh avec une permission d'orchestration.

Règles de persistance à retenir : low, medium, high et xhigh persistent d'une session Claude Code à l'autre une fois définis. max ne s'applique qu'à la session en cours — il faut le réappliquer la fois suivante.

Un pas-à-pas de réglage — un prompt, trois efforts​

Pour calibrer l'intuition, exécutez le même prompt à trois niveaux et comparez la forme de la sortie :

Prompt de calibrage (à lancer à low, high, xhigh)

Task: Review this pull request for security issues.

<pr_diff>
[paste a real diff — 300+ lines, multi-file, at least one auth-touching change]
</pr_diff>

Report: severity-tagged findings + a one-line fix per finding.
Do not restate what the diff does.

Attendez-vous à peu près à ceci :

  • low — repère les problèmes évidents de haute gravité (concaténation de chaînes SQL, entrée utilisateur non vérifiée dans un en-tête). Manque les bugs de logique subtils. 1 à 2 appels d'outils si des outils sont disponibles. Sortie courte. Rapide.
  • high — analyse complète. Repère la plupart des vulnérabilités, y compris subtiles. Plusieurs appels d'outils ciblés pour lire les fichiers liés. Constats structurés. C'est là que la plupart des équipes s'arrêtent.
  • xhigh — exhaustif. Envisage des vecteurs d'attaque inédits et la défense en profondeur. Lit des fichiers adjacents que low/high n'ont pas touchés. Beaucoup plus d'appels d'outils. Consommation de tokens nettement supérieure.

Si vos évaluations montrent que high et xhigh produisent les mêmes constats sur votre base de code, livrez à high. La valeur de xhigh apparaît précisément quand la tâche profite d'appels d'outils répétés et d'une exploration détaillée — exactement quand Anthropic le recommande.

Sonnet 5 a décalé la calibration — ne portez pas les niveaux à l'aveugle​

Si vous faisiez tourner Sonnet 4.6 à high et avez migré vers Sonnet 5, conserver le même niveau fait dépenser à Sonnet 5 quelque chose de proche de ce que Sonnet 4.6 dépensait à max — l'échelle d'effort de Sonnet 5 est décalée. Le conseil d'Anthropic lui-même : Sonnet 5 medium ≈ Sonnet 4.6 high. C'est un écart de coût par requête à vérifier si vous avez rejoué du trafic sans ajuster l'effort. Voir le guide de terrain de Sonnet 5 pour toute l'histoire de la migration.

Ancrez-le​

Appuyez sur Entrée ou Espace pour retourner la carte. Utilisez les flèches gauche et droite pour naviguer entre les cartes.Terme affiché.
1 / 9

Testez-vous

0/7
  1. Laquelle de ces valeurs n'est PAS une valeur d'effort valide sur la Messages API ?
  2. Vous menez une conversation en cache de 20 tours et basculez l'effort de PREMIER NIVEAU de high à xhigh au tour 21. Que se passe-t-il ?
  3. Vous êtes sur Opus 5.5 et omettez entièrement le paramètre effort. Quel niveau s'exécute ?
  4. Vous êtes dans Claude Code et voulez que seul le tour SUIVANT raisonne plus fort sans toucher au réglage d'effort de la session. Meilleure option ?
  5. Sur Opus 4.8 avec effort='xhigh', vos réponses se tronquent sans cesse avec stop_reason='max_tokens' après une longue réflexion. Correctif le plus probable ?
  6. Où va l'effort lors de la création d'un agent Claude Managed Agents (la mise à jour de juillet 2026) ?
  7. Quel changement fait que Sonnet 5 'medium' se comporte le plus comme Sonnet 4.6 à 'high' ?

Sources et lectures complémentaires​

Suite​