Thinking

Un modèle qui répond en une seule passe doit tout réussir du premier coup : pas de brouillon, pas de vérification, pas de changement de cap à mi-chemin. Pour une démonstration, un bug délicat ou une longue tâche agentique, la première approche n'est souvent pas la meilleure.

La réflexion supprime cette contrainte. Lorsque la réflexion est active, Claude travaille sur le problème avec ses propres mots avant de répondre : il reformule ce qui est demandé, essaie des approches, vérifie les résultats intermédiaires et abandonne les pistes qui ne tiennent pas. Ce raisonnement arrive dans des blocs de contenu thinking avant la réponse, et Claude s'en sert pour produire la réponse finale. C'est pourquoi la réflexion améliore les performances sur des tâches complexes comme les mathématiques, le codage, l'analyse et le travail agentique de longue durée, où la qualité de la réponse dépend d'un travail intermédiaire qui serait autrement compressé dans la réponse elle-même ou ignoré.

La réflexion a un coût : les tokens que Claude dépense à raisonner sont facturés comme des tokens de sortie, même lorsque le texte de réflexion ne vous est pas renvoyé, et ils comptent dans max_tokens au même titre que le texte de la réponse. Cette page couvre le comportement de la réflexion à travers la surface de l'API : son activation, la lecture de sa sortie, et la gestion de ses interactions avec les outils, le streaming, la mise en cache et la fenêtre de contexte.

Fonctionnement de la réflexion

Que Claude réfléchisse sur une requête donnée, et avec quelle profondeur, dépend de votre configuration de réflexion et de la complexité de la requête.

Voici à quoi ressemble la réflexion dans une réponse : un ou plusieurs blocs de contenu thinking arrivent avant les blocs text. Le bloc de réflexion est toujours du contenu généré, comme le bloc text qui le suit, mais il est séparé de la réponse canonique. Chaque bloc de réflexion porte également un champ signature, une copie chiffrée du raisonnement complet que vous renvoyez inchangée dans les conversations multi-tours et d'utilisation d'outils (voir Chiffrement de la réflexion) :

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me break this down. The question has two parts, so I'll start with the simpler one and use its result to constrain the second...",
      "signature": "WaUjzkypQ2mUEVM36O2Txu...."
    },
    {
      "type": "text",
      "text": "Based on my analysis..."
    }
  ]
}

Vous ne voyez pas toujours ce texte, et ce que vous voyez n'est jamais la chaîne de pensée brute : le texte d'un bloc de réflexion est un résumé du raisonnement de Claude. Le champ display de la configuration de réflexion contrôle si ce résumé est renvoyé ou non : "summarized" le renvoie, tandis que "omitted", la valeur par défaut sur de nombreux modèles, renvoie des blocs de réflexion avec un champ thinking vide. Dans les deux cas, le bloc est facturé de la même manière et renvoyé de la même manière dans les conversations multi-tours. Voir Contrôler l'affichage de la réflexion pour les valeurs par défaut et les détails par modèle.

Si Claude utilise des outils, la réflexion peut également apparaître entre les appels d'outils. Voir Réflexion avec utilisation d'outils. Pour le format de réponse complet, voir la référence de l'API Messages.

Configurer la réflexion

Sur la plupart des modèles, la réflexion est activée par défaut ou à un paramètre près. La configuration que chaque modèle accepte, et sa valeur par défaut, sont répertoriées dans le tableau de configuration par modèle sur la page de dépannage.

Sur Claude Opus 5, Claude Sonnet 5, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5 et Claude Mythos Preview, la réflexion est déjà activée et ne nécessite aucune configuration. display est par défaut "omitted" sur ces modèles, de sorte que le texte de réflexion est masqué jusqu'à ce que vous choisissiez de l'activer. Activez-le avec thinking: {"type": "adaptive", "display": "summarized"}, ce qui correspond exactement à la requête suivante avec la chaîne de modèle remplacée.

Sur Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 et Claude Sonnet 4.6, la réflexion est désactivée jusqu'à ce que vous définissiez thinking: {type: "adaptive"}, ce qui permet à Claude de décider quand et avec quelle profondeur réfléchir en fonction de la requête. Les exemples suivants font cela, définissent display: "summarized" pour que le texte de réflexion soit visible, et utilisent un max_tokens généreux :

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
)

for block in response.content:
    if block.type == "thinking":
        print(f"\nThinking: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")

L'exécution de l'exemple affiche la réflexion résumée, puis la réponse :

Thinking: Use Euclidean algorithm.
1071 = 2*462 + 147
462 = 3*147 + 21
147 = 7*21 + 0
GCD = 21

Response: ## Finding GCD of 1071 and 462

I'll use the **Euclidean algorithm**, repeatedly dividing and taking remainders...

Les tokens de réflexion comptent dans max_tokens, alors définissez-le suffisamment haut pour laisser de la place à la fois à la réflexion et au texte de la réponse. Voir Contrôle des coûts sur la page d'orientation et Réflexion et fenêtre de contexte.

Désactiver la réflexion

Sur Claude Sonnet 5, où la réflexion est activée par défaut, vous pouvez la désactiver :

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    thinking={"type": "disabled"},
    messages=[{"role": "user", "content": "Summarize this article in one sentence."}],
)

Claude Opus 5 a également la réflexion activée par défaut et accepte thinking: {type: "disabled"} à un effort high ou inférieur. À un effort xhigh ou max, la réflexion ne peut pas être désactivée : les requêtes qui combinent thinking: {type: "disabled"} avec ces niveaux d'effort renvoient une erreur 400. Cette restriction s'applique à Claude Opus 5 et aux modèles ultérieurs et est appliquée à chaque requête. Avec la réflexion désactivée, Claude Opus 5 peut occasionnellement émettre des appels d'outils sous forme de texte brut ou inclure des balises XML internes dans sa sortie visible. Voir Exécution avec la réflexion désactivée pour les mesures d'atténuation par prompt.

Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5 et Claude Mythos Preview rejettent thinking: {type: "disabled"}. La réflexion ne peut pas être désactivée sur ces modèles.

Si votre modèle ne prend en charge que la réflexion étendue (voir le tableau de configuration par modèle), configurez-la avec type: "enabled" et une valeur budget_tokens à la place. La page Réflexion étendue couvre cette configuration. Et si une configuration de réflexion renvoie une erreur 400, Dépannage de la réflexion associe chaque message d'erreur à sa solution.

Lire la sortie de réflexion

Contrôler l'affichage de la réflexion

Le champ display de la configuration de réflexion contrôle la manière dont le contenu de réflexion est renvoyé dans les réponses de l'API. display fonctionne dans les deux modes : définissez-le aux côtés de type: "adaptive" ou type: "enabled". Il accepte ces valeurs :

• "summarized" : les blocs de réflexion contiennent du texte de réflexion résumée, un résumé lisible du raisonnement de Claude. C'est la valeur par défaut sur Claude Opus 4.6, Claude Sonnet 4.6 et les modèles antérieurs.
• "omitted" : les blocs de réflexion sont renvoyés avec un champ thinking vide. Le champ signature porte toujours la réflexion complète chiffrée pour la continuité multi-tours (voir Chiffrement de la réflexion). C'est la valeur par défaut sur Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5, Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7 et Claude Mythos Preview.
• "updates" (bêta) : les blocs de raisonnement sont renvoyés avec un champ thinking vide, comme avec "omitted", et les courtes mises à jour de progression que certains modèles écrivent entre les appels d'outils reviennent sous forme de texte lisible. Nécessite l'en-tête bêta thinking-display-updates-2026-08-18.

Définissez display: "omitted" lorsque votre application ne présente pas le contenu de réflexion aux utilisateurs. Le principal avantage est un délai plus court jusqu'au premier token de texte lors du streaming : le serveur ignore entièrement le streaming des tokens de réflexion et ne fournit que la signature, de sorte que la réponse textuelle finale commence à être diffusée plus tôt.

Avec display: "omitted", la réponse contient des blocs thinking avec un champ thinking vide :

{
  "content": [
    {
      "type": "thinking",
      "thinking": "",
      "signature": "EosnCkYICxIMMb3LzNrMu..."
    },
    {
      "type": "text",
      "text": "The answer is 12,231."
    }
  ]
}

Gardez à l'esprit ce qui suit lorsque vous travaillez avec la réflexion omise :

• Vous êtes toujours facturé pour la totalité des tokens de réflexion. L'omission réduit la latence, pas le coût.
• Si vous renvoyez des blocs de réflexion dans des conversations multi-tours, renvoyez-les inchangés. Le serveur déchiffre la signature pour reconstruire la réflexion originale pour la construction du prompt (voir Préserver les blocs de réflexion). Tout texte que vous placez dans le champ thinking d'un bloc omis renvoyé est ignoré.
• display est invalide avec thinking.type: "disabled" (il n'y a rien à afficher).
• Lors de l'utilisation de thinking.type: "adaptive" et que le modèle ignore la réflexion pour une requête simple, aucun bloc de réflexion n'est produit, quelle que soit la valeur de display.
• Lors du streaming avec display: "omitted", aucun événement thinking_delta n'est émis. Avec display: "updates", seuls les blocs de mise à jour de progression diffusent des événements thinking_delta. Voir Streaming de la réflexion pour la séquence d'événements.

Dans le SDK Ruby, les hachages simples prennent display: comme le montrent les exemples. La classe typée ThinkingConfigAdaptive nomme le paramètre display_ (avec un trait de soulignement final, pour éviter de masquer le Kernel#display de Ruby). Dans les deux cas, le champ réseau reste display.

Réflexion résumée

Lorsque display est "summarized", le texte de réflexion que vous recevez est un résumé du processus de réflexion complet de Claude plutôt que la chaîne de pensée brute. La réflexion résumée offre tous les avantages d'intelligence de la réflexion tout en empêchant les abus. Aucun paramètre display ne renvoie la chaîne de pensée brute.

Gardez à l'esprit ce qui suit lorsque vous travaillez avec la réflexion résumée :

• Vous êtes facturé pour la totalité des tokens de réflexion générés par la requête originale, et non pour les tokens du résumé. Le nombre de tokens de sortie facturés ne correspond pas au nombre de tokens que vous voyez dans la réponse.
• Sur Claude Opus 4.6, Claude Sonnet 4.6 et les modèles antérieurs, les premières lignes de la sortie de réflexion sont plus détaillées, fournissant un raisonnement détaillé particulièrement utile à des fins d'ingénierie de prompt. Claude Mythos Preview résume dès le premier token, de sorte que ses blocs de réflexion ne montrent pas ce préambule détaillé.
• La synthèse préserve les idées clés du processus de réflexion de Claude avec une latence supplémentaire minimale, de sorte que les résumés peuvent être diffusés au fur et à mesure de leur arrivée.
• La synthèse est traitée par un modèle différent de celui que vous ciblez dans vos requêtes. Le modèle de réflexion ne voit pas la sortie résumée.
• Alors qu'Anthropic cherche à améliorer la fonctionnalité de réflexion, le comportement de synthèse est susceptible de changer.

Pour voir le raisonnement du modèle, lisez les blocs thinking plutôt que de demander le raisonnement dans le texte de la réponse. Sur Claude Fable 5.1 et Claude Fable 5, une requête qui tente de susciter le raisonnement interne du modèle dans le cadre du texte de la réponse peut être refusée avec stop_details.category: "reasoning_extraction". Voir Catégories de refus pour la référence du champ et les conseils de gestion.

Streaming de la réflexion

La réflexion fonctionne avec le streaming. Les blocs de réflexion sont diffusés sous forme d'événements thinking_delta à l'intérieur d'événements content_block_delta, suivis d'un seul événement signature_delta juste avant le content_block_stop du bloc. Les blocs de texte sont diffusés ensuite comme d'habitude.

Les exemples suivants diffusent une réponse avec réflexion adaptative, en affichant les deltas de réflexion et de texte au fur et à mesure de leur arrivée :

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
) as stream:
    for event in stream:
        if event.type == "content_block_start":
            print(f"\nStarting {event.content_block.type} block...")
        elif event.type == "content_block_delta":
            if event.delta.type == "thinking_delta":
                print(event.delta.thinking, end="", flush=True)
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)

Pour réassembler des blocs de réflexion complets avec leurs signatures après le streaming, utilisez l'assistant d'accumulation de messages de votre SDK lorsqu'il en existe un (par exemple, stream.get_final_message() en Python ou stream.finalMessage() en TypeScript) au lieu de concaténer les deltas vous-même.

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-4-8", "stop_reason": null, "stop_sequence": null}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "thinking", "thinking": "", "signature": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "I need to find the GCD of 1071 and 462 using the Euclidean algorithm.\n\n1071 = 2 × 462 + 147"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n462 = 3 × 147 + 21\n147 = 7 × 21 + 0\n\nSo GCD(1071, 462) = 21"}}

// Additional thinking deltas...

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b..."}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "text", "text": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "The greatest common divisor of 1071 and 462 is **21**."}}

// Additional text deltas...

event: content_block_stop
data: {"type": "content_block_stop", "index": 1}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null}}

event: message_stop
data: {"type": "message_stop"}

Lorsque display: "omitted" est défini, le bloc de réflexion s'ouvre, un seul signature_delta arrive, et le bloc se ferme sans aucun événement thinking_delta. Le streaming de texte commence immédiatement après :

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"thinking","thinking":"","signature":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"signature_delta","signature":"EosnCkYICxIMMb3LzNrMu..."}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"text","text":""}}

Avec display: "updates" (bêta), les blocs de raisonnement sont diffusés comme ils le font sous "omitted". Chaque bloc de mise à jour de progression diffuse son texte sous forme d'événements thinking_delta avant le bloc tool_use qu'il introduit. Une pause de plusieurs secondes avant l'ouverture du bloc de mise à jour de progression est normale :

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"thinking","thinking":"","signature":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"thinking_delta","thinking":"Confirmed the retry path never refreshes the expired token. Editing auth.py to add the refresh call."}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"signature_delta","signature":"Es8CCkYICxIM..."}}

event: content_block_stop
data: {"type":"content_block_stop","index":1}

event: content_block_start
data: {"type":"content_block_start","index":2,"content_block":{"type":"tool_use","id":"toolu_01D7FLrfh4GYq7yT1ULFeyMV","name":"edit_file","input":{}}}

Sous "updates", traitez un bloc comme une mise à jour de progression dès que l'un de ses événements thinking_delta porte un texte non vide.

Pour les mécanismes généraux de streaming, voir Streaming de messages.

Réflexion et effort

Le paramètre thinking contrôle si Claude réfléchit dans des blocs de réflexion avant de répondre ; le paramètre effort contrôle la quantité de travail que Claude consacre à l'ensemble de la réponse, ce qui, en mode adaptatif, inclut la fréquence et la profondeur de sa réflexion. Ne passez pas adaptive comme valeur de effort : adaptive est un mode de réflexion, et non un niveau d'effort.

Pour savoir ce que chaque niveau d'effort fait au comportement de réflexion, voir le tableau de comportement de réflexion par niveau sur la page Orienter la réflexion. La page Effort documente le paramètre lui-même, y compris les niveaux que chaque modèle prend en charge. Sur Claude Opus 4.5, le seul modèle à réflexion étendue uniquement qui prend en charge l'effort, l'effort se compose avec budget_tokens. Voir Règles de budget et réglage.

Avec les deux contrôles séparés de cette manière, choisissez celui qui correspond à votre objectif :

• Coût ou latence plus faibles sur une charge de travail avec réflexion activée : réduisez d'abord effort. Il réduit l'ensemble de la réponse, réflexion comprise.
• Claude réfléchit trop rarement ou trop superficiellement : augmentez effort, ou voir Orienter la fréquence à laquelle Claude réfléchit sur la page d'orientation.
• Vous avez besoin que la réflexion soit complètement désactivée : utilisez thinking: {type: "disabled"} sur les modèles qui le permettent (voir le tableau de configuration par modèle).
• Vous avez besoin d'un plafond strict sur les dépenses : utilisez max_tokens. L'effort est une orientation souple. max_tokens est une limite stricte.

Réflexion avec utilisation d'outils

La réflexion fonctionne aux côtés de l'utilisation d'outils, permettant à Claude de raisonner sur la sélection d'outils et de traiter les résultats d'outils. Deux contraintes s'appliquent :

1. Limitation du choix d'outil (mode manuel) : l'utilisation d'outils avec la réflexion étendue manuelle (thinking: {type: "enabled"}) ne prend en charge que tool_choice: {"type": "auto"} (la valeur par défaut) ou tool_choice: {"type": "none"}. L'utilisation de tool_choice: {"type": "any"} ou tool_choice: {"type": "tool", "name": "..."} entraîne une erreur car ces options forcent l'utilisation d'outils, ce qui est incompatible avec la réflexion étendue manuelle. La réflexion adaptative, y compris sur les modèles où la réflexion est activée par défaut, prend en charge l'utilisation forcée d'outils, sauf sur Claude Fable 5.1 et Claude Mythos 5.1 (voir Préremplissage de réponse et utilisation forcée d'outils).
2. Préserver les blocs de réflexion : lorsque vous renvoyez les résultats d'outils, vous devez renvoyer les blocs de réflexion du message de l'assistant à l'API, complets et non modifiés. Voir Préserver les blocs de réflexion.

Une boucle d'utilisation d'outils est un seul tour d'assistant. Du point de vue du modèle, un tour d'assistant ne se termine pas tant que Claude n'a pas terminé sa réponse complète, qui peut inclure plusieurs appels d'outils et résultats. Toute cette séquence est un seul tour d'assistant :

User: "What's the weather in Paris?"
Assistant: [thinking] + [tool_use: get_weather]
User: [tool_result: "20°C, sunny"]
Assistant: [text: "The weather in Paris is 20°C and sunny"]

Le tour entier s'exécute dans un seul mode de réflexion : vous ne pouvez pas basculer la réflexion au milieu d'un tour, y compris pendant la boucle d'utilisation d'outils. En mode étendu (manuel), l'API impose en outre que le tour d'assistant final d'une requête avec réflexion activée commence par un bloc de réflexion. Le mode adaptatif assouplit cela : aucun tour d'assistant n'a besoin de commencer par un.

Les conflits en milieu de tour se dégradent gracieusement. Si vous basculez la réflexion en milieu de tour (par exemple, entre l'envoi d'un appel d'outil et le renvoi de son résultat), l'API ne génère pas d'erreur. Au lieu de cela, elle désactive silencieusement la réflexion pour cette requête. Pour préserver la qualité du modèle, l'API peut supprimer les blocs de réflexion qui créeraient une structure de tour invalide, ou désactiver la réflexion lorsque l'historique de la conversation est incompatible avec l'activation de la réflexion. Pour confirmer si la réflexion était active, vérifiez la présence de blocs thinking dans la réponse.

Basculez entre les tours, pas à l'intérieur. Planifiez votre stratégie de réflexion au début de chaque tour. Terminez le tour d'assistant, puis modifiez la configuration de réflexion pour le suivant :

User: "What's the weather?"
Assistant: [tool_use] (thinking disabled)
User: [tool_result]
Assistant: [text: "It's sunny"]
User: "What about tomorrow?"
Assistant: [thinking] + [text: "..."] (thinking enabled - new turn)

Le basculement des modes de réflexion invalide également la mise en cache des prompts. Voir Réflexion et mise en cache des prompts.

Préserver les blocs de réflexion

Lorsque Claude invoque un outil, il met en pause la construction de sa réponse pour attendre des informations externes. Lorsque vous renvoyez le résultat de l'outil, Claude continue de construire cette même réponse, de sorte que son raisonnement antérieur doit toujours être présent. Renvoyez chaque bloc thinking à l'API complet et non modifié, aux côtés du bloc tool_use qu'il accompagnait. Cela importe pour deux raisons :

1. Continuité du raisonnement : les blocs de réflexion capturent le raisonnement étape par étape qui a conduit aux requêtes d'outils. Les inclure permet à Claude de continuer à raisonner là où il s'était arrêté.
2. Maintien du contexte : les résultats d'outils apparaissent comme des messages utilisateur dans la structure de l'API, mais ils font partie d'un flux de raisonnement continu. Préserver les blocs de réflexion maintient ce flux à travers les appels d'API.

En bref :

• Requis : au sein d'un tour d'utilisation d'outils, renvoyez les blocs de réflexion.
• Recommandé : à travers les tours, renvoyez tout.
• Autorisé : en dehors de l'utilisation d'outils, omettez la réflexion des tours précédents.

Vous n'avez pas besoin d'élaguer vous-même l'ancienne réflexion. Renvoyez tous les blocs de réflexion dans les conversations multi-tours, et l'API les filtre automatiquement, conserve les blocs nécessaires pour préserver le raisonnement du modèle, et facture les tokens d'entrée uniquement pour les blocs réellement montrés à Claude. Les blocs des tours précédents conservés dépendent du modèle. Voir Préservation des blocs de réflexion par modèle. Pour remplacer la valeur par défaut, utilisez la stratégie d'édition de contexte clear_thinking_20251015.

Au sein du dernier message de l'assistant, la séquence de blocs thinking consécutifs doit correspondre à ce que le modèle a généré dans la requête originale : vous ne pouvez pas les réorganiser, les modifier ou les supprimer partiellement. Cela inclut les blocs redacted_thinking.

Pour une présentation complète en deux tours avec du code dans chaque SDK, voir Réflexion dans les workflows d'outils et multi-tours. Elle définit un outil, reçoit une réponse réflexion-plus-utilisation-d'outils, et renvoie le tour d'assistant avec le résultat de l'outil.

Réflexion entrelacée

La réflexion entrelacée permet à Claude de réfléchir entre les appels d'outils, en raisonnant sur chaque résultat d'outil avant d'agir en conséquence. Avec la réflexion entrelacée, Claude peut :

• Raisonner sur les résultats d'un appel d'outil avant de décider quoi faire ensuite
• Enchaîner plusieurs appels d'outils avec des étapes de raisonnement entre eux
• Prendre des décisions plus nuancées en fonction des résultats intermédiaires

Avec la réflexion adaptative, la réflexion entrelacée est automatique sur chaque modèle qui prend en charge la réflexion adaptative. Aucun en-tête bêta n'est nécessaire. Sur Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5, Claude Opus 4.8 et Claude Opus 4.7, le raisonnement entre les appels d'outils apparaît toujours dans des blocs de réflexion. Claude Haiku 4.5 ne prend pas en charge la réflexion entrelacée. Sur les modèles utilisant la réflexion étendue manuelle, l'entrelacement nécessite un en-tête bêta et change la manière dont le budget de réflexion est compté. Réflexion entrelacée en mode manuel couvre les règles par modèle et le comportement d'en-tête spécifique à la plateforme.

Avec la réflexion entrelacée, l'allocation de réflexion peut s'étendre sur tout le tour d'assistant plutôt que sur une seule réponse. La réflexion entrelacée n'est prise en charge que pour les outils utilisés via l'API Messages.

Pour une comparaison détaillée montrant ce que la réflexion entrelacée change dans un workflow à deux outils, voir Comment la réflexion entrelacée change le flux.

Mises à jour de progression entre les appels d'outils

Sur Claude Fable 5.1, Claude Mythos 5.1 et Claude Fable 5, le modèle peut écrire une mise à jour de progression entre les appels d'outils. Une mise à jour de progression est une phrase ou deux sur ce que le modèle vient de trouver et ce qu'il s'apprête à faire ensuite, écrite pour la personne qui observe l'agent plutôt que comme un raisonnement. Chacune revient comme son propre bloc thinking avec sa propre signature, séparée de tout bloc de raisonnement au même point. Elle se situe immédiatement avant le bloc tool_use ou server_tool_use qu'elle introduit. Au plus une mise à jour de progression précède chaque appel d'outil, et le modèle peut en ignorer n'importe laquelle. Les mises à jour de progression ne sont pas de la réflexion entrelacée : elles apparaissent que des blocs de raisonnement apparaissent ou non entre les appels d'outils, et une réponse peut contenir les deux.

Ce que contient un bloc de mise à jour de progression dépend de display :

Utilisez display: "updates" pour une interface d'agent qui garde le raisonnement masqué et montre à l'utilisateur une ligne d'état à chaque étape. Sous celle-ci, tout bloc thinking avec un texte non vide est une mise à jour de progression, alors affichez ceux-là et rien d'autre. C'est en bêta et nécessite l'en-tête bêta thinking-display-updates-2026-08-18 (sur Amazon Bedrock, Google Cloud et Microsoft Foundry, passez la valeur bêta comme décrit dans En-têtes bêta). Sans lui, la valeur est rejetée avec la même erreur 400 invalid_request_error qu'une valeur display inconnue.

{
  "model": "claude-fable-5-1",
  "max_tokens": 16000,
  "thinking": { "type": "adaptive", "display": "updates" },
  "tools": [
    {
      "name": "edit_file",
      "description": "Replace the contents of a file in the repository.",
      "input_schema": {
        "type": "object",
        "properties": {
          "path": { "type": "string" },
          "content": { "type": "string" }
        },
        "required": ["path", "content"]
      }
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "The login test fails after an hour of uptime. Find out why and fix it."
    }
  ]
}

Sous "updates", le début de la réponse qui suit un tool_result ressemble à ceci. Le premier bloc est du raisonnement et reste vide, comme il le serait sous "omitted". Le second porte du texte, c'est donc une mise à jour de progression. Sous "summarized", les deux blocs portent du texte, et sous "omitted", les deux sont vides.

{
  "content": [
    {
      "type": "thinking",
      "thinking": "",
      "signature": "EqMBCkYICxIM..."
    },
    {
      "type": "thinking",
      "thinking": "Confirmed the retry path never refreshes the expired token. Editing auth.py to add the refresh call.",
      "signature": "Es8CCkYICxIM..."
    },
    {
      "type": "tool_use",
      "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
      "name": "edit_file",
      "input": { "path": "auth.py", "content": "..." }
    }
  ]
}

Gardez à l'esprit ce qui suit lorsque vous travaillez avec les mises à jour de progression :

• Renvoyez les blocs de mise à jour de progression inchangés avec le reste du tour d'assistant, comme tout autre bloc thinking.
• Le texte que vous recevez est un résumé de la mise à jour de progression, normalement une phrase ou deux. Ne vous fiez pas à sa longueur. La mise à jour de progression compte dans usage.output_tokens à sa pleine longueur, pas à celle du résumé.
• Un bloc de mise à jour de progression peut revenir avec un champ thinking vide sous n'importe quelle valeur de display. N'affichez rien pour un bloc vide. Sous "updates", il ressemble à un bloc de raisonnement vide et ne nécessite aucune gestion séparée.
• Lorsqu'une réponse s'arrête sur max_tokens, model_context_window_exceeded ou stop_sequence peu après un appel d'outil ou un résultat d'outil, son dernier bloc peut être un bloc de mise à jour de progression remplaçant le travail que le modèle n'avait pas terminé. Sous "updates" et "summarized", son texte est exactement This part of the response was interrupted before it finished. et vous pouvez l'afficher comme toute autre mise à jour. Sous "omitted", il est vide. Pour continuer, renvoyez le tour d'assistant inchangé et ajoutez un nouveau message user (avec un tool_result pour chaque bloc tool_use de ce tour).
• Lors du streaming, attendez-vous à une pause de plusieurs secondes avant l'ouverture d'un bloc de mise à jour de progression. Voir la trace "updates" dans Streaming de la réflexion.
• Ces modèles écrivent moins de mises à jour de progression à un effort plus élevé et dans les longues chaînes d'outils. Si votre interface en dépend, voir Demander des mises à jour de progression destinées à l'utilisateur.

Préservation des blocs de réflexion par modèle

Que les blocs de réflexion des tours d'assistant précédents restent dans le contexte par défaut dépend du modèle :

• Conserver tous les tours précédents : Claude Opus 4.5 et les modèles Opus ultérieurs, Claude Sonnet 4.6 et les modèles Sonnet ultérieurs, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5 et Claude Mythos Preview.
• Conserver uniquement le dernier tour : les modèles Opus et Sonnet antérieurs, et tous les modèles Haiku jusqu'à Claude Haiku 4.5. Lorsque vous renvoyez des blocs de réflexion plus anciens, l'API les supprime automatiquement. Vous n'avez pas besoin de les supprimer vous-même.

La préservation apporte deux avantages :

• Optimisation du cache : les blocs de réflexion préservés permettent des accès au cache pendant l'utilisation d'outils, car ils sont renvoyés avec les résultats d'outils et mis en cache de manière incrémentielle tout au long du tour d'assistant, ce qui entraîne des économies de tokens dans les workflows à plusieurs étapes.
• Aucun impact sur l'intelligence : la préservation des blocs de réflexion n'a aucun effet négatif sur les performances du modèle.

Le compromis est l'utilisation du contexte : les longues conversations consomment plus d'espace de contexte sur les modèles qui conservent tout, car les blocs de réflexion conservés comptent comme entrée au même titre que tout autre historique de conversation (voir Réflexion et fenêtre de contexte). Le comportement est automatique dans les deux régimes. Aucune modification de code ni en-tête bêta n'est requis, et vous devez continuer à renvoyer des blocs de réflexion complets et non modifiés comme décrit dans Préserver les blocs de réflexion. Pour remplacer la valeur par défaut dans l'une ou l'autre direction, utilisez l'effacement des blocs de réflexion.

Changer de modèle en milieu de conversation. Continuez à renvoyer les blocs de réflexion inchangés lorsque vous changez de modèle, par exemple après un repli sur refus de classificateur. Un bloc de réflexion n'est lisible que par le modèle qui l'a produit ou un plus récent, et l'API ignore ou supprime les blocs que le modèle cible ne peut pas lire. Sur Claude Fable 5.1 et Claude Mythos 5.1, la direction importe : ils lisent les blocs de réflexion de chaque modèle antérieur et aucun modèle antérieur ne lit les leurs, de sorte que passer à eux conserve le raisonnement de la conversation et redescendre le supprime (voir Réflexion préservée pour la liste exacte et pour la manière dont les blocs supprimés sont facturés et signalés). Supprimez vous-même les blocs thinking et redacted_thinking antérieurs uniquement pour économiser des tokens d'entrée sur les modèles qui les ignorent plutôt que de les supprimer, et jamais lors de l'utilisation d'un crédit de repli, qui nécessite que le corps reste inchangé.

Réflexion préservée

Claude préserve un bloc de réflexion, le gardant utilisable lors des tours ultérieurs, uniquement dans les conditions dans lesquelles il a été créé. À partir de Claude Fable 5.1 et Claude Mythos 5.1, un bloc thinking ou redacted_thinking n'est préservé que :

• Pour le modèle qui l'a produit, ou un plus récent. Un modèle antérieur ne peut pas utiliser le bloc, et l'API le supprime de cette requête. Voir Uniquement pour le modèle qui l'a produit, ou un plus récent.
• Dans la conversation qui l'a produit (Claude Fable 5.1 uniquement). Si l'invite système, les tools ou tout message antérieur change, le bloc n'est plus valide, et l'API rejette la requête ou supprime le bloc. Voir Uniquement dans la conversation qui l'a produit.

La signature du bloc enregistre les deux conditions sur les deux modèles. L'API la vérifie chaque fois que le bloc revient dans une requête ultérieure, y compris une requête vers un modèle différent ; Claude Mythos 5.1 ne vérifie que la condition du modèle.

Renvoyez les blocs inchangés. Envoyez chaque tour d'assistant exactement comme vous l'avez reçu, blocs de réflexion compris, et laissez l'API décider quels blocs le modèle peut utiliser.

Uniquement pour le modèle qui l'a produit, ou un plus récent

Cette condition est à sens unique : Claude Fable 5.1 et Claude Mythos 5.1 lisent les blocs de réflexion des modèles antérieurs, et aucun modèle antérieur ne lit les leurs.

• Une conversation qui passe à Claude Fable 5.1 ou Claude Mythos 5.1 conserve son raisonnement. Les blocs de réflexion du modèle antérieur restent lisibles, de sorte que le modèle réfléchit comme d'habitude dès le premier tour après le changement.
• Une conversation qui passe d'eux à un modèle antérieur le perd. Le modèle antérieur ne peut pas lire leurs blocs, l'API les supprime pour cette requête, et le modèle antérieur raisonne à nouveau à partir des messages visibles. Si la conversation revient plus tard à Claude Fable 5.1 avec le même historique, ses propres blocs sont à nouveau lisibles.

Au complet, Claude Fable 5.1 et Claude Mythos 5.1 lisent les blocs de réflexion produits l'un par l'autre, par Claude Opus 5, Claude Fable 5 et Claude Mythos 5, et par Claude Opus 4.8 et les modèles Opus antérieurs, les modèles Claude Sonnet et Claude Haiku 4.5. Aucun modèle autre que ces deux-là ne peut lire un bloc produit par Claude Fable 5.1 ou Claude Mythos 5.1.

Un bloc que le modèle récepteur ne peut pas lire est supprimé. L'API le supprime avant que le prompt n'atteigne le modèle. Il ne compte pas dans input_tokens et n'est pas facturé. Lorsque vous repliez de Claude Fable 5.1 vers un modèle plus ancien en milieu de conversation, par exemple après un repli sur refus de classificateur, le modèle plus ancien raisonne à nouveau à partir de la conversation visible. Avec l'en-tête bêta de contrôles, la suppression est signalée dans input_transformations comme model_binding_mismatch. Sans lui, la suppression est silencieuse. Un repli côté serveur supprime les blocs illisibles de la même manière.

Uniquement dans la conversation qui l'a produit

Un bloc de réflexion de Claude Fable 5.1 est préservé uniquement tant que le préfixe de conversation à partir duquel il a été produit reste inchangé. Sa signature couvre l'invite system, les tools, et les messages qui ont précédé le bloc. Claude Mythos 5.1 enregistre la même signature mais n'exécute pas cette vérification.

Cette vérification est appliquée pour les nouveaux comptes créés le 31 août 2026 ou après. Pour les comptes créés antérieurement, l'API enregistre la condition dans la signature mais n'agit pas en cas de non-correspondance, sauf si la requête définit thinking.block_binding.prefix_mismatch_behavior, ce qui active l'application. Anthropic prévoit d'appliquer cette condition à chaque organisation sur les futurs modèles. Si votre compte a été créé antérieurement, rendez votre application compatible dès maintenant : les mêmes modèles en ajout seul (append-only) maintiennent le cache de prompt chaud, et vous pouvez tester la vérification en envoyant prefix_mismatch_behavior: "error". Si vous livrez un outil ou un framework que les gens exécutent avec leur propre clé API, testez de cette manière : vos utilisateurs sur de nouveaux comptes sont soumis à l'application avant vous. La réflexion préservée contient la liste de contrôle d'intégration : comment déterminer si votre code modifie l'historique, et la fonctionnalité de l'API qui remplace chaque type de modification.

Là où la vérification est appliquée, une requête qui rejoue un bloc contre un préfixe modifié est rejetée avec une erreur 400 invalid_request_error :

messages.5.content.0: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block". That setting requires the `thinking-binding-controls-2026-08-01` value in the `anthropic-beta` header.

La dernière phrase n'apparaît que lorsque la requête n'a pas envoyé l'en-tête bêta. Le message peut se terminer par une phrase supplémentaire nommant le premier message qui a changé. Réessayer le même corps de requête échoue de la même manière. Pour continuer sans le raisonnement invalidé à la place, envoyez l'en-tête bêta thinking-binding-controls-2026-08-01 et définissez prefix_mismatch_behavior sur "drop_block". L'API supprime alors le bloc défaillant et chaque bloc de réflexion après lui dans la conversation, et signale chacun dans input_transformations comme prefix_binding_mismatch. Le point de terminaison de comptage de tokens exécute la même vérification et renvoie la même erreur 400.

Ce qui invalide les blocs de réflexion ultérieurs :

• Modifier, réorganiser ou supprimer un message antérieur, y compris supprimer un rappel par tour que vous avez injecté dans un tour utilisateur antérieur.
• Modifier le contenu de l'invite system de premier niveau, ou ajouter, supprimer ou modifier un outil dans le tableau tools, entre les requêtes.
• Une compaction ou troncature côté client qui conserve les tours d'assistant récents textuellement, réflexion incluse, tout en réécrivant les tours qui les précèdent.
• Une URL d'image ou de document dans un tour antérieur qui sert des octets différents lors d'une requête ultérieure. La vérification couvre les octets, pas la chaîne d'URL, donc une URL signée rotative pour le même fichier convient. Pour le contenu que vous référencez à travers les tours, téléversez-le une fois avec l'API Files et envoyez le file_id, ou envoyez du base64.

Ce qui ne l'invalide pas :

• Supprimer une série initiale de blocs de réflexion, du plus ancien au plus récent : le premier bloc de réflexion dans la conversation (ou le premier après le bloc de compaction le plus récent), puis le suivant, et ainsi de suite. Supprimer un bloc de réflexion de n'importe quel autre endroit invalide chaque bloc de réflexion après lui, dans ce tour et dans chaque tour ultérieur.
• Modifier output_config.effort, max_tokens, ou d'autres paramètres d'échantillonnage entre les requêtes.
• Les marqueurs cache_control, où que vous les placiez ou les déplaciez.
• La compaction côté serveur et l'édition de contexte : elles ne comptent pas comme des modifications, car la vérification compare la conversation telle que vous l'avez envoyée, et non la copie modifiée du serveur. Après une compaction, le préfixe vérifié commence à partir du bloc de compaction.

Modèles qui maintiennent les blocs de réflexion valides :

• Ajout seul. Ajoutez de nouveaux messages à la fin de messages et laissez les tours antérieurs inchangés octet par octet.
• Utilisez les messages système en milieu de conversation et les changements d'outils en milieu de conversation pour ajouter des instructions ou modifier la disponibilité des outils en cours de route, au lieu de modifier le champ system de premier niveau ou le tableau tools. Pour un rappel qui ne devrait s'appliquer qu'à un seul tour, envoyez-le comme un message système limité au tour et laissez-le dans l'historique plutôt que de le supprimer plus tard. Cela préserve également le cache de prompt.
• Utilisez la gestion de contexte côté serveur plutôt que de réduire l'historique vous-même.
• Si une requête est rejetée pour une non-correspondance de préfixe et que vous ne pouvez pas réparer l'historique, renvoyez-la avec l'en-tête bêta et prefix_mismatch_behavior: "drop_block", ou supprimez chaque bloc thinking et redacted_thinking de l'historique et réessayez une fois.

Lorsque la réflexion antérieure est supprimée, le modèle répond à ce tour sans ces blocs. Un client qui invalide à plusieurs reprises son propre historique redémarre le cache de prompt à chaque fois, ce qui augmente le coût.

Compaction côté client. Cette vérification n'exclut pas la compaction côté client. La règle est plus étroite : ne conservez pas un bloc de réflexion derrière un préfixe que vous avez réécrit. La compaction côté serveur est le moyen le plus simple de la satisfaire. Si vous compactez côté client, utilisez l'une de ces formes :

• Compaction simple (recommandée) : résumez la conversation en un seul message et commencez la requête suivante avec ce résumé plus le nouveau tour utilisateur, sans rejouer aucun tour antérieur ni aucun bloc de réflexion antérieur. Aucune réflexion antérieure ne subsiste, donc rien n'échoue, et le modèle réfléchit à nouveau sur la conversation compactée. Les modèles Claude sont entraînés sur des tâches à long horizon avec ce schéma, et il fonctionne de manière comparable à des schémas plus élaborés pour la plupart des charges de travail. Il réinitialise le cache de prompt, comme toute compaction.
• Compaction avec conservation de la fin : résumez les tours plus anciens et conservez les tours les plus récents textuellement. Les blocs de réflexion des tours conservés ont été produits contre l'historique complet et échouent derrière le résumé. Supprimez thinking et redacted_thinking de chaque tour que vous reportez (leur texte et leurs appels d'outils peuvent rester), ou définissez prefix_mismatch_behavior: "drop_block" et laissez l'API les écarter.
• Compaction en arrière-plan : construisez le résumé hors du chemin critique et échangez-le pendant que la conversation continue. Chaque tour produit entre-temps a une réflexion qui précède l'échange. Envoyez "drop_block" sur chaque requête qui porte encore des blocs de réflexion produits avant l'échange (ou supprimez ces blocs vous-même ; input_transformations sur la première réponse après l'échange liste exactement lesquels), ou compactez de manière synchrone.

Découper des tours individuels au milieu de la transcription invalide chaque bloc de réflexion après eux, et aucune forme côté client n'évite cela. Utilisez un message système en milieu de conversation pour le changement d'instruction que vous faisiez, ou l'édition de contexte côté serveur pour une suppression sélective.

Contrôles pour les blocs qui ne sont pas préservés (bêta)

Envoyez l'en-tête bêta thinking-binding-controls-2026-08-01 pour obtenir deux choses : un tableau input_transformations sur chaque réponse qui liste tous les blocs de réflexion que l'API a supprimés, et un objet block_binding sur la configuration de réflexion avec un champ.

block_binding est accepté aux côtés de thinking.type: "adaptive" et thinking.type: "enabled". L'envoyer sans l'en-tête bêta renvoie une erreur 400. Les modèles qui n'exécutent pas la vérification de conversation acceptent l'objet et ne signalent que les suppressions de vérification du modèle, donc un seul corps de requête fonctionne sur tous les modèles. Sur Amazon Bedrock et Google Cloud, passez les noms bêta comme décrit dans En-têtes bêta.

La requête suivante opte pour la suppression plutôt que le rejet. Lors d'un premier tour, il n'y a rien à rejouer, donc input_transformations revient vide :

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    thinking={
        "type": "adaptive",
        "block_binding": {"prefix_mismatch_behavior": "drop_block"},
    },
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
    betas=["thinking-binding-controls-2026-08-01"],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

print(f"Input transformations: {len(response.input_transformations or [])}")

The greatest common divisor of 1071 and 462 is 21.
Input transformations: 0

Les blocs supprimés sont signalés dans input_transformations. Sous l'en-tête bêta, chaque réponse d'un modèle capable de réflexion porte ce tableau de premier niveau. Il est vide lorsque rien n'a été supprimé et n'est jamais null. Chaque entrée nomme la position d'un bloc supprimé et la vérification qu'il a échouée :

{
  "input_transformations": [
    {
      "type": "thinking_dropped",
      "path": "messages.1.content.0",
      "reason": "model_binding_mismatch"
    }
  ]
}

Le champ reason est model_binding_mismatch ou prefix_binding_mismatch. Ignorez les entrées dont vous ne reconnaissez pas le type ou la reason, car les vérifications ultérieures ajoutent des valeurs. Lors du streaming, input_transformations arrive sur l'objet message dans l'événement message_start. Après un repli côté serveur en milieu de flux, l'événement final message_delta porte à nouveau le tableau avec les entrées du modèle de service. Sans l'en-tête bêta, le champ est absent.

Une signature altérée ou indéchiffrable est un échec différent : elle renvoie toujours une erreur 400 (Invalid `signature` in `thinking` block, sans clause de raison) et prefix_mismatch_behavior ne s'y applique pas. Dans un lot de messages, un élément dont le bloc échoue à la vérification de conversation sous "error" se résout comme errored.

Réflexion et mise en cache des prompts

La mise en cache des prompts interagit avec la réflexion de quelques manières spécifiques. Les règles suivantes s'appliquent dans les deux modes de réflexion.

Les changements de configuration invalident la mise en cache. La configuration de réflexion et le niveau d'effort résolu sont rendus dans l'invite elle-même, donc en changer l'un d'eux démarre un nouveau préfixe de cache. Basculer entre adaptive, enabled et disabled, changer budget_tokens, et changer la valeur d'effort invalident tous les points d'arrêt de cache : les points d'arrêt au niveau du message échouent toujours, et les points d'arrêt d'outils et d'invite système peuvent aussi échouer, selon l'endroit où le modèle rend la configuration. Traitez tout changement de réflexion ou d'effort de premier niveau comme un redémarrage du cache. Sur les modèles qui prennent en charge l'effort par message, un changement d'effort porté dans un message role: "system" à l'intérieur de messages laisse le préfixe mis en cache intact. Les requêtes consécutives qui conservent la même configuration préservent le cache, et définir un paramètre explicitement à sa valeur par défaut équivaut à l'omettre. Un bloc de réflexion que l'API supprime sous l'une ou l'autre condition de réflexion préservée change le préfixe mis en cache à partir de la position de ce bloc. Les blocs renvoyés inchangés maintiennent le cache intact. Une démonstration pratique avec sortie d'utilisation se trouve sur la page Orienter la réflexion.

Les blocs de réflexion sont mis en cache avec les résultats d'outils. Pendant une boucle d'utilisation d'outils, la mise en cache se produit lorsque vous faites une requête de suivi qui inclut des résultats d'outils. À ce moment-là, l'historique de conversation précédent, y compris ses blocs de réflexion, peut être mis en cache, et ces blocs de réflexion mis en cache comptent comme des tokens d'entrée dans vos métriques d'utilisation lorsqu'ils sont lus depuis le cache. Cela se produit automatiquement, même sans marqueurs cache_control explicites, et se comporte de la même manière pour la réflexion régulière et entrelacée. Le compromis : les blocs de réflexion que vous ne revoyez jamais dans les réponses contribuent toujours à l'utilisation des tokens d'entrée lorsqu'ils sont lus depuis le cache.

Le fait que les blocs antérieurs soient dans le contexte ou non dépend du modèle. La valeur par défaut de préservation régit cela. Sur les modèles qui conservent tout, les blocs de réflexion des tours précédents restent mis en cache et dans le contexte. Sur les modèles qui ne conservent que le dernier tour, une fois que vous envoyez un message utilisateur qui n'est pas un résultat d'outil, tous les blocs de réflexion précédents sont retirés du contexte. Sur ces modèles, une conversation comme celle-ci :

User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]

est traitée comme si les blocs de réflexion n'avaient jamais été là :

User: ["What's the weather in Paris?"],
Assistant: [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [text block 2],
User: [Text response, cache=True]

Sur les modèles qui conservent tout, la même requête conserve thinking_block_1 et thinking_block_2 dans le contexte et dans le cache.

La dégradation retire la réflexion de l'historique pouvant être mis en cache. Si la réflexion devient désactivée en milieu de tour et que vous passez du contenu de réflexion dans le tour d'utilisation d'outils actuel, le contenu de réflexion est retiré et la réflexion reste désactivée pour cette requête (voir dégradation gracieuse). La réflexion entrelacée amplifie les effets d'invalidation du cache, car les blocs de réflexion peuvent se produire entre plusieurs appels d'outils.

Réflexion et fenêtre de contexte

max_tokens, qui inclut toute la réflexion que Claude génère dans le tour actuel, est appliqué comme une limite stricte. Sur les modèles Claude 4.5 et plus récents, si les tokens d'entrée plus max_tokens dépassent la taille de la fenêtre de contexte, l'API accepte la requête. Si la génération atteint ensuite la limite de la fenêtre de contexte, elle s'arrête avec stop_reason: "model_context_window_exceeded" au lieu de renvoyer une erreur. Sur les modèles antérieurs, l'API renvoie une erreur de validation à la place. Voir Gestion des raisons d'arrêt.

La manière dont la réflexion compte dans la fenêtre dépend du moment où elle a été générée :

• La réflexion du tour actuel compte toujours dans max_tokens, est facturée comme des tokens de sortie, et occupe de l'espace dans la fenêtre de contexte pour le tour qui l'a générée.
• La réflexion des tours antérieurs dépend de la valeur par défaut de préservation. Sur les modèles qui conservent tous les tours antérieurs, les blocs de réflexion précédents restent dans le contexte, comptent dans la fenêtre, et sont facturés comme des tokens d'entrée comme le reste de l'historique de conversation. Sur les modèles qui ne conservent que le dernier tour, l'API retire automatiquement les blocs de réflexion plus anciens lorsque vous les renvoyez, donc ils ne consomment pas d'espace dans la fenêtre ni de tokens d'entrée.

En pratique :

• Sur les modèles qui conservent tout, budgétisez votre fenêtre de contexte comme si la réflexion était un historique de conversation ordinaire, car c'en est un. Les longues sessions agentiques accumulent de la réflexion dans le contexte. Utilisez l'effacement des blocs de réflexion si vous avez besoin de récupérer de l'espace.
• Sur les modèles qui ne conservent que le dernier tour, la réflexion est un coût par tour uniquement : la réflexion de chaque tour compte dans le max_tokens de ce tour puis sort de la fenêtre.

Les diagrammes suivants illustrent le régime de conservation du dernier tour uniquement (retrait). Le premier montre une conversation à plusieurs tours : le bloc de réflexion de chaque tour est généré dans la sortie mais n'est pas reporté dans l'entrée des tours ultérieurs.

Le second montre le même régime avec l'utilisation d'outils : la réflexion reste dans le contexte aux côtés de son résultat d'outil pendant la durée du tour d'assistant, puis sort au tour utilisateur suivant.

Utilisez l'API de comptage de tokens pour obtenir des comptes précis pour votre cas d'usage spécifique, en particulier pour les conversations à plusieurs tours qui incluent de la réflexion.

Chiffrement de la réflexion

Le contenu complet de la réflexion est chiffré et renvoyé dans le champ signature sur chaque bloc de réflexion. L'API utilise la signature pour vérifier que les blocs de réflexion ont été générés par Claude lorsque vous les renvoyez.

Gardez à l'esprit ce qui suit lorsque vous travaillez avec des signatures :

• Il n'est strictement nécessaire de renvoyer les blocs de réflexion que lors de l'utilisation d'outils avec la réflexion. Sinon, vous pouvez omettre les blocs de réflexion des tours précédents. Si vous les renvoyez, le fait que l'API les conserve ou les retire dépend du modèle (voir Préservation des blocs de réflexion par modèle). Utilisez l'édition de contexte pour configurer cela.
• Lors du renvoi des blocs de réflexion, renvoyez tout exactement comme vous l'avez reçu, pour la cohérence et pour éviter les problèmes potentiels.
• Lors du streaming des réponses, la signature arrive comme un signature_delta à l'intérieur d'un événement content_block_delta juste avant l'événement content_block_stop.
• Les valeurs de signature sont significativement plus longues dans les modèles Claude 4 et ultérieurs que dans les modèles précédents.
• Le champ signature est opaque : ne l'interprétez pas et ne l'analysez pas.
• Les valeurs de signature sont compatibles entre les plateformes (l'API Claude, Amazon Bedrock, et Google Cloud). Les valeurs générées sur une plateforme fonctionnent sur une autre.

Blocs de réflexion expurgés

En plus des blocs thinking réguliers, l'API peut renvoyer des blocs redacted_thinking lorsque des portions du raisonnement de Claude sont expurgées pour des raisons de sécurité. Un bloc redacted_thinking contient du contenu de réflexion chiffré dans un champ data, sans texte lisible :

{
  "type": "redacted_thinking",
  "data": "..."
}

Le champ data est opaque et chiffré. Comme le champ signature sur les blocs de réflexion réguliers, renvoyez les blocs redacted_thinking à l'API inchangés lors de la poursuite d'une conversation à plusieurs tours avec des outils.

Limites et compatibilité des fonctionnalités

Paramètres d'échantillonnage

Sur Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, et Claude Sonnet 5, les valeurs non par défaut de temperature, top_p, ou top_k renvoient une erreur 400 à chaque requête, que la réflexion soit utilisée ou non. Sur les modèles plus anciens, la restriction ne s'applique que lorsque la réflexion est activée : temperature et top_k sont incompatibles avec la réflexion, et top_p est autorisé à des valeurs entre 0,95 et 1.

Préremplissage de réponse et utilisation forcée d'outils

Vous ne pouvez pas préremplir la réponse de l'assistant lorsque la réflexion est activée. L'utilisation forcée d'outils (tool_choice: {"type": "any"} ou {"type": "tool", ...}) est incompatible avec la réflexion étendue manuelle mais fonctionne avec la réflexion adaptative. Les exceptions sont Claude Fable 5.1 et Claude Mythos 5.1, qui rejettent l'utilisation forcée d'outils à chaque requête avec une erreur 400. Sur ces modèles, utilisez tool_choice: {"type": "auto"} avec l'utilisation stricte d'outils ou les sorties structurées à la place. Voir Réflexion avec utilisation d'outils.

Limites de sortie

Chaque modèle accepte max_tokens jusqu'au plafond indiqué ici. Sur l'API Message Batches, l'en-tête bêta output-300k-2026-03-24 augmente ce plafond pour les modèles avec un plafond de lots indiqué.

Consultez l'aperçu des modèles pour les limites sur les modèles hérités.

Requêtes longues

Les SDK exigent le streaming lorsque max_tokens est supérieur à 21 333, pour éviter les délais d'expiration HTTP sur les requêtes de longue durée. Il s'agit d'une validation côté client, pas d'une restriction de l'API. Si vous n'avez pas besoin de traiter les événements de manière incrémentale, utilisez .stream() avec .get_final_message() (Python) ou .finalMessage() (TypeScript) pour obtenir l'objet Message complet sans gérer les événements individuels. Voir Streaming des messages. Attendez-vous à des temps de réponse plus longs lorsque la réflexion est active, car la génération de blocs de réflexion ajoute du temps de traitement. Pour les charges de travail qui poussent la réflexion au-dessus d'environ 32k tokens par requête, utilisez le traitement par lots pour éviter les problèmes de réseau : de telles requêtes peuvent s'exécuter suffisamment longtemps pour atteindre les délais d'expiration du système et les limites de connexions ouvertes.

Étapes suivantes