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-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.

Le « thinking » (réflexion) lève cette contrainte. Lorsque la réflexion est active, Claude travaille 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. Cette réflexion préalable 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 les tâches complexes comme les mathématiques, le code, 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 sinon 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

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 préalable 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 comporte également un champ signature, une copie chiffrée du raisonnement complet que vous renvoyez sans modification 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 détermine 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. 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 la plupart des modèles, la réflexion est activée par défaut ou à un paramètre près. Le tableau suivant indique ce que fait chaque modèle avec chaque valeur thinking qu'une requête peut envoyer. Une erreur 400 signifie que l'API rejette la requête, et Dépannage de la réflexion présente chaque erreur et sa correction.

Dans le tableau, « à l'effort high ou inférieur » signifie que la requête fonctionne avec un effort low, medium et high, et renvoie une erreur 400 avec xhigh ou max.

Sur Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Sonnet 5, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview et Claude Haiku 5.5, la réflexion est déjà activée et ne nécessite aucune configuration. display vaut "omitted" par défaut sur ces modèles, de sorte que le texte de réflexion est masqué jusqu'à ce que vous l'activiez. Activez-le avec thinking: {"type": "adaptive", "display": "summarized"}, comme le font les exemples suivants.

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éterminer quand et avec quelle profondeur réfléchir en fonction de la requête. La même requête, avec la chaîne de modèle remplacée, l'active sur ces modèles. Les exemples suivants définissent display: "summarized" pour que le texte de réflexion soit visible, et utilisent une valeur max_tokens généreuse :

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    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:
    match block.type:
        case "thinking":
            print(f"\nThinking: {block.thinking}")
        case "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 sont comptabilisés dans max_tokens ; définissez donc une valeur suffisamment élevée 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 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"} avec un effort high ou inférieur. Avec 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 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 au niveau du prompt.

Claude Sonnet 5.5 a également la réflexion activée par défaut, et il rejette thinking: {type: "disabled"} avec une erreur 400. Pour désactiver la réflexion préalable, envoyez plutôt thinking: {type: "between_tools"}. C'est le réglage de réflexion le plus bas sur Claude Sonnet 5.5, et il est accepté avec un effort high ou inférieur. Le modèle renvoie toujours ses mises à jour de progression entre les appels d'outils. Sans outils, la réponse ne contient que du texte, comme avec disabled sur Claude Sonnet 5. Consultez Exécution sans réflexion préalable pour des conseils de prompting.

Claude Haiku 5.5 a également la réflexion activée par défaut et accepte thinking: {type: "disabled"} avec un effort high ou inférieur. Avec un effort xhigh ou max, cette combinaison renvoie une erreur 400. Pour obtenir moins de réflexion, abaissez d'abord le niveau d'effort. Avec la réflexion désactivée, le modèle peut omettre un appel d'outil dont il a besoin lorsque vous demandez également une sortie JSON. Un output_config.effort par message qui diffère du niveau en vigueur renvoie également une erreur 400 lorsque la réflexion est désactivée. Consultez Utiliser l'effort pour contrôler la réflexion et Utiliser la réflexion adaptative avec une sortie JSON et vos propres outils.

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

Pour vérifier si un modèle accepte "disabled" avant d'envoyer une requête, lisez sa valeur capabilities.thinking.types.disabled.supported depuis l'API Models. Utiliser l'API Models décrit ce champ.

Si votre modèle ne prend en charge que la réflexion étendue (voir le tableau de configuration par modèle), configurez-le 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 avec type: "adaptive" ou type: "enabled". Il accepte les valeurs suivantes :

• "summarized" : les blocs de réflexion contiennent un 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 contient toujours la réflexion complète chiffrée pour assurer 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.5, Claude Opus 5, Claude Sonnet 5.5, Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7, Claude Mythos Preview et Claude Haiku 5.5.
• "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 sont renvoyées 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 n'affiche pas le contenu de réflexion aux utilisateurs. Le principal avantage est un délai plus court avant le premier token de texte lors du streaming : le serveur ignore entièrement le streaming des tokens de réflexion et ne transmet 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 les points suivants à l'esprit lorsque vous travaillez avec une 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 sans modification. Le serveur déchiffre la signature pour reconstruire la réflexion d'origine 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 n'est pas valide avec thinking.type: "disabled" (il n'y a rien à afficher) ni avec thinking.type: "between_tools" (Claude Sonnet 5.5 uniquement), qui n'accepte aucun autre champ. Avec between_tools, les mises à jour de progression sont toujours renvoyées avec un texte de résumé, comme sous display: "updates" (voir Mises à jour de progression).
• Lorsque vous utilisez thinking.type: "adaptive" et que le modèle ne réfléchit pas 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 texte de réflexion n'est diffusé. Chaque bloc de réflexion diffuse un thinking_delta avec une chaîne thinking vide, puis son signature_delta. Avec display: "updates", seuls les blocs de mise à jour de progression diffusent des événements thinking_delta contenant du texte. Consultez Streaming de la réflexion pour la séquence d'événements.

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 de la réflexion en matière d'intelligence tout en empêchant les abus. Aucun réglage de display ne renvoie la chaîne de pensée brute.

Gardez les points suivants à l'esprit lorsque vous travaillez avec une 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 d'origine, 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 approfondi particulièrement utile pour le « prompt engineering » (ingénierie de prompts). Claude Mythos Preview résume dès le premier token, de sorte que ses blocs de réflexion ne présentent 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.
• La synthèse est effectué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.
• Comme Anthropic cherche à améliorer la fonctionnalité de réflexion, le comportement de la synthèse est susceptible d'évoluer.

Pour voir le raisonnement du modèle, lisez les blocs thinking plutôt que de demander un raisonnement dans le texte de la réponse. Sur Claude Fable 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5 et 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 Conserver le raisonnement dans les blocs de réflexion pour savoir quoi demander à la place.

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 unique événement signature_delta juste avant le content_block_stop du bloc. Les blocs de texte sont ensuite diffusés 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-5-5",
    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:
        match event.type:
            case "content_block_start":
                print(f"\nStarting {event.content_block.type} block...")
            case "content_block_delta":
                delta = event.delta
                match delta.type:
                    case "thinking_delta":
                        print(delta.thinking, end="", flush=True)
                    case "text_delta":
                        print(delta.text, end="", flush=True)

Pour reconstituer des blocs de réflexion complets avec leurs signatures après le streaming, utilisez l'utilitaire d'accumulation de messages de votre SDK, stream.get_final_message(), au lieu de concaténer vous-même les deltas.

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-5-5", "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 thinking_delta avec une chaîne thinking vide arrive, un unique signature_delta suit, et le bloc se ferme. 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":"thinking_delta","thinking":""}}

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 avec "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":{}}}

Avec "updates", considérez un bloc comme une mise à jour de progression dès que l'un de ses événements thinking_delta contient du texte non vide.

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 de effort : adaptive est un mode de réflexion, et non un niveau d'effort.

Pour savoir ce que chaque niveau d'effort change au comportement de réflexion, consultez le tableau du 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 combine avec budget_tokens. Consultez Règles et ajustement du budget.

Les deux contrôles étant ainsi séparés, choisissez celui qui correspond à votre objectif :

• Réduire le coût ou la latence d'une charge de travail avec réflexion activée : baissez 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 consultez 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). Claude Sonnet 5.5 rejette "disabled". Son réglage le plus bas est thinking: {type: "between_tools"}, qui désactive la réflexion préalable.
• Vous avez besoin d'un plafond strict de 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 conjointement avec l'utilisation d'outils, permettant à Claude de raisonner sur le choix 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, sauf sur Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 et Claude Mythos 5.1 (voir Préremplissage de la réponse et utilisation forcée d'outils). Lorsque l'utilisation forcée d'outils est acceptée, la réponse commence par l'appel d'outil et ne contient aucun bloc thinking.
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 de l'assistant. Du point de vue du modèle, un tour de l'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 constitue un seul tour de l'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"]

L'ensemble du tour s'exécute dans un seul mode de réflexion : vous ne pouvez pas activer ou désactiver 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 de l'assistant d'une requête avec réflexion activée commence par un bloc de réflexion. Le mode adaptatif assouplit cette règle : aucun tour de l'assistant n'a besoin de commencer par un tel bloc.

Les conflits en milieu de tour sont gérés en douceur. Si vous activez ou désactivez 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. Elle désactive plutôt 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 de l'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 changement de mode 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, 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

L'« 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éterminer la suite
• 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.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.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 modifie la façon dont le budget de réflexion est comptabilisé. Réflexion entrelacée en mode manuel couvre les règles par modèle et le comportement des en-têtes propre à chaque plateforme.

Avec la réflexion entrelacée, l'allocation de réflexion peut couvrir l'ensemble du tour de l'assistant plutôt qu'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, consultez Comment la réflexion entrelacée modifie le flux.

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

Sur Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5 et Claude Fable 5, le modèle peut écrire une « progress update » (mise à jour de progression) entre les appels d'outils. Une mise à jour de progression est une note sur ce que le modèle vient de trouver et sur ce qu'il s'apprête à faire ensuite, rédigée pour la personne qui observe l'agent plutôt que comme un raisonnement. Chacune est renvoyée dans son propre bloc thinking avec sa propre signature, distinct de tout bloc de raisonnement au même endroit. Elle se place 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 omettre n'importe laquelle d'entre elles. 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.

Le contenu d'un bloc de mise à jour de progression dépend de display :

Sur Claude Sonnet 5.5, le réglage de réflexion le plus bas est thinking: {type: "between_tools"}. Il désactive la réflexion préalable, et chaque mise à jour de progression est renvoyée avec son texte de résumé, comme elle le serait avec display: "updates". between_tools n'est accepté qu'avec un effort high ou inférieur. Avec xhigh ou max, une requête qui l'utilise renvoie une erreur 400. between_tools n'accepte aucun autre champ : display, budget_tokens ou block_binding envoyé avec lui renvoie une erreur 400. Ce réglage ne nécessite aucun en-tête bêta et fonctionne sur toutes les plateformes qui proposent Claude Sonnet 5.5. Renvoyez les blocs sans modification : un bloc de mise à jour de progression que vous renvoyez fournit au modèle la note complète qu'il a écrite, et non le résumé.

Utilisez display: "updates" pour une interface d'agent qui garde le raisonnement masqué et affiche à l'utilisateur une ligne d'état à chaque étape. Avec ce réglage, tout bloc thinking contenant du texte non vide est une mise à jour de progression ; affichez donc ces blocs et rien d'autre. Ce réglage est en bêta et nécessite l'en-tête bêta thinking-display-updates-2026-08-18 (pour l'envoyer sur Amazon Bedrock, Google Cloud ou Microsoft Foundry, consultez Fonctionnalités bêta sur d'autres plateformes). Sans cet en-tête, 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."
    }
  ]
}

Avec "updates", le début de la réponse qui suit un tool_result ressemble à ceci. Le premier bloc est un raisonnement et reste vide, comme il le serait avec "omitted". Le second contient du texte ; il s'agit donc d'une mise à jour de progression. Avec "summarized", les deux blocs contiennent du texte, et avec "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 les points suivants à l'esprit lorsque vous travaillez avec des mises à jour de progression :

• Renvoyez les blocs de mise à jour de progression sans modification avec le reste du tour de l'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 est comptabilisée dans usage.output_tokens pour sa longueur complète, et non pour celle du résumé.
• Un bloc de mise à jour de progression peut être renvoyé avec un champ thinking vide, quelle que soit la valeur de display. N'affichez rien pour un bloc vide. Avec "updates", il ressemble à un bloc de raisonnement vide et ne nécessite aucun traitement particulier.
• 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 qui remplace le travail que le modèle n'avait pas terminé. Avec "updates" et "summarized", son texte est exactement This part of the response was interrupted before it finished. et vous pouvez l'afficher comme n'importe quelle autre mise à jour. Avec "omitted", il est vide. Pour continuer, renvoyez le tour de l'assistant sans modification 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. Consultez la trace "updates" dans Streaming de la réflexion.
• Ces modèles écrivent moins de mises à jour de progression avec un effort plus élevé et dans les longues chaînes d'outils. Si votre interface en dépend, consultez Demander des mises à jour de progression destinées à l'utilisateur ou, pour Claude Opus 5.5, Mises à jour de progression destinées à l'utilisateur. Pour Claude Sonnet 5.5, consultez Mises à jour de progression destinées à l'utilisateur.

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

Le fait que les blocs de réflexion des tours précédents de l'assistant 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 Haiku 5.5, 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, ainsi que 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 succès 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 de l'assistant, ce qui permet d'économiser des 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.

La contrepartie est l'utilisation du contexte : les longues conversations consomment davantage d'espace de contexte sur les modèles qui conservent tout, car les blocs de réflexion conservés comptent comme entrée, comme 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 aucun 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 le comportement par défaut dans un sens ou dans l'autre, utilisez l'effacement des blocs de réflexion.

Changer de modèle en cours de conversation. Continuez à renvoyer les blocs de réflexion sans modification lorsque vous changez de modèle, par exemple après un repli suite à un refus du classificateur. Un bloc de réflexion n'est lisible que par le modèle qui l'a produit et par certains autres modèles, 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, le sens compte : ils lisent les blocs de réflexion des modèles antérieurs, et seuls ces deux modèles lisent les blocs l'un de l'autre, de sorte que passer à l'un d'eux conserve le raisonnement de la conversation, tandis que passer de l'un d'eux à tout autre modèle le supprime (voir comment les blocs supprimés sont facturés et signalés). Claude Opus 5.5 lit les blocs de réflexion de Claude Opus 5 et ceux des modèles Opus, Sonnet et Haiku antérieurs, ainsi que, sur la Claude API et Google Cloud, ceux de Claude Haiku 5.5, mais pas ceux des modèles Claude Fable et Claude Mythos ; sur la Claude API, Claude Fable 5.1 et Claude Mythos 5.1 lisent les blocs de Claude Opus 5.5. Un passage de Claude Opus 5.5 à Claude Fable 5.1 sur la Claude API conserve le raisonnement des tours précédents ; un passage de Claude Fable 5.1 à Claude Opus 5.5 le supprime. Claude Sonnet 5.5 lit les blocs de réflexion de Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5 et des modèles antérieurs, ainsi que, sur la Claude API et Google Cloud, ceux de Claude Haiku 5.5, mais pas ceux de Claude Opus 5, Claude Opus 5.5 ni d'aucun modèle Claude Fable ou Claude Mythos. Sur la Claude API et Google Cloud, Claude Opus 5.5 lit les blocs de Claude Sonnet 5.5 et aucun autre modèle ne le fait : un passage de Claude Sonnet 5.5 à Claude Opus 5.5 sur la Claude API et Google Cloud conserve le raisonnement des tours précédents, et tout autre changement depuis Claude Sonnet 5.5 le supprime. Claude Haiku 5.5 lit les blocs de réflexion de Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5 et des modèles antérieurs, mais pas ceux de Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5 ni d'aucun modèle Claude Fable ou Claude Mythos. Sur la Claude API et Google Cloud, Claude Opus 5.5 et Claude Sonnet 5.5 lisent les blocs de Claude Haiku 5.5 et aucun autre modèle ne le fait. Ne retirez vous-même les blocs thinking et redacted_thinking précédents que pour économiser des tokens d'entrée sur les modèles qui les ignorent plutôt que de les supprimer, et jamais lorsque vous utilisez un crédit de repli, qui exige que le corps de la requête reste inchangé.

Réflexion préservée

La réflexion préservée détermine si le modèle peut utiliser un bloc de réflexion que vous renvoyez depuis un tour précédent. À partir de Claude Fable 5.1, l'API vérifie la signature de chaque bloc thinking ou redacted_thinking d'une requête sur deux points :

• Le modèle qui l'a produit. Chaque modèle lit ses propres blocs de réflexion et ceux d'un ensemble fixe d'autres modèles. Claude Fable 5.1 lit les blocs de Claude Opus 5 et, sur la Claude API, de Claude Opus 5.5 ; ni Claude Opus 5 ni Claude Opus 5.5 ne lisent les blocs de Claude Fable 5.1. L'API supprime un bloc que le modèle actuel ne peut pas lire, sans erreur et sans le facturer. Voir Changer de modèle en cours de conversation.
• Tout ce qui a été envoyé avant lui. Un bloc ne reste valide que tant que l'invite system de niveau supérieur, les tools et les messages qui le précèdent restent inchangés. Si l'un d'eux change, ce bloc et tous les blocs de réflexion ultérieurs deviennent invalides, et l'API rejette la requête avec une erreur 400 ou supprime les blocs invalides, selon votre choix. Voir Conserver le préfixe inchangé.

Les blocs de réflexion de Claude Sonnet 5.5 et de Claude Haiku 5.5 sont également liés au compte qui les a produits. Consultez Les blocs de réflexion restent liés au compte qui les a produits pour savoir où l'API applique cette règle.

La vérification du modèle s'applique à tous les comptes. L'API applique la vérification du préfixe par défaut pour les comptes créés le 31 août 2026 à 00:00 UTC ou après. Sur les comptes plus anciens, elle n'applique la vérification qu'aux requêtes qui définissent thinking.block_binding.prefix_mismatch_behavior. Rendez votre intégration « append-only » (en ajout seul) quel que soit l'âge de votre compte, afin que le même code fonctionne sur tous les comptes, y compris les comptes plus récents soumis à la vérification par défaut.

Pour que la réflexion reste valide, renvoyez chaque tour de l'assistant exactement tel que vous l'avez reçu et ajoutez les nouveaux messages uniquement à la fin de messages. Si votre code construit lui-même le tableau messages, la page Réflexion préservée couvre :

• Ce qui compte comme une modification, et comment vérifier si votre code en effectue une.
• La fonctionnalité de l'API qui remplace chaque modification courante : les messages système en cours de conversation pour les nouvelles instructions et les rappels par tour, les blocs tool_addition et tool_removal pour les changements d'outils, output_config par message pour les changements d'effort, ainsi que la compaction côté serveur et l'édition du contexte pour l'élagage.
• La compaction côté client : quels modèles de conception conservent la validité de la réflexion et lesquels ne la conservent pas.
• L'en-tête bêta thinking-binding-controls-2026-08-01. Il ajoute un champ block_binding.prefix_mismatch_behavior ("error" ou "drop_block") à la configuration de la réflexion et un tableau input_transformations à chaque réponse. Ce tableau répertorie chaque bloc de réflexion que l'API a supprimé, ou qui a échoué à la vérification du préfixe et a été laissé passer.

Réflexion et mise en cache des prompts

La « prompt caching » (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 la réflexion et le niveau d'effort résolu sont intégrés au prompt lui-même, de sorte que 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 d'arrêt du cache : les points d'arrêt au niveau des messages échouent toujours, et les points d'arrêt des outils et de l'invite système peuvent également échouer, selon l'endroit où le modèle intègre la configuration. Considérez tout changement de réflexion ou d'effort de niveau supérieur comme un redémarrage du cache. Sur les modèles qui prennent en charge l'effort par message, un changement d'effort transmis 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 explicitement un paramètre à sa valeur par défaut équivaut à l'omettre. Un bloc de réflexion que l'API supprime en vertu de l'une des conditions de réflexion préservée modifie le préfixe mis en cache à partir de la position de ce bloc. Les blocs renvoyés sans modification conservent le cache intact. Une démonstration détaillée avec la 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 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 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 normale et entrelacée. La contrepartie : les blocs de réflexion que vous ne revoyez jamais dans les réponses contribuent tout de même à l'utilisation des tokens d'entrée lorsqu'ils sont lus depuis le cache.

La présence même des blocs précédents dans le contexte dépend du modèle. Le comportement de préservation par défaut régit ce point. 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 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é présents :

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 est désactivée en cours de tour et que vous transmettez 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 progressive). La réflexion entrelacée amplifie les effets d'invalidation du cache, car des 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 générée par Claude au cours du 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 « context window » (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. Voir Gérer les raisons d'arrêt.

La manière dont la réflexion est comptabilisée 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 du comportement de préservation par défaut. 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, 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, de sorte qu'ils ne consomment ni espace dans la fenêtre ni tokens d'entrée.

En pratique :

• Sur les modèles qui conservent tout, planifiez 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 de conservation du dernier tour uniquement (suppression). Le premier montre une conversation à plusieurs tours : le « thinking block » (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 suivants.

Le second montre le même régime avec la « tool use » (utilisation d'outils) : le « thinking block » (bloc de réflexion) reste dans le contexte avec son « tool result » (résultat d'outil) pendant toute la durée du tour de l'assistant, puis en sort au tour utilisateur suivant.

Utilisez l'API de comptage des tokens pour obtenir des dé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 (la Claude API, Amazon Bedrock et Google Cloud). Les valeurs générées sur une plateforme fonctionnent sur une autre, sauf que les blocs de réflexion de Claude Sonnet 5.5 et Claude Haiku 5.5 ne fonctionnent que dans le compte qui les a produits ou dans un compte qui lui est lié. Voir Les blocs de réflexion restent liés au compte qui les a produits.

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.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5.5, Claude Sonnet 5 et Claude Haiku 5.5, des valeurs non par défaut de temperature, top_p ou top_k renvoient une erreur 400 sur chaque requête, que la réflexion soit utilisée ou non. Sur ces modèles, la valeur par défaut de top_p est 0.99, de sorte qu'un top_p de 1 renvoie une erreur 400, tout comme une requête qui inclut à la fois temperature et top_p, même à leurs valeurs par défaut. Voir Supprimer les paramètres d'échantillonnage. 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 comprises entre 0,95 et 1.

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

Les modèles Claude 4.6 et ultérieurs ainsi que Claude Mythos Preview rejettent un tour final de l'assistant prérempli avec une erreur 400, que la réflexion soit activée ou non (voir Préremplissage non pris en charge). Sur les modèles antérieurs, 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 Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 et Claude Mythos 5.1, qui rejettent l'utilisation forcée d'outils sur chaque requête avec une erreur 400. Sur ces modèles, utilisez plutôt tool_choice: {"type": "auto"} avec l'utilisation d'outils stricte ou les sorties structurées. Lorsque l'utilisation forcée d'outils est acceptée, la réponse commence par l'appel d'outil et ne contient aucun bloc thinking. Pour permettre au modèle de réfléchir avant d'appeler un outil, utilisez tool_choice: {"type": "auto"} et indiquez dans le prompt quand utiliser l'outil. 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

Le SDK exige 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() pour obtenir l'objet Message complet sans avoir à l'assembler vous-même à partir des événements individuels. Voir 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 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.

Étapes suivantes