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 en cours de route. 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 « thinking » (réflexion) supprime 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'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 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 renvoyé, et ils comptent dans max_tokens aux côtés du 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 « context window » (fenêtre de contexte).



Comment fonctionne la réflexion

Le fait que Claude réfléchisse ou non 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 reste 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 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 « chain of thought » (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 les modèles les plus récents, 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 ; consultez Contrôler l'affichage de la réflexion pour les valeurs par défaut par modèle et les détails.

Si Claude utilise des outils, la réflexion peut également apparaître entre les appels d'outils ; consultez 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 répertorié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, puisque display y vaut "omitted" par défaut. 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"} dans votre requête. Les exemples suivants le font, 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, définissez-le donc suffisamment haut pour laisser de la place à la fois à la réflexion et au texte de la réponse. Consultez Contrôle des coûts sur la page de pilotage 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 ; consultez Exécution avec la réflexion désactivée pour les mesures d'atténuation par 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 plutôt avec type: "enabled" et une valeur budget_tokens ; 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 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 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 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 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, 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'expose 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 livre que la signature, de sorte que la réponse textuelle finale commence à être transmise en streaming 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 les points suivants à l'esprit 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).
• Lors de l'utilisation de thinking.type: "adaptive" et lorsque 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 ; consultez Streaming de la réflexion pour la séquence d'événements.

Dans le SDK Ruby, définissez ce champ comme display_: (avec un trait de soulignement final) pour éviter de masquer Kernel#display de Ruby ; le champ transmis sur le réseau reste display.



Réflexion résumée

Lorsque display vaut "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 usages abusifs. Aucun réglage de display ne renvoie la chaîne de pensée brute.

Gardez les points suivants à l'esprit 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 détaillées, fournissant un raisonnement détaillé particulièrement utile à des fins de prompt engineering. Claude Mythos Preview résume dès le premier token, ses blocs de réflexion ne présentent donc 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 ajoutée minimale, permettant une expérience utilisateur compatible avec le streaming.
• 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.



Streaming de la réflexion

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

Les exemples suivants transmettent en streaming une réponse avec la 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)

Lorsque display: "omitted" est défini, le bloc de réflexion s'ouvre, un unique 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, consultez 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 d'effort : adaptive est un mode de réflexion, pas un niveau d'effort.

Pour savoir ce que chaque niveau d'effort fait au comportement de réflexion, consultez le tableau du comportement de réflexion par niveau sur la page Piloter 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 limité à la réflexion étendue qui prend en charge l'effort, l'effort se compose avec budget_tokens ; consultez Règles de budget et réglage.

Avec les deux contrôles ainsi séparés, 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 consultez Piloter la fréquence de réflexion de Claude sur la page de pilotage.
• 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 de pair avec l'utilisation d'outils, permettant à Claude de raisonner sur la sélection des outils et de traiter les résultats des 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.
2. Préservation des blocs de réflexion : lorsque vous renvoyez des résultats d'outils, vous devez renvoyer à l'API les blocs de réflexion du message de l'assistant, complets et non modifiés. Consultez Préserver les blocs de réflexion.

Une boucle d'utilisation d'outils constitue un seul tour d'assistant. Du point de vue du modèle, un tour d'assistant n'est pas terminé 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 constitue 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 en douceur. 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 renvoie 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 de ceux-ci. 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)

Notez que le basculement des modes de réflexion invalide également la mise en cache des prompts ; consultez 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, son raisonnement antérieur doit donc 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 poursuivre son raisonnement 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 :

• Obligatoire : au sein d'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 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 ne facture les tokens d'entrée que pour les blocs réellement montrés à Claude. Les blocs des tours précédents qui sont conservés dépendent du modèle ; consultez 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 en supprimer une partie. Cela inclut les blocs redacted_thinking.

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



Réflexion entrelacée

La « interleaved thinking » (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 tous les modèles qui prennent 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 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 des en-têtes spécifique à 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 flux de travail à deux outils, consultez 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 :

• Conservation de 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.
• Conservation du dernier tour uniquement : les modèles Opus et Sonnet antérieurs, et tous les modèles Haiku jusqu'à Claude Haiku 4.5 inclus. 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 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émentale tout au long du tour d'assistant, ce qui entraîne des économies de tokens dans les flux de travail en 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, puisque les blocs de réflexion conservés comptent comme de l'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 un sens ou dans l'autre, utilisez l'effacement des blocs de réflexion.

Changement de modèle en cours de conversation. Lorsque vous basculez entre deux modèles quelconques, par exemple après un repli suite à un refus du 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 tout de même des tokens d'entrée.



Réflexion et mise en cache des prompts

La « prompt caching » (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 le prompt lui-même, donc modifier l'un d'eux démarre un nouveau préfixe de cache. Basculer entre adaptive, enabled et disabled, modifier budget_tokens et modifier la valeur d'effort invalident tous les points de rupture du cache : les points de rupture au niveau des messages échouent toujours, et les points de rupture des outils et de l'invite système peuvent également échouer, 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 la sortie d'utilisation se trouve sur la page Piloter 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 effectuez 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 tout de même à l'utilisation de tokens d'entrée lorsqu'ils sont lus depuis le cache.

La présence ou non des blocs précédents 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, dès 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 existé :

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 garde 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 est désactivée en milieu de tour et que vous transmettez du contenu de réflexion dans le tour d'utilisation d'outils en cours, le contenu de réflexion est supprimé et la réflexion reste désactivée pour cette requête (voir dégradation en douceur). La réflexion entrelacée amplifie les effets d'invalidation du cache, puisque 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 en cours, 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 plutôt une erreur de validation. Consultez 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 en cours 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 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 des 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, ils ne consomment donc ni espace de fenêtre ni tokens d'entrée.

En pratique :

• Sur les modèles qui conservent tout, budgétez 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 devez récupérer de l'espace.
• Sur les modèles qui ne conservent que le dernier tour, la réflexion n'est qu'un coût par tour : 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 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 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 disparaît au tour utilisateur suivant.

Utilisez l'API de comptage de tokens pour obtenir des comptages précis pour votre cas d'utilisation 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 renvoyé 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 les points suivants à l'esprit 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 de signature sont nettement plus longues dans Claude 4 et les modèles 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 (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 des blocs de réflexion réguliers, renvoyez les blocs redacted_thinking à l'API inchangés lorsque vous poursuivez 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 renvoyée ; les blocs que vous recevez sont des blocs thinking réguliers, pas des redacted_thinking, et le réglage display fonctionne de la même manière que sur les autres modèles (texte résumé, ou un champ thinking vide lorsqu'il est omis, la valeur par défaut ici). Pour la forme de réponse des blocs de réflexion, consultez la référence de l'API Messages.

Lorsque vous poursuivez une conversation sur le même modèle, renvoyez chaque bloc de réflexion à l'API exactement tel que 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'afficher ne pose pas de problème : l'API rejette les blocs dont le contenu renvoyé a été modifié, pas les blocs que vous avez lus. Le texte placé dans un champ thinking vide d'un bloc omis est ignoré plutôt que rejeté.

Pour savoir ce qu'il advient des blocs de réflexion lorsque vous changez de modèle en cours de conversation, consultez 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 issus d'un repli en cours 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 la réponse via un prompt. Sur Claude Fable 5, une requête qui tente d'obtenir le raisonnement interne du modèle dans le texte de la réponse peut être refusée avec stop_details.category: "reasoning_extraction". Consultez 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 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é pour des valeurs comprises entre 0,95 et 1.

Préremplissage de la réponse et utilisation d'outils forcée. Vous ne pouvez pas préremplir la réponse de l'assistant lorsque la réflexion est activée. L'utilisation d'outils forcée (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 l'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émentale, 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 des 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 de réseau : de telles requêtes peuvent durer suffisamment longtemps pour atteindre les délais d'expiration du système et les limites de connexions ouvertes.



Prochaines étapes