Réflexion étendue

L'« extended thinking » (réflexion étendue) en mode manuel vous donne un contrôle direct sur la quantité de réflexion de Claude. Vous définissez un budget de tokens de réflexion sur chaque requête avec thinking: {type: "enabled", budget_tokens: N}, et Claude réfléchit dans la limite de ce budget avant de commencer sa réponse finale. Le mode manuel reste utile lorsque votre charge de travail exige une latence prévisible ou un contrôle précis des coûts de réflexion. Cette page explique comment définir et ajuster le budget, comment le mode manuel interagit avec la réflexion entrelacée et la « prompt caching » (mise en cache des prompts), et comment migrer vers la réflexion adaptative.

Pour comprendre le fonctionnement de la réflexion elle-même, y compris les blocs de réflexion et la forme de la réponse, le paramètre display, le streaming, la réflexion avec l'« tool use » (utilisation d'outils) et le chiffrement, consultez la présentation de la réflexion.

Modèles pris en charge

La disponibilité de la réflexion étendue par modèle, y compris les modèles pour lesquels la réflexion étendue est le seul mode, est indiquée dans le tableau de configuration par modèle.

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:
    match block.type:
        case "thinking":
            print(f"\nThinking summary: {block.thinking}")
        case "text":
            print(f"\nResponse: {block.text}")

Pour activer la réflexion étendue manuelle, ajoutez un objet thinking avec type défini sur enabled et une valeur budget_tokens.

Le paramètre budget_tokens définit une cible pour le nombre de tokens que Claude peut utiliser pour son processus de raisonnement interne. Des budgets plus importants peuvent améliorer la qualité des réponses en permettant une analyse plus approfondie des problèmes complexes.

Règles et ajustement du budget

budget_tokens doit respecter ces contraintes :

• Minimum de 1 024 tokens. L'API rejette les valeurs inférieures.
• Inférieur à max_tokens. Les tokens de réflexion sont comptabilisés dans la limite max_tokens du tour, le budget doit donc laisser de la place pour la réponse finale. La seule exception est la réflexion entrelacée, où budget_tokens peut dépasser max_tokens car le budget couvre tous les blocs de réflexion au sein d'un même tour de l'assistant.
• Pas de préchauffage du cache. Comme 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).

Le budget est une cible plutôt qu'un plafond strict. L'utilisation réelle de tokens varie selon la tâche, et Claude peut arrêter de raisonner bien avant que le budget ne soit épuisé ; max_tokens reste le plafond absolu de la sortie totale.

Sur Claude Opus 4.5, le seul modèle limité à la réflexion étendue qui prend en charge l'effort, l'effort façonne la réponse globale tandis que budget_tokens définit la profondeur de réflexion ; définissez les deux.

Pour ajuster le budget :

• Adaptez le point de départ à la tâche. Pour les tâches simples, commencez près du minimum de 1 024 tokens et augmentez progressivement pour trouver la plage optimale pour votre cas d'usage. Pour les tâches complexes, commencez avec un budget plus important de 16 000 tokens ou plus et ajustez selon vos besoins en matière de latence et de qualité. Des budgets plus élevés permettent un raisonnement plus complet, avec des rendements décroissants qui dépendent de la tâche, et au prix d'une latence accrue. Pour les tâches critiques, testez différents réglages pour trouver le bon équilibre.
• Pour les budgets de réflexion supérieurs à 32k, utilisez le traitement par lots pour éviter les problèmes réseau. Pousser le modèle à réfléchir au-delà de 32k tokens produit des requêtes de longue durée qui peuvent atteindre les délais d'expiration du système et les limites de connexions ouvertes.

Pour suivre ce qu'un budget vous coûte réellement, surveillez le champ usage.output_tokens_details.thinking_tokens dans la réponse, qui indique combien des tokens de sortie facturés correspondaient au raisonnement interne. En streaming, cette ventilation n'apparaît que dans l'événement final message_delta.

Lorsque vous êtes prêt à abandonner les budgets manuels, consultez Migrer vers la réflexion adaptative.

Réflexion entrelacée en mode manuel

L'« interleaved thinking » (réflexion entrelacée) permet à Claude de réfléchir entre les appels d'outils au sein d'un même tour de l'assistant, en raisonnant sur chaque résultat d'outil avant de décider de la suite. Pour le concept, la structure des tours et son comportement sur les modèles à réflexion adaptative, consultez réflexion entrelacée dans la présentation de la réflexion. Cette section explique comment l'activer lorsque vous utilisez la réflexion manuelle type: "enabled".

Sur Claude Opus 4.5, Claude Sonnet 4.5 et les modèles Claude 4 antérieurs, ajoutez l'en-tête bêta interleaved-thinking-2025-05-14 à votre requête API.

La génération 4.6 se divise en mode manuel :

• Claude Sonnet 4.6 : l'en-tête bêta avec le mode manuel type: "enabled" est toujours fonctionnel mais déprécié. Préférez la réflexion adaptative, qui entrelace automatiquement sans en-tête.
• Claude Opus 4.6 : le mode manuel ne dispose d'aucune réflexion entrelacée. Seul son mode adaptatif entrelace, passez donc à thinking: {type: "adaptive"} si vous avez besoin de raisonnement entre les appels d'outils sur ce modèle.

Claude Haiku 4.5 ne prend pas en charge la réflexion entrelacée. Sur l'API Claude, l'en-tête bêta est accepté mais ignoré.

Deux considérations supplémentaires pour la réflexion entrelacée en mode manuel :

• budget_tokens peut ici dépasser max_tokens ; les règles du budget expliquent cette exception.
• La réflexion entrelacée n'est prise en charge que pour les outils utilisés via l'API Messages.

Le traitement de l'en-tête bêta diffère selon les plateformes. L'API Claude et Claude Platform on AWS acceptent interleaved-thinking-2025-05-14 sur n'importe quel modèle et l'ignorent là où il n'est pas pris en charge. L'acceptation n'équivaut pas à un effet : sur les modèles qui rejettent type: "enabled" (4.7 et ultérieurs) ou qui ne disposent pas de l'entrelacement en mode manuel (Claude Opus 4.6), l'en-tête n'a aucun effet en mode manuel ; la réflexion adaptative y entrelace automatiquement.

Les plateformes exploitées par des partenaires (Amazon Bedrock et Google Cloud) acceptent également l'en-tête sur n'importe quel modèle sans renvoyer d'erreur, et l'ignorent sur les modèles qui ne prennent pas en charge la réflexion entrelacée.

Structure des tours en mode manuel

Les règles générales de structure des tours, y compris la boucle d'utilisation d'outils sur un seul tour, la gestion des conflits en milieu de tour et l'activation ou la désactivation de la réflexion entre les tours, se trouvent dans Réflexion avec utilisation d'outils.

Le mode manuel ajoute une exigence : le dernier tour de l'assistant d'une requête avec réflexion activée doit commencer par un bloc de réflexion (la réflexion adaptative supprime cette exigence). Modifier la configuration de réflexion entre les tours invalide également la mise en cache des prompts ; consultez la section suivante.

Mise en cache des prompts en mode manuel

Le mode manuel ajoute une règle en plus du comportement de mise en cache indépendant du mode décrit dans réflexion et mise en cache des prompts : modifier budget_tokens entre les requêtes invalide les points de rupture du cache, tout comme le changement de mode de réflexion, car la valeur du budget est intégrée au prompt. Les points de rupture au niveau des messages échouent toujours après un changement de budget ; le fait que les points de rupture des outils et de l'invite système échouent également dépend de l'endroit où le modèle intègre la configuration.

En pratique, choisissez un budget et maintenez-le stable pendant toute la durée d'une conversation mise en cache. Exécuter une conversation multi-tours avec mise en cache au niveau des messages sur Claude Sonnet 4.6 et modifier le budget lors de la troisième requête de 4 000 à 8 000 tokens montre directement l'invalidation :

First request - establishing cache
First response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 17, output_tokens: 700 }

Second request - same thinking parameters (cache hit expected)
Second response usage: { cache_creation_input_tokens: 0, cache_read_input_tokens: 1370, input_tokens: 303, output_tokens: 874 }

Third request - different thinking budget (cache miss expected)
Third response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 747, output_tokens: 619 }

La troisième requête recrée le cache (cache_creation_input_tokens=1370, cache_read_input_tokens=0) car le budget a changé entre les requêtes. Pour une version exécutable de la même expérience en mode adaptatif, où le niveau d'effort joue le rôle de cache que budget_tokens joue ici, consultez Mise en cache des prompts sur la page de pilotage.

Mécanismes partagés

La plupart des comportements de réflexion sont indépendants du mode et documentés une seule fois sur la page Réflexion. Tout ce qui s'y trouve s'applique également en mode manuel :

• Contrôler l'affichage de la réflexion
• Streaming de la réflexion
• Réflexion avec utilisation d'outils, y compris la préservation des blocs de réflexion
• Réflexion et mise en cache des prompts
• Réflexion et fenêtre de contexte
• Chiffrement de la réflexion
• Tarification (sur la page Piloter la réflexion)

Migrer vers la réflexion adaptative

Si votre modèle ne prend en charge que la réflexion étendue (Claude Sonnet 4.5, Claude Opus 4.5, Claude Haiku 4.5 et les modèles Claude 4 antérieurs), aucune action n'est nécessaire pour le moment : la réflexion adaptative n'y est pas disponible, et type: "adaptive" renvoie une erreur 400. Conservez budget_tokens jusqu'à ce que vous passiez à un modèle qui prend en charge la réflexion adaptative, puis appliquez la correspondance qui suit.

Vous devez abandonner type: "enabled" si :

• Vous utilisez Claude Opus 4.6 ou Claude Sonnet 4.6, où budget_tokens est déprécié.
• Vous utilisez Claude 4.7 ou un modèle ultérieur, tel que Claude Opus 5.5, Claude Sonnet 5 ou Claude Fable 5.1, où type: "enabled" renvoie une erreur 400.

La correspondance est simple : supprimez budget_tokens, définissez thinking: {type: "adaptive"}, et contrôlez la profondeur de raisonnement avec output_config: {effort: ...} au lieu d'un budget de tokens.

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 16000,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 10000
  }
}

devient :

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 16000,
  "thinking": {
    "type": "adaptive"
  },
  "output_config": {
    "effort": "high"
  }
}

effort: "high" correspond à la valeur par défaut de l'API ; il n'apparaît ici que pour montrer où se trouve désormais le contrôle de la profondeur, et l'omettre produit un comportement identique.

Attendez-vous à une différence de comportement, et non à un simple changement de syntaxe. Avec un budget fixe, Claude réfléchit à chaque requête. Avec la réflexion adaptative, Claude décide s'il doit réfléchir et dans quelle mesure à chaque requête, et avec des réglages d'effort plus faibles, il peut ignorer complètement la réflexion sur les entrées simples. Vous pouvez également supprimer l'en-tête bêta interleaved-thinking-2025-05-14 après la migration : la réflexion adaptative entrelace automatiquement, et l'API Claude ignore l'en-tête sur ces modèles. La préservation des blocs de réflexion change également : Claude Opus 4.5 et les modèles numérotés 4.6 et supérieurs conservent les blocs de réflexion des tours précédents dans le contexte et les facturent comme entrée, alors que Claude Sonnet 4.5, Claude Haiku 4.5 et les modèles antérieurs les supprimaient ; consultez préservation des blocs de réflexion par modèle.

Le changement de mode constitue une modification de la configuration de réflexion, de sorte que la première requête après le changement invalide les points de rupture du cache, comme décrit dans Mise en cache des prompts en mode manuel.

Pour des conseils complets, consultez réflexion adaptative, effort et le guide de migration des modèles.

Prochaines étapes