Réflexion adaptative

La réflexion adaptative est la méthode recommandée pour utiliser la réflexion étendue avec Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 et Claude Sonnet 4.6, et le seul mode de réflexion sur Claude Fable 5 et Claude Mythos 5. Au lieu de définir manuellement un budget de tokens de réflexion, la réflexion adaptative permet à Claude de déterminer dynamiquement quand et dans quelle mesure utiliser la réflexion étendue en fonction de la complexité de chaque requête. Les valeurs par défaut et les restrictions propres à chaque modèle sont répertoriées dans Modèles pris en charge.



Modèles pris en charge

La réflexion adaptative est prise en charge sur les modèles suivants :

• Claude Fable 5 (claude-fable-5) et Claude Mythos 5 (claude-mythos-5), la réflexion adaptative est toujours activée ; thinking: {type: "disabled"} n'est pas pris en charge. Aucun de ces deux modèles n'est disponible dans le cadre de la rétention zéro des données.
• Claude Mythos Preview (claude-mythos-preview), la réflexion adaptative est le mode par défaut ; thinking: {type: "disabled"} n'est pas pris en charge, et le mode manuel {type: "enabled", budget_tokens: N} est toujours accepté.
• Claude Opus 4.8 (claude-opus-4-8), la réflexion adaptative est le seul mode de réflexion pris en charge. La réflexion est désactivée sauf si vous définissez explicitement thinking: {type: "adaptive"} dans votre requête ; le mode manuel thinking: {type: "enabled"} est rejeté avec une erreur 400.
• Claude Opus 4.7 (claude-opus-4-7), la réflexion adaptative est le seul mode de réflexion pris en charge. La réflexion est désactivée sauf si vous définissez explicitement thinking: {type: "adaptive"} dans votre requête ; le mode manuel thinking: {type: "enabled"} est rejeté avec une erreur 400.
• Claude Opus 4.6 (claude-opus-4-6), la réflexion adaptative est désactivée sauf si vous définissez explicitement thinking: {type: "adaptive"} ; le mode manuel {type: "enabled", budget_tokens: N} est toujours accepté mais déprécié.
• Claude Sonnet 5 (claude-sonnet-5), la réflexion adaptative est activée par défaut ; passez thinking: {type: "disabled"} pour la désactiver. Le mode manuel {type: "enabled"} est rejeté avec une erreur 400.
• Claude Sonnet 4.6 (claude-sonnet-4-6), la réflexion adaptative est désactivée sauf si vous définissez explicitement thinking: {type: "adaptive"} ; le mode manuel {type: "enabled", budget_tokens: N} est toujours accepté mais déprécié.



Comment fonctionne la réflexion adaptative

En mode adaptatif, la réflexion est facultative pour le modèle. Claude évalue la complexité de chaque requête et détermine s'il doit utiliser la réflexion étendue et dans quelle mesure. Au niveau d'effort par défaut (high), Claude réfléchit presque toujours. À des niveaux d'effort inférieurs, Claude peut ignorer la réflexion pour les problèmes plus simples.

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



Comment utiliser la réflexion adaptative

Définissez thinking.type sur "adaptive" dans votre requête API. Les exemples définissent également thinking.display sur "summarized" pour rendre le texte de réflexion visible : sur les modèles les plus récents, display est par défaut "omitted", ce qui renvoie des blocs de réflexion avec un champ thinking vide. Consultez Contrôler l'affichage de la réflexion pour plus de détails.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    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}")

Les tokens de réflexion sont comptabilisés dans max_tokens, donc définissez-le suffisamment haut pour laisser de la place à la fois pour la réflexion et le texte de réponse. Consultez Contrôle des coûts.



Réflexion adaptative avec le paramètre effort

Vous pouvez combiner la réflexion adaptative avec le paramètre effort pour guider la quantité de réflexion effectuée par Claude. Le niveau d'effort agit comme une orientation souple pour l'allocation de réflexion de Claude :

client = anthropic.Anthropic()

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

for block in response.content:
    if block.type == "text":
        print(block.text)



Streaming avec la réflexion adaptative

La réflexion adaptative fonctionne avec le streaming. Les blocs de réflexion sont diffusés via des événements thinking_delta, de la même manière qu'en mode de réflexion manuel. Comme dans les exemples précédents, thinking.display: "summarized" rend visible le texte de réflexion diffusé :

client = anthropic.Anthropic()

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



Réflexion adaptative vs manuelle vs désactivée



Considérations importantes



Changements de validation

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

Par ailleurs, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 4.8, Claude Opus 4.7 et Claude Sonnet 5 rejettent les valeurs non par défaut de temperature, top_p et top_k avec une erreur 400. Cela s'applique à chaque requête sur ces modèles, que la réflexion soit active ou non.



Mise en cache des prompts

Les requêtes consécutives utilisant la réflexion adaptive préservent les points de rupture du cache de prompts. Cependant, le passage entre les modes de réflexion adaptive et enabled/disabled rompt les points de rupture du cache pour les messages. Les invites système et les définitions d'outils restent en cache quels que soient les changements de mode.



Ajuster le comportement de réflexion

Le comportement de déclenchement de la réflexion adaptative peut être influencé par le prompt. Si Claude réfléchit plus ou moins souvent que vous ne le souhaitez, vous pouvez ajouter des indications à 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.

Pour encourager la réflexion à la place, utilisez une formulation comme :

This task involves multi-step reasoning. Think carefully before responding.

L'efficacité de l'orientation peut être sensible à la formulation exacte. Si une formulation ne produit pas le comportement souhaité, essayez une variante plus directe.

Vous pouvez également orienter la réflexion message par message depuis le tour de l'utilisateur. Ajouter "Please think hard before responding." à un message utilisateur encourage Claude à réfléchir lors de ce tour ; "Answer directly without deliberating." la supprime. Cela fonctionne indépendamment de l'invite système et est utile lorsque seules certaines requêtes d'une conversation justifient un raisonnement étendu.



Contrôle des coûts

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

Aux niveaux d'effort high et max, Claude peut réfléchir plus longuement et est plus susceptible d'épuiser le budget max_tokens. Si vous observez stop_reason: "max_tokens" dans les réponses, envisagez d'augmenter max_tokens pour donner plus de marge au modèle, ou de réduire le niveau d'effort.



Travailler avec les blocs de réflexion

Les concepts suivants s'appliquent à tous les modèles qui prennent en charge la réflexion étendue, que vous utilisiez le mode adaptatif ou manuel.



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 Sonnet 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 de changer.
• 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.



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

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

Pour des exemples de code et le comportement de streaming avec display: "omitted", consultez Contrôler l'affichage de la réflexion sur la page de la réflexion étendue. Les exemples qui s'y trouvent utilisent type: "enabled" ; avec la réflexion adaptative, utilisez :

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



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 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 signature sont compatibles entre les plateformes (API Claude, Amazon Bedrock et Google Cloud). Les valeurs générées sur une plateforme seront compatibles avec une autre.



Sortie de réflexion sur Claude Fable 5 et Claude Mythos 5

Sur Claude Fable 5 et Claude Mythos 5, la chaîne de pensée brute n'est jamais renvoyée. Les blocs de réflexion que vous recevez sont des blocs thinking ordinaires, et non des redacted_thinking. Le paramètre thinking.display fonctionne de la même manière que sur les autres modèles :

• "summarized" renvoie un résumé lisible du raisonnement.
• "omitted" (la valeur par défaut sur ces modèles) inclut toujours des blocs thinking dans les réponses, mais leur champ thinking est une chaîne vide.

Pour la structure de réponse des blocs de réflexion, consultez la référence de l'API Messages.

Lorsque vous poursuivez une conversation sur le même modèle, renvoyez chaque bloc de réflexion à l'API exactement tel que reçu, y compris les blocs dont le champ thinking est vide. Ne les modifiez pas et ne les reconstruisez pas. Lire le texte du résumé pour l'afficher est acceptable : l'API rejette les blocs dont le contenu a été modifié, pas les blocs que vous avez lus.

Lorsque vous changez de modèle, par exemple après un repli suite à un refus du classificateur, supprimez les blocs thinking et redacted_thinking des tours précédents de l'assistant. Les blocs de réflexion sont liés au modèle qui les a produits. Les autres modèles les ignorent silencieusement plutôt que de rejeter la requête, mais les blocs ignorés ajoutent tout de même des tokens d'entrée.

Deux exceptions, couvertes dans Crédit de repli :

• Les nouvelles tentatives avec crédit de repli doivent renvoyer le corps de la requête refusée sans modification.
• Les blocs fallback issus d'un repli en cours de sortie restent là où ils sont apparus.

Pour obtenir une visibilité sur le raisonnement du modèle, lisez les blocs thinking décrits dans cette section plutôt que de demander le raisonnement dans le texte de réponse. Sur Claude Fable 5, une requête qui tente d'obtenir le raisonnement interne du modèle dans le texte de réponse peut être refusée avec stop_details.category: "reasoning_extraction". Consultez Catégories de refus pour la référence du champ et les conseils de gestion.



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



Sujets supplémentaires

La page sur la réflexion étendue couvre plusieurs sujets plus en détail avec des exemples de code spécifiques à chaque mode :

• Utilisation d'outils avec la réflexion : les mêmes règles s'appliquent pour la réflexion adaptative : préservez les blocs de réflexion entre les appels d'outils et soyez conscient des limitations de tool_choice lorsque la réflexion est active.
• Réflexion étendue avec la mise en cache des prompts : exemples de code pour la mise en cache avec des blocs de réflexion. Le comportement de cache spécifique au mode adaptatif est couvert dans Mise en cache des prompts plus haut sur cette page.
• Fenêtres de contexte : comment les tokens de réflexion interagissent avec max_tokens et les limites de la fenêtre de contexte.



Prochaines étapes