La réflexion (thinking)

Avant de répondre, Claude peut réfléchir : dérouler un raisonnement, envisager plusieurs pistes, vérifier une hypothèse. Sur les modèles actuels, cette réflexion est adaptative : c’est Claude qui décide, à chaque requête, s’il en a besoin et combien. Votre levier principal s’appelle l’effort.

La réflexion adaptative

D’après la documentation, Claude évalue la complexité de chaque demande. Une question factuelle simple peut recevoir une réponse directe, sans bloc de réflexion ; un calcul en plusieurs étapes ou un débogage délicat déclenche un raisonnement plus poussé. Une même conversation peut donc mêler des tours avec et sans réflexion.

Ce qui change selon le modèle :

L’ancien réglage par budget fixe (budget_tokens) est refusé sur ces modèles : c’est l’effort qui le remplace.

Régler l’effort

L’effort se règle dans output_config, sur cinq niveaux : low, medium, high, xhigh, max.

const response = await client.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 16000,
  thinking: { type: "adaptive", display: "summarized" },
  output_config: { effort: "high" },
  messages: [{ role: "user", content: "Analyse les compromis entre microservices et monolithe pour notre équipe de 6 personnes." }],
});

for (const block of response.content) {
  if (block.type === "thinking") console.log("Réflexion :", block.thinking);
  if (block.type === "text") console.log("Réponse :", block.text);
}

L’effort ne règle pas seulement la réflexion : il pèse sur la dépense totale de jetons. Avec des outils, un effort plus bas conduit Claude à regrouper ses opérations et à faire moins d’appels. Montez l’effort pour le travail où la justesse dépend de cas faciles à manquer ; baissez-le pour les tâches simples, les sous-tâches et les échanges rapides. Comme toujours, mesurez sur vos propres exemples avant de changer un réglage par défaut.

Voir ou non la réflexion

Le paramètre display décide de ce que vous recevez. Par défaut sur les modèles actuels, il vaut "omitted" : les blocs de réflexion arrivent avec un texte vide. Avec "summarized", vous recevez un résumé lisible du raisonnement. Le raisonnement brut n’est jamais exposé. Si vous affichez la réflexion à vos utilisateurs en streaming, pensez à demander le résumé : sinon, l’attente ressemble à un long silence avant la réponse.

display ne change que la visibilité : la réflexion a lieu et elle est facturée de la même façon, comme des jetons de sortie.

Ce qu’il faut renvoyer

Dans une boucle d’outils, renvoyez les blocs de réflexion tels quels, avec le reste de la réponse : ne les modifiez pas et ne les retirez pas vous-même. L’API ignore, sans les facturer, ceux que le modèle courant ne peut pas lire.

Ce qui n’existe plus

Deux habitudes héritées sont à abandonner : le préremplissage de la réponse de l’assistant, refusé (erreur 400) par les modèles récents, et les réglages d’échantillonnage comme temperature : les modèles actuels n’acceptent que leur valeur par défaut, et la version d’API 2026-10-21 les refuse tous. Pour contrôler le format, utilisez les instructions du prompt système ou les sorties structurées ; pour contrôler la profondeur, l’effort.

À vous de jouer

Mesurer l’effort. Posez la même question de raisonnement à Claude Opus 5.5 avec effort à low, medium puis high, avec display: "summarized". Notez pour chacun la qualité de la réponse, le nombre de jetons de sortie dans usage et la durée de l’appel.

Sources officielles : What is thinking? (Claude Academy) · Adaptive thinking · Effort · Models overview

Points clés à retenir

• La réflexion est adaptative : Claude décide à chaque requête s’il réfléchit et combien
• Le levier est l’effort (output_config.effort, de low à max) ; medium par défaut sur Opus 5.5 et Haiku 5.5, high sur Fable 5.1 et Sonnet 5.5
• display: "summarized" pour voir un résumé ; la réflexion est facturée en jetons de sortie dans tous les cas
• budget_tokens, le préremplissage et temperature sont refusés sur les modèles actuels