Le paramètre effort : cinq niveaux pour arbitrer coût et qualité

La leçon précédente s’est conclue sur une promesse : puisque vous ne pilotez plus la réflexion avec un budget de tokens, vous la pilotez avec effort. Ce paramètre est devenu le levier principal pour arbitrer entre qualité, latence et coût, et il ne demande aucun en-tête bêta : vous pouvez l’utiliser en production dès aujourd’hui.

Où il se place dans la requête

effort se trouve dans output_config, et non à la racine de la requête :

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    messages=[
        {"role": "user", "content": "Compare les architectures microservices et monolithiques."}
    ],
    output_config={"effort": "high"},
)

Sur Opus 5.5, dont le défaut est medium, cette requête travaille un cran plus haut que si l’on omettait le paramètre.

Les cinq niveaux

Le paramètre accepte cinq valeurs, de la plus dépensière à la plus économe :

Deux précisions évitent des débats inutiles en équipe. D’abord, la valeur par défaut n’est plus la même partout : medium sur Claude Opus 5.5 et Claude Haiku 5.5, high sur les autres modèles. Une requête sans effort envoyée à Opus 5.5 tourne donc un cran plus bas que la même requête sur Opus 5. Ensuite, xhigh est plus récent que max : certains modèles qui acceptent max, comme Opus 4.6 ou Sonnet 4.6, n’acceptent pas xhigh. Vérifiez la compatibilité avant de généraliser ce niveau dans votre code.

Ce que l’effort influence vraiment

C’est ici que effort se distingue de l’ancien budget de réflexion. Un budget ne contraignait que la phase de réflexion ; effort agit sur tous les tokens de la réponse : le texte et les explications, les appels d’outils et leurs arguments, et la réflexion quand elle a lieu. C’est ce périmètre élargi qui en fait un outil de contrôle du coût bien plus puissant. Ce n’est pas pour autant un budget strict : à effort bas, Claude réfléchit encore sur un problème vraiment difficile, mais moins qu’il ne le ferait à effort élevé.

Le comportement change de manière visible. À effort réduit, Claude regroupe les opérations, fait moins d’appels d’outils et va droit au but. À effort élevé, il explique son plan avant d’agir, multiplie les appels et détaille ses résumés. Vous ne payez donc pas seulement plus ou moins de réflexion : vous obtenez un style de travail différent.

Une limite déjoue une intuition répandue : effort règle le volume de travail, pas la longueur du texte affiché. Sur Opus 5, la documentation précise que baisser l’effort ne raccourcit pas les réponses de façon fiable. Si vous voulez des réponses courtes, demandez-le dans votre prompt : c’est le prompt qui gouverne la concision.

Le piège du cache

effort façonne le prompt envoyé au modèle : en changer la valeur entre deux requêtes invalide le cache de prompt. Dans une conversation longue qui repose sur la mise en cache, alterner les niveaux revient à repayer le prix fort à chaque changement.

Depuis le 1er septembre 2026, une solution existe en bêta : l’effort par message. On insère dans messages un message role: "system" au contenu vide qui porte output_config.effort, avec l’en-tête mid-conversation-output-config-2026-07-01, et le nouveau niveau s’applique à partir du tour suivant sans casser le cache. Sur l’API Claude, il est disponible pour Fable 5.1, Mythos 5.1, Opus 5.5, Opus 5, Sonnet 5.5 et Haiku 5.5 ; un modèle qui ne le gère pas, comme Fable 5, renvoie une erreur 400.

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    output_config={"effort": "high"},
    messages=[
        {"role": "user", "content": "Planifie une migration de SQLite vers PostgreSQL en trois étapes."},
        {"role": "assistant", "content": "1. Exporter les données. 2. Créer le schéma. 3. Importer et vérifier."},
        {"role": "system", "content": [], "output_config": {"effort": "low"}},  # effort plus bas dès le tour suivant
        {"role": "user", "content": "Résume le plan en une phrase."},
    ],
    betas=["mid-conversation-output-config-2026-07-01"],
)

Sans cette bêta, la règle reste simple : si votre conversation repose sur le cache, choisissez un niveau au début et gardez-le constant. Faites varier l’effort entre types de charges (un niveau pour vos sous-agents, un autre pour vos tâches de fond), pas à l’intérieur d’une même conversation mise en cache.

Recommandations par modèle

Pour Fable 5.1, partez de high, le défaut ; montez à xhigh ou max pour le code et l’agentique les plus exigeants, et descendez à medium ou low pour le travail courant une fois vos évaluations faites. Pour Opus 5.5, le défaut est medium, un point de départ délibérément plus économe. Pour Sonnet 5.5, high par défaut, avec une mise en garde : ses niveaux ont été recalibrés et ne correspondent pas aux mêmes niveaux de Sonnet 5. Pour Haiku 5.5, commencez à medium, y compris pour le code agentique, et gardez low pour la conversation et les tâches simples à fort volume. Pour les modèles de l’été encore en service, Opus 5 et Fable 5, le défaut reste high. Dans tous les cas, la documentation demande de refaire un balayage des niveaux sur vos propres évaluations plutôt que de reprendre les réglages d’un modèle antérieur.

Dernier réglage à ne pas oublier : aux niveaux élevés, prévoyez un max_tokens généreux, car c’est une limite stricte sur toute la sortie, réflexion comprise. Pour Opus 5 aux niveaux xhigh et max, la documentation propose de partir de 64 000 tokens. Un effort élevé bridé par un plafond trop bas ne sert à rien. Et pour ces gros plafonds, passez en streaming afin d’éviter les délais d’attente HTTP.

À vous de jouer

Votre balayage d’effort. Choisissez cinq requêtes représentatives de votre application et lancez-les sur votre modèle aux niveaux low, medium et high. Relevez pour chacune usage.output_tokens, la durée et votre appréciation de la qualité. Retenez le niveau le plus bas dont la qualité vous suffit, et notez-le dans votre configuration avec la date du test.

Sources officielles : Effort (documentation Claude : niveaux, défauts, effort par message, recommandations par modèle) · Thinking · Prompt caching

Points clés à retenir

• effort se place dans output_config : cinq niveaux de low à max, défaut medium sur Opus 5.5 et Haiku 5.5, high ailleurs
• Il agit sur tous les tokens, appels d’outils compris, et change le style de travail
• Changer l’effort d’une requête à l’autre invalide le cache, sauf avec l’effort par message (bêta)
• Il ne raccourcit pas le texte affiché : demandez la concision dans le prompt
• Refaites toujours le calibrage sur vos propres évaluations, avec un max_tokens à la mesure de l’effort