Réflexion adaptative : la fin du paramètre thinking explicite

De tous les changements de cette génération, c’est celui qui casse le plus de code existant. Il mérite donc d’être compris avec précision, d’autant qu’il fait cohabiter deux mécanismes aux noms trompeusement proches : la réflexion étendue, que vous connaissez peut-être déjà, et la réflexion adaptative, qui la remplace sur les modèles actuels. Confondre les deux conduit droit à des requêtes rejetées.

Deux mécanismes, deux philosophies

Avec la réflexion étendue, c’était vous qui décidiez : vous activiez la réflexion avec thinking: {"type": "enabled"} et vous accordiez au modèle un budget de tokens (budget_tokens) à consacrer au raisonnement avant de répondre. Le contrôle était total, mais il reposait entièrement sur vous : estimer, tâche par tâche, combien de réflexion serait nécessaire, et maintenir ces réglages dans le temps. Ce mécanisme est déprécié sur Opus 4.6 et Sonnet 4.6, et il renvoie une erreur 400 sur Opus 4.7, Opus 4.8 et tous les modèles des générations 5 et 5.5.

La réflexion adaptative inverse la logique. Le modèle décide lui-même quand réfléchir et combien : face à une question simple, il répond directement ; face à un problème qui le justifie, il prend le temps de raisonner. Sur tous les modèles des générations 5 et 5.5, elle est active par défaut : vous n’avez rien à configurer. Sur certains, elle est même impossible à couper : c’est le cas de Fable 5, Fable 5.1 et Opus 5.5.

Voici la situation d’après la documentation au 5 novembre 2026 :

La conséquence directe pour votre code : si une application activait la réflexion étendue et migre vers un modèle récent, ce réglage doit disparaître. Il ne s’agit pas d’adapter le paramètre, il s’agit de le supprimer.

Ce que la réponse contient

Même quand vous ne demandez rien, la réponse peut commencer par des blocs thinking. Sur tous les modèles actuels, leur texte est omis par défaut (display: "omitted") : le bloc arrive avec un champ thinking vide et une signature chiffrée, qui sert à la continuité de la conversation. Pour lire un résumé du raisonnement, passez thinking={"type": "adaptive", "display": "summarized"}. Une troisième valeur, "updates", en bêta, renvoie à la place les courtes notes de progression que certains modèles écrivent entre deux appels d’outils. Dans tous les cas, lisez les blocs par leur type, jamais par leur position : un code qui lit content[0].text casse dès qu’un bloc thinking passe en tête.

Alors, comment piloter la profondeur de réflexion ?

C’est la question que se posent les équipes qui avaient soigneusement calibré leurs budgets. La réponse tient en un mot : effort. La documentation est explicite : là où la réflexion adaptative est disponible, effort est le moyen recommandé de régler la profondeur de réflexion. Vous ne dites plus au modèle « réfléchis avec tel budget » ; vous lui dites « travaille à tel niveau d’intensité », et il en déduit la part de réflexion nécessaire. La leçon suivante détaille ce paramètre.

Un contresens circule à ce sujet : adaptive est le nom d’un mode de réflexion, pas une valeur d’effort. Les valeurs d’effort sont low, medium, high, xhigh et max.

Les contraintes de désactivation

Il reste un piège pour les équipes qui avaient pris l’habitude inverse : non pas activer la réflexion, mais la couper systématiquement pour gagner en latence. Sur Claude Opus 5 et Haiku 5.5, thinking: {"type": "disabled"} n’est accepté qu’à l’effort high ou en dessous : aux niveaux xhigh et max, la requête n’est pas simplement ignorée, elle échoue avec une erreur 400.

En pratique, cela produit une panne sournoise. Une application migre, tout fonctionne aux niveaux d’effort courants, puis un développeur monte l’effort à xhigh pour une tâche exigeante, et la requête échoue parce qu’un disabled hérité traînait encore dans la configuration. Lors d’une migration, cherchez donc les deux directions : le code qui activait la réflexion, et celui qui la coupait.

La génération 5.5 durcit encore la règle. Sur Opus 5.5, comme sur Fable 5.1, disabled et enabled renvoient tous deux une erreur 400 : il faut omettre le champ et régler la profondeur avec effort. Sonnet 5.5 introduit une valeur nouvelle, between_tools, qui coupe la réflexion préalable sans empêcher le modèle de réfléchir entre deux appels d’outils ; elle remplace disabled, refusé sur ce modèle, et n’est acceptée qu’aux niveaux low à high. Pour savoir ce qu’accepte un modèle sans tâtonner, l’API Models expose depuis octobre 2026 les champs capabilities.thinking.types.disabled et capabilities.thinking.types.between_tools.

À vous de jouer

Chasser les réglages hérités. Cherchez dans votre code toutes les occurrences de thinking, budget_tokens et content[0]. Pour chacune, notez le modèle visé et décidez quoi faire d’après le tableau : supprimer, remplacer par un niveau d’effort, ou garder disabled sous réserve d’un effort high au plus. Interrogez ensuite l’API Models pour vérifier, modèle par modèle, les valeurs de thinking acceptées.

Sources officielles : Thinking (documentation Claude : configuration par modèle, affichage) · Effort · Models overview (API Models) · Release notes

Points clés à retenir

• Réflexion étendue (enabled avec un budget) : refusée par Opus 4.7, Opus 4.8 et toutes les générations 5 et 5.5
• Réflexion adaptative : le modèle décide seul ; toujours active sur Fable 5, Fable 5.1 et Opus 5.5
• Le texte de la réflexion est omis par défaut : lisez les blocs par leur type
• Sur les modèles actuels, pilotez la profondeur avec effort, et adaptive n’est pas une valeur d’effort
• disabled n’est accepté qu’à l’effort high au plus (Opus 5, Haiku 5.5) ; sur Sonnet 5.5, between_tools le remplace