Construire avec la réflexion étendue

La réflexion étendue donne à Claude des capacités de raisonnement améliorées pour les tâches complexes, tout en fournissant différents niveaux de transparence dans son processus de réflexion étape par étape avant de livrer sa réponse finale.

Modèles pris en charge

La réflexion étendue manuelle (thinking: {type: "enabled", budget_tokens: N}) est prise en charge sur tous les modèles Claude actuels sauf Claude Opus 4.7 et les modèles ultérieurs, où elle n'est plus acceptée et retourne une erreur 400. Quelques modèles ont un comportement spécifique au mode :

• Claude Opus 4.7 (claude-opus-4-7) et modèles ultérieurs : la réflexion étendue manuelle n'est plus prise en charge. Utilisez plutôt la réflexion adaptative (thinking: {type: "adaptive"}) avec le paramètre d'effort.
• Claude Mythos Preview : la réflexion adaptative est la valeur par défaut ; thinking: {type: "enabled", budget_tokens: N} est également accepté. thinking: {type: "disabled"} n'est pas pris en charge, et display prend par défaut la valeur "omitted" plutôt que de retourner le contenu de la réflexion. Passez display: "summarized" pour recevoir des résumés.
• Claude Opus 4.6 (claude-opus-4-6) : la réflexion adaptative est recommandée ; le mode manuel (type: "enabled") est déprécié mais toujours fonctionnel.
• Claude Sonnet 4.6 (claude-sonnet-4-6) : la réflexion adaptative est recommandée ; le mode manuel (type: "enabled") avec le mode entrelacé est déprécié mais toujours fonctionnel.

Comment fonctionne la réflexion étendue

Lorsque la réflexion étendue est activée, Claude crée des blocs de contenu thinking où il produit son raisonnement interne. Claude intègre les insights de ce raisonnement avant de formuler une réponse finale.

La réponse de l'API inclut les blocs de contenu thinking, suivis des blocs de contenu text.

Voici un exemple du format de réponse par défaut :

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me analyze this step by step...",
      "signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
    },
    {
      "type": "text",
      "text": "Based on my analysis..."
    }
  ]
}

Pour plus d'informations sur le format de réponse de la réflexion étendue, consultez la Référence de l'API Messages.

Comment utiliser la réflexion étendue

Voici un exemple d'utilisation de la réflexion étendue dans l'API Messages :

Pour activer la réflexion étendue, ajoutez un objet thinking, avec le paramètre type défini sur enabled et le budget_tokens défini sur un budget de tokens spécifié pour la réflexion étendue. Pour Claude Opus 4.6 et Claude Sonnet 4.6, utilisez plutôt type: "adaptive". Consultez Réflexion adaptative pour plus de détails. Bien que type: "enabled" avec budget_tokens soit toujours fonctionnel sur ces modèles, il est déprécié et sera supprimé dans une future version.

Le paramètre budget_tokens détermine le nombre maximum de tokens que Claude est autorisé à utiliser pour son processus de raisonnement interne. Dans Claude 4 et les modèles ultérieurs, cette limite s'applique aux tokens de réflexion complète, et non à la sortie résumée. Des budgets plus importants peuvent améliorer la qualité de la réponse en permettant une analyse plus approfondie pour les problèmes complexes, bien que Claude ne puisse pas utiliser l'intégralité du budget alloué, en particulier pour les plages supérieures à 32k.

budget_tokens doit être défini sur une valeur inférieure à max_tokens. Cependant, lors de l'utilisation de la réflexion entrelacée avec des outils, vous pouvez dépasser cette limite car la limite de tokens devient votre fenêtre de contexte entière.

Réflexion résumée

With extended thinking enabled, the Messages API for Claude 4 models returns a summary of Claude's full thinking process. Summarized thinking provides the full intelligence benefits of extended thinking, while preventing misuse. This is the default behavior on Claude 4 models when the display field on the thinking configuration is unset or set to "summarized". On Claude Opus 4.7 and Claude Mythos Preview, display defaults to "omitted" instead, so you must set display: "summarized" explicitly to receive summarized thinking.

Here are some important considerations for summarized thinking:

• You're charged for the full thinking tokens generated by the original request, not the summary tokens.
• The billed output token count will not match the count of tokens you see in the response.
• On Claude 4 models, the first few lines of thinking output are more verbose, providing detailed reasoning that's particularly helpful for prompt engineering purposes. Claude Mythos Preview summarizes from the first token, so its thinking blocks do not show this verbose preamble.
• As Anthropic seeks to improve the extended thinking feature, summarization behavior is subject to change.
• Summarization preserves the key ideas of Claude's thinking process with minimal added latency, enabling a streamable user experience.
• Summarization is processed by a different model than the one you target in your requests. The thinking model does not see the summarized output.

Contrôle de l'affichage de la réflexion

The display field on the thinking configuration controls how thinking content is returned in API responses. It accepts two values:

• "summarized": Thinking blocks contain summarized thinking text. See Summarized thinking for details. This is the default on Claude Opus 4.6, Claude Sonnet 4.6, and earlier Claude 4 models.
• "omitted": Thinking blocks are returned with an empty thinking field. The signature field still carries the encrypted full thinking for multi-turn continuity (see Thinking encryption). This is the default on Claude Opus 4.7 and Claude Mythos Preview.

Setting display: "omitted" is useful when your application doesn't surface thinking content to users. The primary benefit is faster time-to-first-text-token when streaming: The server skips streaming thinking tokens entirely and delivers only the signature, so the final text response begins streaming sooner.

Here are some important considerations for omitted thinking:

• You're still charged for the full thinking tokens. Omitting reduces latency, not cost.
• If you pass thinking blocks back in multi-turn conversations, pass them unchanged. The server decrypts the signature to reconstruct the original thinking for prompt construction (see Preserving thinking blocks). Any text you place in the thinking field of a round-tripped omitted block is ignored.
• display is invalid with thinking.type: "disabled" (there is nothing to display).
• When using thinking.type: "adaptive" and the model skips thinking for a simple request, no thinking block is produced regardless of display.

Les pipelines automatisés qui ne présentent jamais le contenu de la réflexion aux utilisateurs finaux peuvent ignorer la surcharge de la réception des tokens de réflexion sur le fil. Les applications sensibles à la latence obtiennent la même qualité de raisonnement sans attendre que le texte de réflexion soit diffusé en continu avant que la réponse finale ne commence.

Lorsque display: "omitted" est défini, 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."
    }
  ]
}

Lors de la diffusion en continu avec display: "omitted", aucun événement thinking_delta n'est émis ; consultez Réflexion en diffusion ci-dessous pour la séquence d'événements.

Streaming de la réflexion étendue

Vous pouvez diffuser en continu les réponses de réflexion étendue en utilisant les événements envoyés par le serveur (SSE).

Lorsque la diffusion en continu est activée pour la réflexion étendue, vous recevez le contenu de réflexion via les événements thinking_delta.

Lorsque display: "omitted" est défini, aucun événement thinking_delta n'est émis. Voir Contrôle de l'affichage de la réflexion.

Pour plus de documentation sur la diffusion en continu via l'API Messages, voir Streaming Messages.

Voici comment gérer la diffusion en continu avec la réflexion :

Exemple de sortie de diffusion en continu :

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-sonnet-4-6", "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": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}

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

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

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

// Additional text deltas...

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

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

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

Lorsque display: "omitted" est défini, le bloc de réflexion s'ouvre, un seul signature_delta arrive, et le bloc se ferme sans aucun événement thinking_delta. La diffusion en continu 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":""}}

Réflexion étendue avec utilisation d'outils

La réflexion étendue peut être utilisée aux côtés de l'utilisation d'outils, permettant à Claude de raisonner sur la sélection des outils et le traitement des résultats.

Lors de l'utilisation de la réflexion étendue avec l'utilisation d'outils, soyez conscient des limitations suivantes :

1. Limitation du choix d'outil : L'utilisation d'outils avec réflexion ne supporte 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înera une erreur car ces options forcent l'utilisation d'outils, ce qui est incompatible avec la réflexion étendue.

2. Préservation des blocs de réflexion : Lors de l'utilisation d'outils, vous devez renvoyer les blocs thinking à l'API pour le dernier message de l'assistant. Incluez le bloc complet non modifié à l'API pour maintenir la continuité du raisonnement.

Basculer les modes de réflexion dans les conversations

Vous ne pouvez pas basculer la réflexion au milieu d'un tour d'assistant, y compris lors de boucles d'utilisation d'outils. L'intégralité du tour d'assistant doit fonctionner dans un seul mode de réflexion :

• Si la réflexion est activée, le tour d'assistant final doit commencer par un bloc de réflexion.
• Si la réflexion est désactivée, le tour d'assistant final ne doit contenir aucun bloc de réflexion

Du point de vue du modèle, les boucles d'utilisation d'outils font partie du tour d'assistant. Un tour d'assistant ne se termine que lorsque Claude termine sa réponse complète, qui peut inclure plusieurs appels d'outils et résultats.

Par exemple, cette séquence fait partie d'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"]

Bien qu'il y ait plusieurs messages API, la boucle d'utilisation d'outils fait conceptuellement partie d'une seule réponse d'assistant continue.

Dégradation gracieuse de la réflexion

Lorsqu'un conflit de réflexion en milieu de tour se produit (comme le basculement de la réflexion activée ou désactivée lors d'une boucle d'utilisation d'outils), l'API désactive automatiquement la réflexion pour cette demande. Pour préserver la qualité du modèle et rester dans la distribution, l'API peut :

• Supprimer les blocs de réflexion de la conversation lorsqu'ils créeraient une structure de tour invalide
• Désactiver la réflexion pour la demande actuelle lorsque l'historique de conversation est incompatible avec l'activation de la réflexion

Cela signifie que tenter de basculer la réflexion en milieu de tour ne causera pas d'erreur, mais la réflexion sera silencieusement désactivée pour cette demande. Pour confirmer si la réflexion était active, vérifiez la présence de blocs thinking dans la réponse.

Conseils pratiques

Meilleure pratique : Planifiez votre stratégie de réflexion au début de chaque tour plutôt que de tenter de basculer en milieu de tour.

Exemple : Basculer la réflexion après avoir complété un tour

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)

En complétant le tour d'assistant avant de basculer la réflexion, vous vous assurez que la réflexion est réellement activée pour la nouvelle demande.

Préserver les blocs de réflexion

Lors de l'utilisation d'outils, vous devez transmettre les blocs thinking à l'API, et vous devez inclure le bloc complet non modifié à l'API. Ceci est critique pour maintenir le flux de raisonnement du modèle et l'intégrité de la conversation.

Lorsque Claude invoque des outils, il met en pause la construction de sa réponse pour attendre des informations externes. Lorsque les résultats des outils sont renvoyés, Claude continue à construire cette réponse existante. Cela nécessite de préserver les blocs de réflexion lors de l'utilisation d'outils, pour quelques raisons :

1. Continuité du raisonnement : Les blocs de réflexion capturent le raisonnement étape par étape de Claude qui a conduit aux demandes d'outils. Lorsque vous publiez les résultats des outils, inclure la réflexion originale garantit que Claude peut continuer son raisonnement à partir du point où il s'est arrêté.

2. Maintenance du contexte : Bien que les résultats des outils apparaissent comme des messages utilisateur dans la structure de l'API, ils font partie d'un flux de raisonnement continu. Préserver les blocs de réflexion maintient ce flux conceptuel à travers plusieurs appels API. Pour plus d'informations sur la gestion du contexte, consultez le guide sur les fenêtres de contexte.

Important : Lorsque vous fournissez des blocs thinking, l'intégralité de la séquence de blocs thinking consécutifs doit correspondre aux résultats générés par le modèle lors de la demande originale ; vous ne pouvez pas réorganiser ou modifier la séquence de ces blocs.

Réflexion entrelacée

La réflexion étendue avec utilisation d'outils dans les modèles Claude 4 prend en charge la réflexion entrelacée, qui permet à Claude de réfléchir entre les appels d'outils et de faire un raisonnement plus sophistiqué après avoir reçu les résultats des outils.

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 les deux
• Prendre des décisions plus nuancées basées sur les résultats intermédiaires

Support du modèle :

• Claude Mythos Preview : La réflexion entrelacée se produit automatiquement. Chaque étape de raisonnement inter-outils se déplace dans un bloc de réflexion au lieu de texte brut, et les blocs de réflexion sont préservés à travers les tours par défaut. Aucun en-tête bêta n'est nécessaire ou pris en charge.
• Claude Opus 4.7 : La réflexion entrelacée est automatiquement activée lors de l'utilisation de la réflexion adaptative (le seul mode de réflexion pris en charge sur Opus 4.7). Aucun en-tête bêta n'est nécessaire.
• Claude Opus 4.6 : La réflexion entrelacée est automatiquement activée lors de l'utilisation de la réflexion adaptative. Aucun en-tête bêta n'est nécessaire. L'en-tête bêta interleaved-thinking-2025-05-14 est déprécié sur Opus 4.6 et est ignoré en toute sécurité s'il est inclus.
• Claude Sonnet 4.6 : La réflexion entrelacée est automatiquement activée lors de l'utilisation de la réflexion adaptative (recommandé). L'en-tête bêta interleaved-thinking-2025-05-14 avec réflexion étendue manuelle (thinking: {type: "enabled"}) est toujours fonctionnel mais déprécié.
• Autres modèles Claude 4 (Opus 4.5, Opus 4.1, Opus 4 (déprécié), Sonnet 4.5, Sonnet 4 (déprécié)) : Ajoutez à votre demande API pour activer la réflexion entrelacée.

Voici quelques considérations importantes pour la réflexion entrelacée :

• Avec la réflexion entrelacée, le budget_tokens peut dépasser le paramètre max_tokens, car il représente le budget total à travers tous les blocs de réflexion dans un tour d'assistant.
• La réflexion entrelacée n'est prise en charge que pour les outils utilisés via l'API Messages.
• Les appels directs à l'API Claude vous permettent de transmettre interleaved-thinking-2025-05-14 dans les demandes à n'importe quel modèle, sans effet (sauf Opus 4.7 et Opus 4.6, où c'est déprécié et ignoré en toute sécurité).
• Sur les plates-formes tierces (par exemple, Amazon Bedrock et Vertex AI), si vous transmettez interleaved-thinking-2025-05-14 à n'importe quel modèle autre que Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6, Claude Opus 4.5, Claude Opus 4.1, Opus 4 (déprécié), Sonnet 4.5, ou Sonnet 4 (déprécié), votre demande échouera.

Réflexion étendue avec mise en cache des invites

La mise en cache des invites avec réflexion a plusieurs considérations importantes :

Suppression du contexte des blocs de réflexion

• Les blocs de réflexion des tours précédents sont supprimés du contexte, ce qui peut affecter les points d'arrêt du cache
• Lors de la continuation des conversations avec utilisation d'outils, les blocs de réflexion sont mis en cache et comptent comme des jetons d'entrée lorsqu'ils sont lus à partir du cache
• Cela crée un compromis : bien que les blocs de réflexion ne consomment pas d'espace de fenêtre de contexte visuellement, ils comptent toujours vers votre utilisation de jetons d'entrée lorsqu'ils sont mis en cache
• Si la réflexion est désactivée et que vous transmettez du contenu de réflexion dans le tour d'utilisation d'outils actuel, le contenu de réflexion sera supprimé et la réflexion restera désactivée pour cette demande

Modèles d'invalidation du cache

• Les modifications apportées aux paramètres de réflexion (activation/désactivation ou allocation de budget) invalident les points d'arrêt du cache de messages
• La réflexion entrelacée amplifie l'invalidation du cache, car les blocs de réflexion peuvent se produire entre plusieurs appels d'outils
• Les invites système et les outils restent mis en cache malgré les modifications des paramètres de réflexion ou la suppression de blocs

Comprendre le comportement de la mise en cache des blocs de réflexion

Lors de l'utilisation de la réflexion étendue avec l'utilisation d'outils, les blocs de réflexion présentent un comportement de mise en cache spécifique qui affecte le comptage des jetons :

Fonctionnement :

1. La mise en cache ne se produit que lorsque vous effectuez une demande ultérieure qui inclut les résultats des outils
2. Lorsque la demande ultérieure est effectuée, l'historique de conversation précédent (y compris les blocs de réflexion) peut être mis en cache
3. Ces blocs de réflexion mis en cache comptent comme des jetons d'entrée dans vos métriques d'utilisation lorsqu'ils sont lus à partir du cache
4. Lorsqu'un bloc utilisateur non-résultat d'outil est inclus, tous les blocs de réflexion précédents sont ignorés et supprimés du contexte

Flux d'exemple détaillé :

Demande 1 :

User: "What's the weather in Paris?"

Réponse 1 :

[thinking_block_1] + [tool_use block 1]

Demande 2 :

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

Réponse 2 :

[thinking_block_2] + [text block 2]

La demande 2 écrit un cache du contenu de la demande (pas la réponse). Le cache inclut le message utilisateur original, le premier bloc de réflexion, le bloc d'utilisation d'outil et le résultat de l'outil.

Demande 3 :

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]

Pour Claude Opus 4.5 et versions ultérieures (y compris Claude Opus 4.6), tous les blocs de réflexion précédents sont conservés par défaut. Pour les modèles plus anciens, parce qu'un bloc utilisateur non-résultat d'outil a été inclus, tous les blocs de réflexion précédents sont ignorés. Cette demande sera traitée de la même manière que :

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]

Points clés :

• Ce comportement de mise en cache se produit automatiquement, même sans marqueurs cache_control explicites
• Ce comportement est cohérent, que vous utilisiez la réflexion régulière ou la réflexion entrelacée

Tokens max et taille de la fenêtre de contexte avec la réflexion étendue

Dans les anciens modèles Claude (antérieurs à Claude Sonnet 3.7), si la somme des tokens d'invite et de max_tokens dépassait la fenêtre de contexte du modèle, le système ajustait automatiquement max_tokens pour tenir dans la limite de contexte. Cela signifiait que vous pouviez définir une grande valeur max_tokens et le système la réduirait silencieusement selon les besoins.

Avec les modèles Claude 3.7 et 4, max_tokens (qui inclut votre budget de réflexion lorsque la réflexion est activée) est appliqué comme une limite stricte. Le système retournera maintenant une erreur de validation si les tokens d'invite + max_tokens dépassent la taille de la fenêtre de contexte.

La fenêtre de contexte avec la réflexion étendue

Lors du calcul de l'utilisation de la fenêtre de contexte avec la réflexion activée, il y a certaines considérations à connaître :

• Les blocs de réflexion des tours précédents sont supprimés et ne sont pas comptabilisés dans votre fenêtre de contexte
• La réflexion du tour actuel compte dans votre limite max_tokens pour ce tour

Le diagramme ci-dessous montre la gestion spécialisée des tokens lorsque la réflexion étendue est activée :

La fenêtre de contexte effective est calculée comme :

context window =
  (current input tokens - previous thinking tokens) +
  (thinking tokens + encrypted thinking tokens + text output tokens)

Utilisez l'API de comptage des tokens pour obtenir des comptages de tokens précis pour votre cas d'usage spécifique, en particulier lorsque vous travaillez avec des conversations multi-tours qui incluent la réflexion.

La fenêtre de contexte avec la réflexion étendue et l'utilisation d'outils

Lors de l'utilisation de la réflexion étendue avec l'utilisation d'outils, les blocs de réflexion doivent être explicitement préservés et retournés avec les résultats des outils.

Le calcul de la fenêtre de contexte effective pour la réflexion étendue avec utilisation d'outils devient :

context window =
  (current input tokens + previous thinking tokens + tool use tokens) +
  (thinking tokens + encrypted thinking tokens + text output tokens)

Le diagramme ci-dessous illustre la gestion des tokens pour la réflexion étendue avec utilisation d'outils :

Gestion des tokens avec la réflexion étendue

Compte tenu du comportement de la fenêtre de contexte et de max_tokens avec la réflexion étendue sur les modèles Claude 3.7 et 4, vous devrez peut-être :

• Surveiller et gérer plus activement votre utilisation des tokens
• Ajuster les valeurs max_tokens à mesure que la longueur de votre invite change
• Potentiellement utiliser les points de terminaison de comptage des tokens plus fréquemment
• Être conscient que les blocs de réflexion précédents ne s'accumulent pas dans votre fenêtre de contexte

Ce changement a été apporté pour fournir un comportement plus prévisible et transparent, en particulier à mesure que les limites de tokens maximaux ont augmenté considérablement.

Chiffrement de la réflexion

Full thinking content is encrypted and returned in the signature field. This field is used to verify that thinking blocks were generated by Claude when passed back to the API.

Here are some important considerations on thinking encryption:

• When streaming responses, the signature is added via a signature_delta inside a content_block_delta event just before the content_block_stop event.
• signature values are significantly longer in Claude 4 models than in previous models.
• The signature field is an opaque field and should not be interpreted or parsed.
• signature values are compatible across platforms (Claude APIs, Amazon Bedrock, and Vertex AI). Values generated on one platform will be compatible with another.

Blocs de réflexion masqués

En plus des blocs thinking réguliers, l'API peut retourner des blocs redacted_thinking. Un bloc redacted_thinking contient du contenu de réflexion chiffré dans un champ data, sans résumé lisible :

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

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

Différences de réflexion entre les versions de modèles

L'API Messages gère la réflexion différemment selon les modèles Claude Sonnet 3.7 et Claude 4, principalement dans le comportement de résumé.

Consultez le tableau ci-dessous pour une comparaison condensée :

Préservation des blocs de réflexion dans Claude Opus 4.5 et versions ultérieures

À partir de Claude Opus 4.5 (et continuant dans Claude Opus 4.6), les blocs de réflexion des tours d'assistant précédentes sont préservés dans le contexte du modèle par défaut. Ceci diffère des modèles antérieurs, qui suppriment les blocs de réflexion des tours précédentes.

Avantages de la préservation des blocs de réflexion :

• Optimisation du cache : Lors de l'utilisation d'outils, les blocs de réflexion préservés permettent les accès au cache car ils sont repassés avec les résultats des outils et mis en cache de manière incrémentale dans le tour de l'assistant, ce qui entraîne des économies de tokens dans les flux de travail multi-é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

Considérations importantes :

• Utilisation du contexte : Les conversations longues consommeront plus d'espace de contexte puisque les blocs de réflexion sont conservés dans le contexte
• Comportement automatique : Ceci est le comportement par défaut pour Claude Opus 4.5 et les modèles ultérieurs (y compris Claude Mythos Preview et Claude Opus 4.6). Aucune modification de code ou en-tête bêta requis
• Compatibilité rétroactive : Pour tirer parti de cette fonctionnalité, continuez à repasser les blocs de réflexion complets et non modifiés à l'API comme vous le feriez pour l'utilisation d'outils

Tarification

For complete pricing information including base rates, cache writes, cache hits, and output tokens, see the pricing page.

The thinking process incurs charges for:

• Tokens used during thinking (output tokens)
• Thinking blocks from prior assistant turns kept in context: only the last turn on earlier Opus/Sonnet models and all Haiku models; all turns by default on Opus 4.5+ and Sonnet 4.6+ (input tokens)
• Standard text output tokens

When using summarized thinking:

• Input tokens: Tokens in your original request (excludes thinking tokens from previous turns)
• Output tokens (billed): The original thinking tokens that Claude generated internally
• Output tokens (visible): The summarized thinking tokens you see in the response
• No charge: Tokens used to generate the summary

When using display: "omitted":

• Input tokens: Tokens in your original request (same as summarized)
• Output tokens (billed): The original thinking tokens that Claude generated internally (same as summarized)
• Output tokens (visible): Zero thinking tokens (the thinking field is empty)

Meilleures pratiques et considérations pour la réflexion étendue

Travailler avec les budgets de réflexion

• Optimisation du budget : Le budget minimum est de 1 024 tokens. Commencez par le minimum et augmentez le budget de réflexion de manière incrémentale pour trouver la plage optimale pour votre cas d'usage. Des comptages de tokens plus élevés permettent un raisonnement plus complet mais avec des rendements décroissants selon la tâche. L'augmentation du budget peut améliorer la qualité de la réponse au détriment d'une latence accrue. Pour les tâches critiques, testez différents paramètres pour trouver l'équilibre optimal. Notez que le budget de réflexion est une cible plutôt qu'une limite stricte. L'utilisation réelle des tokens peut varier en fonction de la tâche.
• Points de départ : Commencez avec des budgets de réflexion plus importants (16k+ tokens) pour les tâches complexes et ajustez selon vos besoins.
• Budgets importants : Pour les budgets de réflexion supérieurs à 32k, utilisez le traitement par lot pour éviter les problèmes de réseau. Les demandes poussant le modèle à réfléchir au-dessus de 32k tokens causent des demandes longues qui pourraient se heurter aux délais d'expiration du système et aux limites de connexions ouvertes.
• Suivi de l'utilisation des tokens : Surveillez l'utilisation des tokens de réflexion pour optimiser les coûts et les performances.

Considérations de performance

• Temps de réponse : Soyez préparé à des temps de réponse plus longs en raison du traitement supplémentaire. La génération de blocs de réflexion augmente le temps de réponse global.
• Exigences de streaming : Les SDK nécessitent le streaming lorsque max_tokens est supérieur à 21 333 pour éviter les délais d'expiration HTTP sur les demandes longues. Ceci est une validation côté client, pas une restriction 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 Messages pour plus de détails. Lors du streaming, soyez préparé à gérer les blocs de contenu de réflexion et de texte à mesure qu'ils arrivent.
• Omission de la réflexion pour la latence : Si votre application n'affiche pas le contenu de réflexion, définissez display: "omitted" sur la configuration de réflexion pour réduire le temps jusqu'au premier token de texte. Consultez Contrôle de l'affichage de la réflexion.

Compatibilité des fonctionnalités

• La réflexion n'est pas compatible avec les modifications temperature ou top_k ainsi qu'avec l'utilisation forcée d'outils.
• Lorsque la réflexion est activée, vous pouvez définir top_p sur des valeurs entre 1 et 0,95.
• Vous ne pouvez pas pré-remplir les réponses lorsque la réflexion est activée.
• Les modifications du budget de réflexion invalident les préfixes d'invite mis en cache qui incluent des messages. Cependant, les invites système mises en cache et les définitions d'outils continueront à fonctionner lorsque les paramètres de réflexion changent.

Directives d'utilisation

• Sélection des tâches : Utilisez la réflexion étendue pour les tâches particulièrement complexes qui bénéficient d'un raisonnement étape par étape, comme les mathématiques, le codage et l'analyse.
• Gestion du contexte : Vous n'avez pas besoin de supprimer vous-même les blocs de réflexion précédents. L'API Claude ignore automatiquement les blocs de réflexion des tours précédentes et ils ne sont pas inclus lors du calcul de l'utilisation du contexte.
• Ingénierie des invites : Consultez les conseils d'invite de réflexion étendue si vous souhaitez maximiser les capacités de réflexion de Claude.

Prochaines étapes