Réflexion

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-parcours. Pour une démonstration mathématique, un bug délicat ou une longue tâche agentique, la première approche n'est souvent pas la meilleure.

La réflexion lève cette contrainte. Lorsque la réflexion est active, Claude travaille sur le problème dans 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'appuie dessus 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, la programmation, 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 omis.

La réflexion a un coût : les tokens que Claude consacre au raisonnement sont facturés comme des tokens de sortie, même lorsque le texte de réflexion ne vous est pas retourné, et ils comptent dans max_tokens au même titre que le texte de réponse. Cette page explique comment la réflexion se comporte à travers la surface de l'API : l'activer, lire sa sortie et gérer ses interactions avec les outils, le streaming, la mise en cache et la fenêtre de contexte.



Fonctionnement de la réflexion

Le fait 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 comporte également un champ signature, une copie chiffrée du raisonnement complet que vous renvoyez inchangée dans les conversations multi-tours et avec 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 retourné ou non : "summarized" le retourne, tandis que "omitted", la valeur par défaut sur les modèles les plus récents, retourne 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, consultez la référence de l'API Messages.



Configurer la réflexion

Sur les modèles actuels, la réflexion est activée par défaut ou à un paramètre près. La configuration acceptée par chaque modèle, et sa valeur par défaut, est indiquée dans le tableau de configuration par modèle sur la page de dépannage.

Sur Claude Opus 5, Claude Sonnet 5, Claude Fable 5, Claude Mythos 5 et Claude Mythos Preview, la réflexion est déjà activée : aucune configuration n'est nécessaire. La première chose dont la plupart des développeurs ont besoin sur ces modèles est de voir le texte de réflexion, car display y est par défaut à "omitted". 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 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 niveau d'effort high ou inférieur. Aux niveaux d'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 retournent 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 des mesures d'atténuation par le prompt.

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 revient avec une erreur 400, Dépannage de la réflexion associe chaque message d'erreur à sa correction.



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 retourné dans les réponses de l'API. display fonctionne dans les deux modes : définissez-le avec type: "adaptive" ou type: "enabled". Il accepte deux 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 retournés avec un champ thinking vide. Le champ signature contient 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, Claude Mythos 5, Claude Opus 5, Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7 et Claude Mythos Preview.

Définissez display: "omitted" lorsque votre application n'affiche pas le contenu de réflexion aux utilisateurs. Le principal avantage est un temps plus rapide jusqu'au premier token de texte lors du streaming : le serveur saute entièrement le streaming des tokens de réflexion et ne livre 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 les points suivants lorsque vous travaillez avec la réflexion omise :

• Vous êtes toujours facturé pour l'intégralité 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 lors de 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).
• Lorsque vous utilisez thinking.type: "adaptive" et que le modèle saute la réflexion pour une requête simple, aucun bloc de réflexion n'est produit, quel que soit display.
• Lors du streaming avec display: "omitted", aucun événement thinking_delta n'est émis. Voir Streaming de la réflexion pour la séquence d'événements.

Dans le SDK Ruby, les hashes simples prennent display: comme le montrent les exemples. La classe typée ThinkingConfigAdaptive nomme le paramètre display_ (avec un underscore final, pour éviter de masquer Kernel#display de Ruby). Dans les deux cas, le champ transmis 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 prévenant les abus. Aucun paramètre display ne retourne la chaîne de pensée brute.

Gardez à l'esprit les points suivants lorsque vous travaillez avec la réflexion résumée :

• Vous êtes facturé pour l'intégralité des tokens de réflexion générés par la requête originale, pas 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 verbeuses, 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, donc ses blocs de réflexion ne montrent pas ce préambule verbeux.
• Le résumé 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 en streaming au fur et à mesure de leur arrivée.
• Le résumé est traité 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.
• Comme Anthropic cherche à améliorer la fonctionnalité de réflexion, le comportement de résumé est susceptible de changer.



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, 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'utilitaire d'accumulation de messages de votre SDK lorsqu'il existe (par exemple, stream.get_final_message() en Python ou stream.finalMessage() en TypeScript) au lieu de concaténer les deltas vous-même.

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 du 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":""}}

Pour les mécanismes généraux du streaming, voir Streaming des 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 d'effort : adaptive est un mode de réflexion, pas un niveau d'effort.

Pour 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 pris en charge par chaque modèle. 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 :

• Réduire le coût ou la latence sur une charge de travail avec réflexion activée : réduisez d'abord effort. Cela 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 de réflexion de Claude sur la page d'orientation.
• Vous avez besoin de désactiver complètement la réflexion : 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 indication souple. max_tokens est une limite stricte.



Réflexion avec utilisation d'outils

La réflexion fonctionne avec 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 d'outils forcée.
2. Préserver les blocs de réflexion : lorsque vous retournez des résultats d'outils, vous devez renvoyer les blocs de réflexion du message 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 fini 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 dernier tour d'assistant 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 tel bloc.

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 retour 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 conversation est incompatible avec la réflexion activée. 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 changez 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)

Basculer les 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 retournez le résultat de l'outil, Claude continue à construire cette même réponse, donc son raisonnement antérieur doit toujours être présent. Renvoyez chaque bloc thinking à l'API complet et non modifié, avec le bloc tool_use qu'il accompagnait. Cela est important 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 résumé :

• Obligatoire : dans un tour d'utilisation d'outils, renvoyez les blocs de réflexion.
• Recommandé : entre 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 l'ancienne réflexion vous-même. 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 qui sont 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.

Dans le dernier message 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 démonstration complète sur 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'outil, 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 dessus. 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 basées sur 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, 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 façon 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 des en-têtes spécifiques à chaque plateforme.

Avec la réflexion entrelacée, l'allocation de réflexion peut s'étendre sur l'ensemble du 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.



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

Le fait 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, 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 retirer vous-même.

La préservation apporte deux avantages :

• Optimisation du cache : les blocs de réflexion préservés permettent des correspondances de 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émentale tout au long du tour d'assistant, ce qui entraîne des économies de tokens dans les workflows multi-étapes.
• Aucun impact sur l'intelligence : préserver les 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 retenus 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. Aucun changement 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 cours de conversation. Lorsque vous passez d'un modèle à un autre, par exemple après un repli suite à un refus de classificateur, supprimez les blocs thinking et redacted_thinking des tours d'assistant précédents. Les blocs de réflexion sont liés au modèle qui les a produits. Les autres modèles les ignorent silencieusement plutôt que de rejeter la requête, mais les blocs ignorés ajoutent quand même des tokens d'entrée.



Réflexion et mise en cache des prompts

La mise en cache des prompts interagit avec la réflexion de plusieurs 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 le prompt lui-même, donc 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 des messages manquent toujours, et les points d'arrêt d'outils et d'invite système peuvent aussi manquer, selon l'endroit où le modèle rend la configuration. Considérez tout changement de réflexion ou d'effort comme un redémarrage du cache. Les requêtes consécutives qui conservent la même configuration préservent le cache, et définir explicitement un paramètre à sa valeur par défaut équivaut à l'omettre. Une démonstration détaillée 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 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 quand même à l'utilisation de tokens d'entrée lorsqu'ils sont lus depuis le cache.

Le fait que les blocs précédents soient dans le contexte 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 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 supprimé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 supprime 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 supprimé 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 apparaître 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 retourner une erreur. Sur les modèles antérieurs, l'API retourne une erreur de validation à la place. Voir Gestion des raisons d'arrêt.

La façon 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 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 précédents dépend de la valeur par défaut de préservation. Sur les modèles qui conservent tous les tours précédents, les blocs de réflexion précédents restent dans le contexte, comptent dans la fenêtre et sont facturés comme tokens d'entrée au même titre que le reste de l'historique de conversation. Sur les modèles qui ne conservent que le dernier tour, l'API supprime automatiquement les blocs de réflexion plus anciens lorsque vous les renvoyez, donc ils ne consomment pas d'espace de 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'est le cas. 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 schémas suivants illustrent le régime du dernier tour uniquement (suppression). Le premier montre une conversation multi-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 utilisation d'outils : la réflexion reste dans le contexte avec 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 comptages précis pour votre cas d'usage spécifique, en particulier pour les conversations multi-tours qui incluent de la réflexion.



Chiffrement de la réflexion

Le contenu complet de la réflexion est chiffré et retourné dans le champ signature de 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 les points suivants lorsque vous travaillez avec les 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 supprime dépend du modèle (voir Préservation des blocs de réflexion par modèle). Utilisez l'édition de contexte pour configurer cela.
• Lorsque vous renvoyez des blocs de réflexion, renvoyez tout exactement comme vous l'avez reçu, par souci de cohérence et pour éviter des problèmes potentiels.
• Lors du streaming des réponses, la signature arrive sous forme de signature_delta à l'intérieur d'un événement content_block_delta juste avant l'événement content_block_stop.
• Les valeurs 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 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 retourner 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 des blocs de réflexion réguliers, renvoyez les blocs redacted_thinking à l'API inchangés lorsque vous continuez une conversation multi-tours avec des outils.



Sortie de réflexion sur Claude Fable 5 et Claude Mythos 5

Sur Claude Fable 5 et Claude Mythos 5, la chaîne de pensée brute n'est jamais retournée. Les blocs que vous recevez sont des blocs thinking réguliers, pas redacted_thinking, et le paramètre display fonctionne de la même manière que sur les autres modèles (texte résumé, ou un champ thinking vide lorsqu'omis, la valeur par défaut ici). Pour la forme de réponse des blocs de réflexion, voir la référence de l'API Messages.

Lorsque vous continuez une conversation sur le même modèle, renvoyez chaque bloc de réflexion à l'API exactement comme reçu, y compris les blocs dont le champ thinking est vide. Ne les modifiez pas et ne les reconstruisez pas. Lire le texte du résumé pour l'affichage est acceptable : l'API rejette les blocs dont le contenu retourné a été modifié, pas les blocs que vous avez lus. Le texte placé dans un champ thinking omis vide est ignoré plutôt que rejeté.

Pour la façon dont les blocs de réflexion sont gérés lorsque vous changez de modèle en cours de conversation, voir Préservation des blocs de réflexion par modèle.

Deux exceptions, couvertes dans Crédit de repli :

• Les nouvelles tentatives avec crédit de repli doivent renvoyer le corps de la requête refusée inchangé.
• Les blocs fallback d'un repli en milieu de sortie restent là où ils sont apparus.

Pour obtenir une visibilité sur le raisonnement du modèle, lisez les blocs thinking décrits sur cette page plutôt que de demander le raisonnement dans le texte de réponse. Sur Claude Fable 5, une requête qui tente d'obtenir le raisonnement interne du modèle dans le texte de 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.



Limites et compatibilité des fonctionnalités

Paramètres d'échantillonnage. Sur 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 s'applique uniquement lorsque la réflexion est activée : temperature et top_k sont incompatibles avec la réflexion, et top_p est autorisé pour des valeurs comprises entre 0,95 et 1.

Préremplissage de la 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. Consultez Réflexion avec utilisation d'outils.

Limites de sortie. Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5, Claude Opus 4.6 et Claude Sonnet 4.6 prennent en charge jusqu'à 128k tokens de sortie par requête. Claude Haiku 4.5, Claude Sonnet 4.5 et Claude Opus 4.5 prennent en charge jusqu'à 64k. Sur l'API Message Batches, l'en-tête bêta output-300k-2026-03-24 porte la limite à 300k pour Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5, Claude Opus 4.6 et Claude Sonnet 4.6. Consultez la vue d'ensemble des modèles pour les limites des modèles hérités.

Requêtes longues. Les SDK exigent le streaming lorsque max_tokens est supérieur à 21 333, afin d'éviter les délais d'expiration HTTP sur les requêtes de longue durée. Il s'agit d'une validation côté client, et non d'une restriction de l'API. Si vous n'avez pas besoin de traiter les événements de manière incrémentielle, utilisez .stream() avec .get_final_message() (Python) ou .finalMessage() (TypeScript) pour obtenir l'objet Message complet sans gérer les événements individuels. Consultez Streaming de 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-delà d'environ 32k tokens par requête, utilisez le traitement par lots pour éviter les problèmes réseau : de telles requêtes peuvent s'exécuter suffisamment longtemps pour atteindre les délais d'expiration système et les limites de connexions ouvertes.



Étapes suivantes