Le mode réflexion prolongée : thinking et effort#

Le modèle peut réfléchir dans un espace séparé avant de répondre. Tu ne règles plus un budget de tokens à la main : tu règles un niveau d'effort.

Temps de lecture : 14 min | Niveau : Intermédiaire

Ce que tu sauras faire après#

• Expliquer la différence entre extended thinking (ancien) et adaptive thinking (actuel).
• Régler le paramètre effort au bon niveau selon ta tâche.
• Savoir ce que la réflexion coûte vraiment, et où lire le compteur.
• Éviter les trois pièges classiques : température, cache cassé, blocs de réflexion perdus.
• Reconnaître les cas où la réflexion ne sert strictement à rien.

1. De quoi on parle#

Quand la réflexion est active, le modèle produit d'abord des blocs thinking dans lesquels il travaille, puis des blocs text qui contiennent la réponse.

La doc le décrit comme ça : "When thinking is active, Claude works through the problem in its own words before answering: it restates what is being asked, tries approaches, checks intermediate results, and abandons paths that do not hold up."

Forme de la réponse :

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Le probleme a deux parties, je commence par la plus simple...",
      "signature": "WaUjzkypQ2mUEVM36O2Txu...."
    },
    {
      "type": "text",
      "text": "Voici l'analyse..."
    }
  ]
}

Deux choses à comprendre tout de suite :

• Le texte que tu vois n'est pas le raisonnement brut. C'est un résumé. La doc est claire : "what you see is never the raw chain of thought".
• Le champ signature est une copie chiffrée du raisonnement complet. Tu dois le renvoyer tel quel dans les tours suivants. On y revient en section 6.

Différence avec le fichier 01 : le chain of thought manuel, c'est toi qui écris "réfléchis étape par étape" dans le prompt, et le raisonnement sort dans la réponse visible. Ici, c'est un mécanisme du modèle, dans un canal séparé.

2. Ce qui a changé : budget_tokens est déprécié#

C'est le point le plus important de ce fichier, et celui que la plupart des tutoriels de 2025 ont faux.

Avant (extended thinking, mode manuel) : tu fixais un budget de tokens de réflexion.

# MODE MANUEL - toujours obligatoire sur Claude 4.5 et avant,
# deprecie sur 4.6, refuse (erreur 400) a partir de 4.7
client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[{"role": "user", "content": "..."}],
)

Maintenant (adaptive thinking) : le modèle décide lui-même s'il réfléchit et combien. Tu pilotes avec effort.

# ACTUEL
client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},
    messages=[{"role": "user", "content": "..."}],
)

La doc précise le statut exact : "extended thinking with a budget_tokens cap is still functional on Opus 4.6 and Sonnet 4.6 but is deprecated. On Claude 4.7 and later models, setting budget_tokens returns a 400 error."

Elle ajoute, sur les mesures internes : "In internal evaluations, adaptive thinking reliably drives better performance than extended thinking. Consider moving to adaptive thinking."

Attention : "déprécié" ne veut pas dire "supprimé partout"#

C'est la nuance que beaucoup de gens ratent, et elle peut te concerner directement si tu tournes sur un modèle plus ancien.

Si tu dois garder budget_tokens : le minimum est de 1 024 tokens et la valeur doit rester inférieure à max_tokens. La migration tient en une ligne : tu enlèves budget_tokens, tu mets thinking: {"type": "adaptive"}, et tu pilotes la profondeur avec output_config: {"effort": "..."}.

Où en est ton modèle#

Le comportement par défaut dépend du modèle. Extrait de la doc :

Sur ces derniers modèles (Opus 5.5, Fable 5.1, Mythos 5.1, Fable 5, Mythos 5, Mythos Preview), envoyer thinking: {"type": "disabled"} renvoie une erreur 400. Tu ne peux pas couper la réflexion : tu peux seulement baisser effort.

Cas particulier d'Opus 5 : il accepte thinking: {"type": "disabled"}, mais seulement à effort high ou en dessous. À xhigh ou max, la même requête renvoie une erreur 400.

Cette répartition par modèle bouge à chaque génération. Ne l'apprends pas par cœur : va lire la table de configuration par modèle sur la page Thinking le jour où tu intègres.

3. Le paramètre effort : le seul bouton qui compte#

effort se place dans output_config, pas dans l'objet thinking.

{
  "model": "claude-opus-5-5",
  "max_tokens": 4096,
  "output_config": { "effort": "medium" },
  "messages": [{ "role": "user", "content": "..." }]
}

Cinq niveaux existent :

Trois précisions de la doc qui évitent des malentendus :

1. effort agit sur tous les tokens de sortie, pas seulement sur la réflexion : le texte, les appels d'outils, les arguments. Un effort bas donne aussi moins d'appels d'outils et plus courts.
2. effort est une orientation, pas une limite stricte. Citation : "Effort is a behavioral signal, not a strict token budget." La seule limite dure, c'est max_tokens.
3. adaptive n'est pas une valeur d'effort. C'est un mode de thinking. La doc le dit explicitement : "Don't pass adaptive as an effort value."
4. Tous les modèles n'acceptent pas effort. Claude Haiku 4.5, par exemple, ne le supporte pas du tout. Et tous les modèles qui acceptent max n'acceptent pas forcément xhigh. Vérifie la table de disponibilité sur la page Effort avant d'écrire ton code.

Comment choisir, en pratique#

Traduction en langage data engineer :

• low : classification de logs, extraction de champs, génération de docstrings, sous-agents qui font une seule chose.
• medium : écriture d'une requête SQL standard, relecture d'un modèle dbt, génération de tests unitaires.
• high : conception d'un schéma, debug d'un pipeline qui échoue par intermittence, refactoring multi-fichiers.
• xhigh / max : migration complète, investigation d'un bug de données que personne n'a su reproduire.

Conseil de la doc pour les niveaux hauts : "At high and above, set a large max_tokens. It's a hard limit on total output (thinking plus response text)." Un point de départ raisonnable cité dans la doc est 64k tokens.

4. Comment déclencher plus ou moins de réflexion par le prompt#

effort est le premier levier. Le prompt est le second, et la doc conseille cet ordre : règle effort d'abord, ajoute du prompt seulement si le comportement ne colle toujours pas.

Pour que le modèle réfléchisse moins#

À mettre dans ton prompt système :

Extended thinking adds latency and should only be used when it
will meaningfully improve answer quality, typically for problems
that require multistep reasoning. When in doubt, respond directly.

Pour qu'il réfléchisse plus#

This task involves multistep reasoning. Think carefully before responding.

Par message, sans toucher au prompt système#

• Encourager : "Please think hard before responding."
• Supprimer : "Answer directly without deliberating."

C'est très utile dans un harnais d'agent : tu ajoutes la phrase d'encouragement sur les étapes de planification, et la phrase de suppression sur les confirmations de routine. Aucun paramètre ne change, donc le cache n'est pas cassé (voir section 7).

La doc prévient que l'effet dépend des mots exacts : "Steering effectiveness can be sensitive to exact wording." Si une formulation ne marche pas, essaie une variante plus directe.

5. Interaction avec la température : lis ce paragraphe#

C'est un piège classique quand on arrive d'un autre fournisseur.

Sur les modèles Claude récents, toute valeur non par défaut de temperature, top_p ou top_k renvoie une erreur 400. Ça vaut que la réflexion soit active ou non.

Les modèles concernés : Fable 5.1, Mythos 5.1, Fable 5, Mythos 5, Mythos Preview, Opus 5.5, Opus 5, Opus 4.8, Opus 4.7 et Sonnet 5.

La référence de l'API le confirme pour temperature : "Deprecated. Models released after Claude Opus 4.6 do not support setting temperature. A value of 1.0 will be accepted for backwards compatibility, all other values will be rejected with a 400 error."

Ce que ça veut dire pour toi : le réflexe "je mets temperature=0 pour du SQL déterministe" ne marche plus. Le déterminisme se pilote maintenant par le prompt et par les sorties structurées (voir 06-prefill-et-controle.md), pas par la température.

Sur les modèles plus anciens, la restriction est plus souple. Elle ne s'applique que quand la réflexion est active : temperature et top_k sont refusés, top_p est accepté entre 0.95 et 1.

6. Interaction avec les outils#

Trois règles à connaître avant de brancher la réflexion sur du tool use.

Règle 1 : une boucle d'outils, c'est UN seul tour#

Du point de vue du modèle, un tour assistant ne se termine pas tant que la réponse n'est pas finie, même s'il y a eu dix appels d'outils au milieu. Tout ce bloc tourne dans un seul mode de réflexion. Tu ne peux pas activer ou couper la réflexion en plein milieu.

User      : "Quel est le CA de septembre ?"
Assistant : [thinking] + [tool_use: query_database]
User      : [tool_result: "1 240 000 EUR"]
Assistant : [text: "Le CA de septembre est de 1,24 M EUR"]

Ces quatre lignes = un seul tour assistant.

Règle 2 : renvoie les blocs thinking tels quels#

Quand tu renvoies un tool_result, tu dois repasser à l'API tous les blocs thinking du message assistant, complets et non modifiés, à côté du bloc tool_use qu'ils accompagnaient.

Résumé de la doc :

• Obligatoire : à l'intérieur d'un tour avec outils, renvoyer les blocs thinking.
• Recommandé : entre les tours, tout renvoyer.
• Autorisé : hors tool use, omettre les blocs thinking des tours précédents.

Un bloc modifié est rejeté avec une erreur 400.

Piège concret : si ton code filtre les blocs avec block.type == "thinking", tu perds silencieusement les blocs redacted_thinking (réflexion masquée pour raison de sécurité) et tu casses le protocole. Filtre sur les deux types.

Règle 3 : le forçage d'outil n'est pas toujours possible#

• Avec l'ancien mode manuel (thinking: {type: "enabled"}), seuls tool_choice: {"type": "auto"} et {"type": "none"} sont acceptés.
• Avec adaptive thinking, le forçage d'outil fonctionne... sauf sur Claude Opus 5.5, Fable 5.1 et Mythos 5.1, qui refusent tool_choice de type any ou tool avec une erreur 400, quelle que soit la configuration.

Sur ces modèles, la doc renvoie vers strict tool use ou les sorties structurées à la place.

7. Coût, cache et compteurs#

Ce que tu paies#

Tu paies :

• Les tokens de réflexion, facturés comme des tokens de sortie.
• Les blocs de réflexion des tours précédents qui restent en contexte, facturés comme des tokens d'entrée.
• Le texte de réponse normal.

Avertissement important de la doc : "You are billed for the full thinking process, not the thinking content visible in the response." Le résumé que tu vois est beaucoup plus court que ce qui est facturé.

Où lire le compteur#

Le champ à surveiller est usage.output_tokens_details.thinking_tokens :

{
  "usage": {
    "input_tokens": 25,
    "output_tokens": 348,
    "output_tokens_details": {
      "thinking_tokens": 312
    }
  }
}

Ici, 312 tokens sur 348 sont partis en réflexion. Si tu vois ce ratio sur une tâche simple, baisse effort.

En streaming, ce détail n'arrive que sur l'événement final message_delta.

Comment borner le coût#

La doc est nette : "You don't set a thinking token budget. Two controls bound cost."

1. max_tokens : plafond dur sur le total de sortie (réflexion + texte). Attention, dans une boucle d'outils, chaque requête a son propre max_tokens, donc ça ne borne pas le tour entier.
2. effort : orientation souple.

Si tu vois stop_reason: "max_tokens", deux remèdes : monter max_tokens si le raisonnement était nécessaire, ou baisser effort si le modèle a sur-réfléchi.

Le piège du cache#

Changer effort ou la configuration de thinking entre deux requêtes casse le cache de prompt. La valeur d'effort est intégrée au prompt lui-même.

La doc donne un exemple chiffré : une même conversation, la deuxième requête lit 3546 tokens en cache, la troisième passe de medium à low et retombe à cache_read_input_tokens = 0.

Conséquence pratique : choisis un niveau d'effort au début d'une conversation et garde-le. Si tu dois varier, utilise le pilotage par prompt (section 4), qui ne casse pas le cache.

Il existe un mécanisme de changement d'effort en cours de conversation qui préserve le cache, via un message role: "system" portant output_config. C'est en beta (en-tête mid-conversation-output-config-2026-07-01) et limité à certains modèles. Vérifie la doc avant de compter dessus.

Dernier point : les tâches avec beaucoup de réflexion dépassent souvent la durée de vie de cache par défaut (5 minutes). La doc suggère le cache 1 heure dans ce cas.

8. Quand la réflexion ne sert à rien#

Quatre situations où tu paies pour rien :

1. Transformation mécanique. Reformater, extraire, convertir. Mets effort: low.
2. Requête de suivi qui ne fait que traiter un résultat d'outil. La doc note que ces requêtes sautent souvent la réflexion d'elles-mêmes, même à xhigh et max.
3. Tâche à fort volume et faible enjeu. Classer 100 000 lignes : low, ou un modèle plus petit (voir 08-cout-cache-et-performance.md).
4. Sur-vérification. Sur Claude Opus 5 spécifiquement, la doc dit que le modèle vérifie déjà bien son travail et que des consignes de vérification héritées d'anciens prompts provoquent de la sur-vérification. Il faut retirer ces consignes, pas les réécrire.

9. Ton template prêt à copier#

Template A - Appel API avec réflexion (Python)#

import anthropic

client = anthropic.Anthropic()

reponse = client.messages.create(
    model="[MODELE, ex: claude-opus-5-5]",
    max_tokens=[MAX_TOKENS, ex: 16000],
    thinking={"type": "adaptive"},              # laisse le modele decider
    output_config={"effort": "[low|medium|high|xhigh|max]"},
    system="[TON_PROMPT_SYSTEME]",
    messages=[{"role": "user", "content": "[TA_DEMANDE]"}],
)

# combien de tokens sont partis en reflexion ?
details = reponse.usage.output_tokens_details
print("reflexion :", details.thinking_tokens, "/", reponse.usage.output_tokens)

Template B - Prompt système pour calmer la réflexion#

[TON_ROLE_ET_TON_CONTEXTE]

Regle de reflexion : reflechir ajoute de la latence. Ne reflechis en profondeur
que si cela ameliore reellement la qualite, typiquement sur les problemes a
plusieurs etapes. En cas de doute, reponds directement.

Pour les taches suivantes, reponds toujours directement :
- [TACHE_MECANIQUE_1, ex: reformatage de donnees]
- [TACHE_MECANIQUE_2, ex: generation de docstrings]

Template C - Demander plus de réflexion sur un message précis#

[TA_DEMANDE_COMPLEXE]

Cette tache demande un raisonnement a plusieurs etapes. Reflechis soigneusement
avant de repondre. Verifie en particulier : [LE_POINT_QUI_TE_FAIT_PEUR].

À retenir#

• budget_tokens est déprécié sur les modèles 4.6 et refusé (erreur 400) à partir de Claude 4.7. Le mode actuel est thinking: {"type": "adaptive"} + output_config.effort. Mais sur Claude 4.5 et avant, budget_tokens reste le seul mode disponible : regarde ton modèle avant de choisir.
• Cinq niveaux d'effort : low, medium, high, xhigh, max. Défaut high sur la plupart des modèles, medium sur Opus 5.5.
• effort agit sur tous les tokens de sortie, pas seulement sur la réflexion. Seul max_tokens est une limite dure.
• La température est dépréciée sur les modèles sortis après Opus 4.6 : toute valeur autre que 1.0 renvoie une 400.
• Avec des outils : renvoie les blocs thinking et redacted_thinking non modifiés, sinon erreur 400.
• Changer effort en cours de conversation casse le cache. Choisis un niveau et garde-le, ou pilote par le prompt.
• Surveille usage.output_tokens_details.thinking_tokens. C'est ton indicateur de gaspillage.

Sources#

• Thinking - Anthropic (mode actuel : adaptive)
• Extended thinking - Anthropic (ancien mode manuel budget_tokens, règles de budget et guide de migration)
• Effort - Anthropic
• Steering thinking - Anthropic
• Prompting best practices - Anthropic
• Messages API reference - Anthropic
• Models overview - Anthropic