Réflexion étendue

La « extended thinking » (réflexion étendue) offre à Claude des capacités de raisonnement améliorées pour les tâches complexes, tout en fournissant différents niveaux de transparence sur son processus de réflexion étape par étape avant de livrer sa réponse finale.



Modèles pris en charge

La réflexion étendue est disponible sur tous les modèles Claude actuels. La manière de l'activer dépend du modèle :

Avec la réflexion adaptative, le modèle décide quand et combien réfléchir pour chaque requête. Sur Claude Mythos Preview, Claude Fable 5 et Claude Mythos 5, thinking: {type: "disabled"} n'est pas pris en charge. Pour les différences de comportement par modèle (sortie de réflexion, réflexion entrelacée et préservation des blocs), consultez Différences de réflexion entre les versions de modèles.



Fonctionnement de la réflexion étendue

Lorsque la réflexion étendue est activée, Claude crée des blocs de contenu thinking dans lesquels il produit son raisonnement interne. Claude intègre les enseignements de ce raisonnement avant d'élaborer une réponse finale.

La réponse de l'API inclut des blocs de contenu thinking, suivis de 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 :

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[
        {
            "role": "user",
            "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
        }
    ],
)

# La réponse contient des blocs de réflexion résumés et des blocs de texte
for block in response.content:
    if block.type == "thinking":
        print(f"\nThinking summary: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")

Pour activer la réflexion étendue, ajoutez un objet thinking avec type défini sur enabled et une valeur budget_tokens. Sur les modèles où la réflexion étendue manuelle est obsolète ou non prise en charge (voir Modèles pris en charge), utilisez plutôt type: "adaptive" comme décrit dans Réflexion adaptative.

Le paramètre budget_tokens définit le nombre maximal de tokens que Claude peut utiliser pour son processus de raisonnement interne. Cette limite s'applique aux tokens de réflexion complets, et non à la sortie résumée. Des budgets plus importants peuvent améliorer la qualité des réponses en permettant une analyse plus approfondie des problèmes complexes, bien que Claude puisse ne pas utiliser la totalité du budget alloué, en particulier pour des valeurs supérieures à 32k.

budget_tokens doit être défini sur une valeur inférieure à max_tokens. Cependant, lorsque vous utilisez 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. Étant donné que budget_tokens doit être inférieur à max_tokens, la réflexion étendue ne peut pas être combinée avec max_tokens: 0 (préchauffage du cache).



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. Il accepte deux valeurs :

• "summarized" : les blocs de réflexion contiennent un texte de réflexion résumé. Consultez Réflexion résumée pour plus de détails. Il s'agit de la valeur par défaut sur Claude Opus 4.6, Claude Sonnet 4.6 et les modèles Claude 4 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). Il s'agit de la valeur par défaut sur Claude Fable 5, Claude Mythos 5, Claude Opus 4.8, Claude Opus 4.7 et Claude Mythos Preview.

Définir display: "omitted" est utile 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 le streaming de la réponse textuelle finale commence plus tôt.

Voici quelques considérations importantes concernant 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, transmettez-les sans modification. Le serveur déchiffre le champ signature pour reconstruire la réflexion d'origine lors de la construction du prompt (voir Préservation des 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).
• Lorsque vous utilisez thinking.type: "adaptive" et que le modèle ignore la réflexion pour une requête simple, aucun bloc de réflexion n'est produit, quelle que soit la valeur de display.

Les pipelines automatisés qui n'exposent jamais le contenu de réflexion aux utilisateurs finaux peuvent éviter la surcharge liée à la réception des tokens de réflexion sur le réseau. Les applications sensibles à la latence obtiennent la même qualité de raisonnement sans attendre que le texte de réflexion soit diffusé en streaming avant que la réponse finale ne commence.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000,
        "display": "omitted",
    },
    messages=[
        {"role": "user", "content": "What is 27 * 453?"},
    ],
)

for block in response.content:
    if block.type == "thinking":
        if block.thinking:
            print(f"Thinking: {block.thinking}")
        else:
            print("Thinking: [omitted]")
    elif block.type == "text":
        print(f"Response: {block.text}")

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



Réflexion résumée

Lorsque la réflexion étendue est activée, l'API Messages pour les modèles Claude 4 renvoie un résumé du processus de réflexion complet de Claude. La réflexion résumée offre tous les avantages d'intelligence de la réflexion étendue, tout en prévenant les utilisations abusives. Il s'agit du comportement par défaut sur les modèles Claude 4 lorsque le champ display de la configuration de réflexion n'est pas défini ou est défini sur "summarized". Sur Claude Fable 5, Claude Mythos 5, Claude Opus 4.8, Claude Opus 4.7 et Claude Mythos Preview, display est défini par défaut sur "omitted" ; vous devez donc définir explicitement display: "summarized" pour recevoir la réflexion résumée.

Voici quelques considérations importantes concernant 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 d'origine, et non pour les tokens du résumé.
• Le nombre de tokens de sortie facturés ne correspondra pas au nombre de tokens que vous voyez dans la réponse.
• Sur les modèles Claude 4, les premières lignes de la sortie de réflexion sont plus détaillées, fournissant un raisonnement approfondi particulièrement utile à des fins d'ingénierie de prompts. Claude Mythos Preview résume dès le premier token, de sorte que ses blocs de réflexion n'affichent pas ce préambule détaillé.
• Anthropic cherchant à améliorer la fonctionnalité de réflexion étendue, le comportement de résumé est susceptible d'évoluer.
• Le résumé préserve les idées clés du processus de réflexion de Claude avec une latence supplémentaire minimale, permettant une expérience utilisateur compatible avec le streaming.
• Le résumé est traité par un modèle différent de celui que vous ciblez dans vos requêtes. Le modèle de réflexion ne voit pas la sortie résumée.



Streaming de la réflexion

Vous pouvez diffuser en streaming les réponses de réflexion étendue en utilisant les server-sent events (SSE).

Lorsque le streaming est activé pour la réflexion étendue, vous recevez le contenu de réflexion via des événements thinking_delta.

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

Pour plus de documentation sur le streaming via l'API Messages, consultez Streaming Messages.

Voici comment gérer le streaming avec la réflexion :

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
) as stream:
    thinking_started = False
    response_started = False

    for event in stream:
        if event.type == "content_block_start":
            print(f"\nStarting {event.content_block.type} block...")
            # Réinitialiser les indicateurs pour chaque nouveau bloc
            thinking_started = False
            response_started = False
        elif event.type == "content_block_delta":
            if event.delta.type == "thinking_delta":
                if not thinking_started:
                    print("Thinking: ", end="", flush=True)
                    thinking_started = True
                print(event.delta.thinking, end="", flush=True)
            elif event.delta.type == "text_delta":
                if not response_started:
                    print("Response: ", end="", flush=True)
                    response_started = True
                print(event.delta.text, end="", flush=True)
        elif event.type == "content_block_stop":
            print("\nBlock complete.")

Exemple de sortie en streaming :

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



Réflexion étendue avec l'utilisation d'outils

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

Lorsque vous utilisez la réflexion étendue avec l'utilisation d'outils, tenez compte des limitations suivantes :

1. Limitation du choix d'outil : l'utilisation d'outils avec la réflexion 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î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 : pendant l'utilisation d'outils, vous devez renvoyer les blocs thinking à l'API pour le dernier message de l'assistant. Incluez le bloc complet et non modifié dans l'API pour maintenir la continuité du raisonnement.



Basculer entre les modes de réflexion dans les conversations

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

• Si la réflexion est activée, le dernier tour de l'assistant doit commencer par un bloc de réflexion.
• Si la réflexion est désactivée, le dernier tour de l'assistant 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 de l'assistant. 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.

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

Même s'il y a plusieurs messages d'API, la boucle d'utilisation d'outils fait conceptuellement partie d'une seule réponse continue de l'assistant.



Dégradation gracieuse de la réflexion

Lorsqu'un conflit de réflexion survient en milieu de tour (par exemple, activer ou désactiver la réflexion pendant une boucle d'utilisation d'outils), l'API désactive automatiquement la réflexion pour cette requête. 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 requête 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 provoquera pas d'erreur, mais la réflexion sera silencieusement désactivée pour cette requête. Pour confirmer si la réflexion était active, vérifiez la présence de blocs thinking dans la réponse.



Conseils pratiques

Bonne pratique : planifiez votre stratégie de réflexion au début de chaque tour plutôt que d'essayer de basculer en milieu de tour.

Exemple : basculer la réflexion après avoir terminé 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 terminant le tour de l'assistant avant de basculer la réflexion, vous vous assurez que la réflexion est réellement activée pour la nouvelle requête.



Préservation des blocs de réflexion

Pendant l'utilisation d'outils, vous devez renvoyer les blocs thinking à l'API, et vous devez inclure le bloc complet et non modifié dans l'API. Ceci est essentiel 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 de construire cette réponse existante. Cela nécessite de préserver les blocs de réflexion pendant l'utilisation d'outils, pour plusieurs raisons :

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

2. Maintien 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. La préservation des blocs de réflexion maintient ce flux conceptuel à travers plusieurs appels d'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, la séquence entière de blocs thinking consécutifs doit correspondre aux sorties générées par le modèle lors de la requête originale ; vous ne pouvez pas réorganiser ou modifier la séquence de ces blocs.



Réflexion entrelacée

La réflexion étendue avec l'utilisation d'outils dans les modèles Claude 4 prend en charge la « interleaved thinking » (réflexion entrelacée), qui permet à Claude de réfléchir entre les appels d'outils et d'effectuer 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 intermédiaires
• Prendre des décisions plus nuancées en fonction des résultats intermédiaires

La manière d'activer la réflexion entrelacée dépend du modèle :

Les modèles Claude 4 antérieurs désignent ici Claude Sonnet 4.5, Claude Opus 4.1 (obsolète), Claude Opus 4 (retiré, sauf sur Vertex AI) et Claude Sonnet 4 (retiré, sauf sur Bedrock et Vertex AI).

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

• Avec la réflexion entrelacée, budget_tokens peut dépasser le paramètre max_tokens, car il représente le budget total sur tous les blocs de réflexion au sein d'un tour de l'assistant.
• La réflexion entrelacée n'est prise en charge que pour les outils utilisés via l'API Messages.
• L'API Claude et Claude Platform sur AWS acceptent interleaved-thinking-2025-05-14 dans les requêtes vers n'importe quel modèle sans renvoyer d'erreur. Sur les modèles qui ne prennent pas en charge la réflexion entrelacée, l'en-tête est ignoré. Sur Claude Opus 4.8, Claude Opus 4.7 et Claude Opus 4.6, il est obsolète et ignoré sans erreur. Sur Claude Mythos Preview, il n'est pas nécessaire et est ignoré sans erreur.
• Sur les plateformes exploitées par des partenaires (par exemple, Amazon Bedrock et Vertex AI), si vous passez interleaved-thinking-2025-05-14 à un modèle autre que Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6, Claude Opus 4.5, Claude Opus 4.1 (obsolète), Opus 4 (retiré, sauf sur Vertex AI), Sonnet 4.5 ou Sonnet 4 (retiré, sauf sur Bedrock et Vertex AI), votre requête échouera.



Réflexion étendue avec la mise en cache des prompts

La mise en cache des prompts avec la réflexion comporte plusieurs considérations importantes :

Suppression du contexte des blocs de réflexion

• Sur les modèles Opus/Sonnet antérieurs et tous les modèles Haiku, les blocs de réflexion des tours précédents sont supprimés du contexte, ce qui peut affecter les points de rupture du cache. Sur Opus 4.5+ et Sonnet 4.6+, ils sont conservés par défaut.
• Lors de la poursuite de conversations avec l'utilisation d'outils, les blocs de réflexion sont mis en cache et comptent comme des tokens d'entrée lorsqu'ils sont lus depuis le cache
• Cela crée un compromis : bien que les blocs de réflexion ne consomment pas visuellement d'espace dans la fenêtre de contexte, ils comptent toujours dans votre utilisation de tokens d'entrée lorsqu'ils sont mis en cache
• Si la réflexion est désactivée et que vous passez 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 requête

Schémas d'invalidation du cache

• Les modifications des paramètres de réflexion (activé/désactivé ou allocation de budget) invalident les points de rupture du cache des messages
• La réflexion entrelacée amplifie l'invalidation du cache, car les blocs de réflexion peuvent survenir entre plusieurs appels d'outils
• Les invites système et les outils restent en cache malgré les modifications des paramètres de réflexion ou la suppression de blocs



Comprendre le comportement de 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 tokens :

Fonctionnement :

1. La mise en cache ne se produit que lorsque vous effectuez une requête ultérieure qui inclut des résultats d'outils
2. Lorsque la requête 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 tokens d'entrée dans vos métriques d'utilisation lorsqu'ils sont lus depuis le cache
4. Lorsqu'un bloc utilisateur qui n'est pas un résultat d'outil est inclus : sur Opus 4.5+ et Sonnet 4.6+, les blocs de réflexion précédents sont conservés ; sur les modèles Opus/Sonnet antérieurs et tous les modèles Haiku, tous les blocs de réflexion précédents sont ignorés et supprimés du contexte

Exemple de flux détaillé :

Requête 1 :

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

Réponse 1 :

[thinking_block_1] + [tool_use block 1]

Requête 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 requête 2 écrit un cache du contenu de la requête (pas de 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.

Requête 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 Opus 4.5+ et Sonnet 4.6+, tous les blocs de réflexion précédents sont conservés par défaut. Pour les modèles Opus/Sonnet antérieurs et tous les modèles Haiku, étant donné qu'un bloc utilisateur qui n'est pas un résultat d'outil a été inclus, tous les blocs de réflexion précédents sont ignorés et supprimés du contexte. Cette requête 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 normale ou la réflexion entrelacée



Max tokens et taille de la fenêtre de contexte avec la réflexion étendue

max_tokens (qui inclut votre budget de réflexion lorsque la réflexion est activée) 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". Sur les modèles antérieurs, l'API renvoie plutôt une erreur de validation. Consultez Gestion des raisons d'arrêt.



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 quelques considérations à prendre en compte :

• Sur Opus 4.5+ et Sonnet 4.6+, les blocs de réflexion des tours précédents sont conservés et comptent dans votre fenêtre de contexte ; sur les modèles Opus/Sonnet antérieurs et tous les modèles Haiku, ils sont supprimés et ne sont pas comptés
• La réflexion du tour actuel compte dans votre limite max_tokens pour ce tour

Le diagramme ci-dessous illustre 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 suit :

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

Utilisez l'API de comptage de tokens pour obtenir des comptages de tokens précis pour votre cas d'utilisation spécifique, en particulier lorsque vous travaillez avec des conversations multi-tours qui incluent de 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 renvoyés avec les résultats des outils.

Le calcul de la fenêtre de contexte effective pour la réflexion étendue avec l'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 l'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, vous devrez peut-être :

• Surveiller et gérer plus activement votre utilisation de tokens
• Ajuster les valeurs de max_tokens à mesure que la longueur de votre prompt change
• Utiliser potentiellement les points de terminaison de comptage de 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



Chiffrement de la réflexion

Le contenu complet de la réflexion est chiffré et renvoyé dans le champ signature. Ce champ est utilisé pour vérifier que les blocs de réflexion ont bien été générés par Claude lorsqu'ils sont renvoyés à l'API.

Voici quelques considérations importantes concernant le chiffrement de la réflexion :

• Lors du streaming des réponses, la signature est ajoutée via 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 nettement plus longues dans les modèles Claude 4 que dans les modèles précédents.
• Le champ signature est un champ opaque et ne doit pas être interprété ni analysé.
• Les valeurs de signature sont compatibles entre les plateformes (API Claude, Amazon Bedrock et Vertex AI). Les valeurs générées sur une plateforme seront compatibles avec une autre.



Blocs de réflexion expurgés

En plus des blocs thinking normaux, l'API peut renvoyer 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 normaux, vous devez renvoyer les blocs redacted_thinking à l'API sans modification lors de la poursuite 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 versions de modèles Claude. Le tableau suivant donne une comparaison condensée :

¹ Définissez display: "summarized" pour recevoir une réflexion résumée. Sur Claude Fable 5, Claude Mythos 5 et Claude Mythos Preview, les tokens de réflexion bruts ne sont jamais renvoyés.
² Avec la réflexion adaptative. L'en-tête bêta interleaved-thinking-2025-05-14 n'est pas nécessaire sur ces modèles et est ignoré sans erreur s'il est inclus.
³ Les blocs sont supprimés lors de la poursuite de la conversation sur un modèle qui ne prend pas en charge le format de réflexion Mythos.



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

La préservation par défaut des blocs de réflexion des tours précédents de l'assistant dans le contexte dépend de la classe de modèle. Opus : Claude Opus 4.5 et les modèles Opus ultérieurs conservent tous les blocs de réflexion précédents ; Claude Opus 4.1 (obsolète) et les modèles Opus antérieurs ne conservent que la réflexion du dernier tour de l'assistant. Sonnet : Claude Sonnet 4.6 et les modèles Sonnet ultérieurs conservent tout ; Claude Sonnet 4.5 et les modèles Sonnet antérieurs ne conservent que le dernier tour. Haiku : tous les modèles Haiku jusqu'à Claude Haiku 4.5 ne conservent que le dernier tour. Claude Mythos Preview conserve également tous les blocs de réflexion précédents.

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 des correspondances de cache car ils sont renvoyés avec les résultats des outils et mis en cache de manière incrémentielle tout au long du tour de l'assistant, ce qui entraîne des économies de tokens dans les workflows 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 longues conversations consommeront plus d'espace de contexte puisque les blocs de réflexion sont conservés dans le contexte
• Comportement automatique : il s'agit de la valeur par défaut pour chaque modèle comme indiqué ci-dessus. Aucune modification de code ni en-tête bêta n'est requis
• Rétrocompatibilité : pour tirer parti de cette fonctionnalité, continuez à renvoyer les blocs de réflexion complets et non modifiés à l'API comme vous le feriez pour l'utilisation d'outils



Tarification

Pour obtenir des informations complètes sur la tarification, y compris les tarifs de base, les écritures en cache, les lectures depuis le cache et les tokens de sortie, consultez la page de tarification.

Le processus de réflexion entraîne des frais pour :

• Les tokens utilisés pendant la réflexion (tokens de sortie)
• Les blocs de réflexion des tours d'assistant précédents conservés dans le contexte : uniquement le dernier tour sur les modèles Opus/Sonnet antérieurs et tous les modèles Haiku ; tous les tours par défaut sur Opus 4.5+ et Sonnet 4.6+ (tokens d'entrée)
• Les tokens de sortie de texte standard

Lors de l'utilisation de la réflexion résumée :

• Tokens d'entrée : Tokens de votre requête d'origine (exclut les tokens de réflexion des tours précédents)
• Tokens de sortie (facturés) : Les tokens de réflexion d'origine que Claude a générés en interne
• Tokens de sortie (visibles) : Les tokens de réflexion résumée que vous voyez dans la réponse
• Non facturés : Tokens utilisés pour générer le résumé

Lors de l'utilisation de display: "omitted" :

• Tokens d'entrée : Tokens de votre requête d'origine (identique à la réflexion résumée)
• Tokens de sortie (facturés) : Les tokens de réflexion d'origine que Claude a générés en interne (identique à la réflexion résumée)
• Tokens de sortie (visibles) : Zéro token de réflexion (le champ thinking est vide)

Pour connaître le nombre de tokens de sortie facturés consacrés au raisonnement interne, consultez usage.output_tokens_details.thinking_tokens dans la réponse. Cette valeur reflète le raisonnement brut généré par le modèle (et non le texte résumé renvoyé dans le corps de la réponse) et est toujours inférieure ou égale à output_tokens. Soustrayez-la de output_tokens pour obtenir une approximation de la partie de la sortie qui ne relève pas du raisonnement.

{
  "usage": {
    "input_tokens": 25,
    "output_tokens": 348,
    "output_tokens_details": {
      "thinking_tokens": 312
    }
  }
}

output_tokens reste le total inclusif et faisant autorité utilisé pour la facturation. output_tokens_details est une ventilation en lecture seule destinée à l'observabilité.



Bonnes 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 au minimum et augmentez progressivement le budget de réflexion pour trouver la plage optimale pour votre cas d'usage. Un nombre de tokens plus élevé permet un raisonnement plus complet, mais avec des rendements décroissants selon la tâche. Augmenter le budget peut améliorer la qualité des réponses au prix d'une latence accrue. Pour les tâches critiques, testez différents paramètres afin de trouver l'équilibre optimal. Notez que le budget de réflexion est une cible plutôt qu'une limite stricte. L'utilisation réelle de tokens peut varier en fonction de la tâche.
• Points de départ : Commencez avec des budgets de réflexion plus importants (16k tokens ou plus) pour les tâches complexes et ajustez en fonction de vos besoins.
• Budgets importants : Pour les budgets de réflexion supérieurs à 32k, utilisez le traitement par lots afin d'éviter les problèmes réseau. Les requêtes qui poussent le modèle à réfléchir au-delà de 32k tokens entraînent des requêtes de longue durée susceptibles de se heurter aux délais d'expiration 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. Le champ usage.output_tokens_details.thinking_tokens dans la réponse indique combien de tokens de sortie facturés correspondaient au raisonnement interne. En mode streaming, cette répartition n'apparaît que sur l'événement final message_delta.



Considérations de performance

• Temps de réponse : Attendez-vous à 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 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 Messages en streaming pour plus de détails. Lors du streaming, préparez-vous à gérer à la fois les blocs de contenu de réflexion et de texte au fur et à mesure de leur arrivée.
• Omettre la réflexion pour réduire la latence : Si votre application n'affiche pas le contenu de réflexion, définissez display: "omitted" dans la configuration de réflexion pour réduire le délai avant le premier token de texte. Consultez Contrôler l'affichage de la réflexion.



Compatibilité des fonctionnalités

• La réflexion n'est pas compatible avec les modifications de temperature ou top_k, ni avec l'utilisation forcée d'outils.
• Lorsque la réflexion est activée, vous pouvez définir top_p à des valeurs comprises 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 de prompts mis en cache qui incluent des messages. Cependant, les invites système et les définitions d'outils mises en cache continueront de 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, la programmation et l'analyse.
• Gestion du contexte : Vous n'avez pas besoin de supprimer vous-même les blocs de réflexion précédents. Sur Opus 4.5+ et Sonnet 4.6+, l'API Claude conserve par défaut les blocs de réflexion des tours précédents ; sur les modèles Opus/Sonnet antérieurs et tous les modèles Haiku, elle les ignore automatiquement et ils ne sont pas inclus dans le calcul de l'utilisation du contexte.
• Ingénierie de prompts : Consultez les conseils de prompting pour la réflexion étendue si vous souhaitez maximiser les capacités de réflexion de Claude.



Étapes suivantes