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 a un avantage appréciable : il ne nécessite aucun en-tête bêta. Vous pouvez l’utiliser dès aujourd’hui, en production, sans précaution particulière.

Où il se place dans la requête

Commençons par la syntaxe, parce que c’est là que se produit la première erreur : effort se trouve dans output_config, et non à la racine de la requête. Un effort posé au mauvais niveau ne déclenchera pas forcément d’erreur explicite — il sera simplement sans effet, ce qui est pire.

import anthropic

client = anthropic.Anthropic()

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

Les cinq niveaux

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

Deux précisions évitent des débats inutiles en équipe. D’abord, régler effort sur high produit exactement le même comportement que de ne pas passer le paramètre du tout : inutile donc de l’ajouter partout « pour être sûr ». Ensuite, xhigh étant plus récent, certains modèles qui acceptent max ne l’acceptent pas — 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 radicalement de l’ancien budget de réflexion. Un budget ne contraignait que la phase de réflexion ; effort, lui, 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.

Concrètement, le comportement du modèle 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, 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 doit cependant être posée d’emblée, car elle déjoue une intuition répandue : effort contrôle le volume de réflexion, pas la longueur du texte affiché. Sur Opus 5, baisser l’effort ne raccourcit pas de façon fiable la réponse. Si vous voulez des réponses courtes, demandez-le explicitement dans votre prompt — c’est le prompt qui gouverne la concision, pas l’effort.

Le piège du cache

effort est un réglage par requête, et c’est précisément ce qui crée un piège. Comme il façonne le prompt envoyé au modèle, le changer entre deux requêtes invalide le cache de prompt. Dans une conversation longue qui repose sur la mise en cache, alterner les niveaux d’effort revient à payer le prix fort à chaque tour, en annulant l’économie que le cache devait justement procurer.

La règle pratique en découle naturellement : si votre conversation repose sur la mise en cache, choisissez un niveau d’effort au début et gardez-le constant. Faites varier l’effort entre différents types de charges — un niveau pour vos sous-agents, un autre pour vos tâches de fond — mais pas à l’intérieur d’une même conversation mise en cache.

Recommandations par modèle

Pour Opus 5, partez de high, qui est le défaut, montez à xhigh pour le code et l’agentique exigeants, et descendez à low ou medium dès que vos évaluations montrent que la qualité tient. Pour Fable 5, restez sur high par défaut, en gardant en tête que ses niveaux bas dépassent souvent le xhigh des modèles précédents — descendre en effort y est donc moins risqué qu’on ne l’imagine. Pour Sonnet 5, high par défaut, et low pour le conversationnel à fort volume.

Dernier réglage à ne pas oublier : aux niveaux xhigh et max, prévoyez un max_tokens généreux — 64 000 tokens est un point de départ raisonnable — afin que le modèle ait la place de réfléchir et d’enchaîner ses appels d’outils. Un effort élevé bridé par un plafond de sortie trop bas ne sert à rien.

Source officielle : Effort

Points clés à retenir

• effort se place dans output_config, cinq niveaux de low à max, défaut high
• Il agit sur tous les tokens, y compris les appels d’outils
• Le changer en cours de conversation invalide le cache de prompt
• Il ne raccourcit pas le texte affiché : demandez-le dans le prompt
• Recalibrez toujours sur vos propres évaluations