Pensée adaptative

Réflexion adaptative

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

La pensée adaptative est la méthode recommandée pour utiliser la pensée étendue avec Claude Opus 4.7, Claude Opus 4.6 et Claude Sonnet 4.6, et c'est le mode par défaut sur Claude Mythos Preview (où elle s'applique automatiquement chaque fois que thinking n'est pas défini). Au lieu de définir manuellement un budget de jetons de pensée, la pensée adaptative permet à Claude de déterminer dynamiquement quand et combien utiliser la pensée étendue en fonction de la complexité de chaque demande. Sur Claude Opus 4.7, la pensée adaptative est le seul mode de pensée supporté ; thinking: {type: "enabled", budget_tokens: N} manuel n'est plus accepté.

La pensée adaptative peut offrir de meilleures performances que la pensée étendue avec un budget_tokens fixe pour de nombreuses charges de travail, en particulier les tâches bimodales et les flux de travail agentiques à long terme. Aucun en-tête bêta n'est requis.

Si votre charge de travail nécessite une latence prévisible ou un contrôle précis des coûts de pensée, la pensée étendue avec budget_tokens est toujours fonctionnelle sur Claude Opus 4.6 et Claude Sonnet 4.6 mais est dépréciée et n'est plus recommandée. Voir l'avertissement ci-dessous.

Modèles supportés

La pensée adaptative est supportée sur les modèles suivants :

Claude Mythos Preview (claude-mythos-preview), la pensée adaptative est le mode par défaut ; thinking: {type: "disabled"} n'est pas supporté
Claude Opus 4.7 (claude-opus-4-7), la pensée adaptative est le seul mode de pensée supporté. La pensée est désactivée sauf si vous définissez explicitement thinking: {type: "adaptive"} dans votre demande ; thinking: {type: "enabled"} manuel est rejeté avec une erreur 400.
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 4.6 (claude-sonnet-4-6)

thinking.type: "enabled" et budget_tokens sont dépréciés sur Opus 4.6 et Sonnet 4.6 et seront supprimés dans une future version du modèle. Utilisez thinking.type: "adaptive" avec le paramètre effort à la place. Les configurations budget_tokens existantes sont toujours fonctionnelles mais ne sont plus recommandées ; prévoyez de migrer.

Les modèles plus anciens (Sonnet 4.5, Opus 4.5, etc.) ne supportent pas la pensée adaptative et nécessitent thinking.type: "enabled" avec budget_tokens.

Comment fonctionne la pensée adaptative

En mode adaptatif, la pensée est optionnelle pour le modèle. Claude évalue la complexité de chaque demande et détermine si et combien utiliser la pensée étendue. Au niveau d'effort par défaut (high), Claude pense presque toujours. Aux niveaux d'effort inférieurs, Claude peut ignorer la pensée pour les problèmes plus simples.

La pensée adaptative active également automatiquement la pensée entrelacée. Cela signifie que Claude peut penser entre les appels d'outils, ce qui la rend particulièrement efficace pour les flux de travail agentiques.

Comment utiliser la pensée adaptative

Définissez thinking.type à "adaptive" dans votre demande API :

Pensée adaptative avec le paramètre effort

Vous pouvez combiner la pensée adaptative avec le paramètre effort pour guider la quantité de pensée que Claude utilise. Le niveau d'effort agit comme une guidance douce pour l'allocation de pensée de Claude :

Niveau d'effort	Comportement de pensée
`max`	Claude pense toujours sans contraintes sur la profondeur de pensée. Disponible sur Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6 et Claude Sonnet 4.6.
`xhigh`	Claude pense toujours profondément avec exploration étendue. Disponible sur Claude Opus 4.7.
`high` (par défaut)	Claude pense toujours. Fournit un raisonnement profond sur les tâches complexes.
`medium`	Claude utilise une pensée modérée. Peut ignorer la pensée pour les requêtes très simples.
`low`	Claude minimise la pensée. Ignore la pensée pour les tâches simples où la vitesse est la plus importante.

Streaming avec pensée adaptative

La pensée adaptative fonctionne de manière transparente avec le streaming. Les blocs de pensée sont diffusés via des événements thinking_delta tout comme le mode de pensée manuel :

Pensée adaptative vs manuelle vs désactivée

Mode	Configuration	Disponibilité	Quand l'utiliser
Adaptative	`thinking: {type: "adaptive"}`	Claude Mythos Preview (par défaut), Opus 4.7 (seul mode), Opus 4.6, Sonnet 4.6	Claude détermine quand et combien utiliser la pensée étendue. Utilisez `effort` pour guider.
Manuelle	`thinking: {type: "enabled", budget_tokens: N}`	Tous les modèles sauf Claude Opus 4.7 (rejeté). Dépréciée sur Opus 4.6 et Sonnet 4.6 (considérez le mode adaptatif à la place).	Quand vous avez besoin d'un contrôle précis sur les dépenses de jetons de pensée.
Désactivée	Omettez le paramètre `thinking` ou passez `{type: "disabled"}`	Tous les modèles sauf Claude Mythos Preview	Quand vous n'avez pas besoin de pensée étendue et voulez la latence la plus basse.

La pensée adaptative est disponible sur Claude Mythos Preview, Claude Opus 4.7, Opus 4.6 et Sonnet 4.6. Sur Mythos Preview, la pensée adaptative est le mode par défaut et s'applique automatiquement chaque fois que thinking n'est pas défini. Sur Claude Opus 4.7, la pensée adaptative est le seul mode supporté et type: "enabled" avec budget_tokens est rejeté. Les modèles plus anciens ne supportent que type: "enabled" avec budget_tokens. Sur Opus 4.6 et Sonnet 4.6, type: "enabled" avec budget_tokens est toujours fonctionnel mais déprécié.

Disponibilité de la pensée entrelacée par mode :

Mode adaptatif : La pensée entrelacée est automatiquement activée sur Claude Mythos Preview, Claude Opus 4.7, Opus 4.6 et Sonnet 4.6. Sur Mythos Preview et Opus 4.7, le raisonnement inter-outils vit toujours à l'intérieur des blocs de pensée.
Mode manuel sur Sonnet 4.6 : La pensée entrelacée fonctionne via l'en-tête bêta interleaved-thinking-2025-05-14.
Mode manuel sur Opus 4.6 : La pensée entrelacée n'est pas disponible. Si votre flux de travail agentique nécessite une pensée entre les appels d'outils sur Opus 4.6, utilisez le mode adaptatif.

Considérations importantes

Changements de validation

Lors de l'utilisation de la pensée adaptative, les tours d'assistant précédentes n'ont pas besoin de commencer par des blocs de pensée. C'est plus flexible que le mode manuel, où l'API impose que les tours avec pensée activée commencent par un bloc de pensée.

Mise en cache des invites

Les demandes consécutives utilisant la pensée adaptive préservent les points d'arrêt du cache d'invite. Cependant, basculer entre les modes de pensée adaptive et enabled/disabled casse les points d'arrêt du cache pour les messages. Les invites système et les définitions d'outils restent mises en cache indépendamment des changements de mode.

Ajustement du comportement de pensée

Le comportement de déclenchement de la pensée adaptative est invitable. Si Claude pense plus ou moins souvent que vous le souhaitez, vous pouvez ajouter une guidance à votre invite système :

Extended thinking adds latency and should only be used when it
will meaningfully improve answer quality — typically for problems
that require multi-step reasoning. When in doubt, respond directly.

Diriger Claude à penser moins souvent peut réduire la qualité sur les tâches qui bénéficient du raisonnement. Mesurez l'impact sur vos charges de travail spécifiques avant de déployer l'ajustement basé sur les invites en production. Considérez d'abord les tests avec des niveaux d'effort inférieurs.

Contrôle des coûts

Utilisez max_tokens comme limite stricte sur la sortie totale (pensée + texte de réponse). Le paramètre effort fournit une guidance douce supplémentaire sur la quantité de pensée que Claude alloue. Ensemble, ceux-ci vous donnent un contrôle efficace sur les coûts.

Aux niveaux d'effort high et max, Claude peut penser plus extensivement et peut être plus susceptible d'épuiser le budget max_tokens. Si vous observez stop_reason: "max_tokens" dans les réponses, considérez d'augmenter max_tokens pour donner plus d'espace au modèle, ou baissez le niveau d'effort.

Travailler avec les blocs de pensée

Les concepts suivants s'appliquent à tous les modèles qui supportent la pensée étendue, que vous utilisiez le mode adaptatif ou manuel.

Pensée 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 and easy migration from Claude Sonnet 3.7 to Claude 4 and later models.
Summarization is processed by a different model than the one you target in your requests. The thinking model does not see the summarized output.

Claude Sonnet 3.7 continues to return full thinking output.

In rare cases where you need access to full thinking output for Claude 4 models, contact our sales team.

Contrôle de l'affichage de la pensée

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.

The signature field is identical whether display is "summarized" or "omitted". Switching display values between turns in a conversation is supported.

Sur Claude Opus 4.7, thinking.display est par défaut "omitted". Les blocs de pensée apparaissent toujours dans le flux de réponse, mais leur champ thinking est vide sauf si vous vous inscrivez explicitement. C'est un changement silencieux par rapport à Claude Opus 4.6, où la valeur par défaut était "summarized". Pour restaurer le texte de pensée résumée sur Claude Opus 4.7, définissez thinking.display à "summarized" explicitement :

thinking = {
    "type": "adaptive",
    "display": "summarized",
}

Pour les exemples de code et le comportement de streaming avec display: "omitted", voir Contrôle de l'affichage de la pensée sur la page de pensée étendue. Les exemples là utilisent type: "enabled" ; avec la pensée adaptative, utilisez :

thinking = {"type": "adaptive", "display": "omitted"}

Chiffrement de la pensée

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.

It is only strictly necessary to send back thinking blocks when using tools with extended thinking. Otherwise you can omit thinking blocks from previous turns. If you pass them back, whether the API keeps or strips them depends on the model: Opus 4.5+ and Sonnet 4.6+ keep them in context by default; earlier Opus/Sonnet models and all Haiku models strip them. See context editing to configure this.

If sending back thinking blocks, we recommend passing everything back as you received it for consistency and to avoid potential issues.

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.

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 extended thinking is enabled, a specialized system prompt is automatically included to support this feature.

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)

The billed output token count will not match the visible token count in the response. You are billed for the full thinking process, not the thinking content visible in the response.

Sujets supplémentaires

La page de pensée étendue couvre plusieurs sujets en plus de détails avec des exemples de code spécifiques au mode :

Utilisation d'outils avec pensée : Les mêmes règles s'appliquent pour la pensée adaptative : préservez les blocs de pensée entre les appels d'outils et soyez conscient des limitations de tool_choice quand la pensée est active.
Mise en cache des invites : Avec la pensée adaptative, les demandes consécutives utilisant le même mode de pensée préservent les points d'arrêt du cache. Basculer entre les modes adaptive et enabled/disabled casse les points d'arrêt du cache pour les messages (les invites système et les définitions d'outils restent mises en cache).
Fenêtres de contexte : Comment les jetons de pensée interagissent avec les limites max_tokens et de fenêtre de contexte.

Prochaines étapes

Pensée étendue

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=[
        {
            "role": "user",
            "content": "Explain why the sum of two even numbers is always even.",
        }
    ],
)

for block in response.content:
    if block.type == "thinking":
        print(f"\nThinking: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "What is the capital of France?"}],
)

print(response.content[0].text)

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-7",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
) as stream:
    for event in stream:
        if event.type == "content_block_start":
            print(f"\nStarting {event.content_block.type} block...")
        elif event.type == "content_block_delta":
            if event.delta.type == "thinking_delta":
                print(event.delta.thinking, end="", flush=True)
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)