Orienter la réflexion

La réflexion de Claude est adaptative : le modèle évalue chaque requête et décide par lui-même s'il doit réfléchir et dans quelle mesure. Vous définissez une intention, spécifiez éventuellement l'effort, et le modèle alloue le raisonnement là où il juge que le raisonnement sera utile.

Cela fait de la réflexion un excellent choix pour les charges de travail qui mélangent des requêtes triviales et complexes, et pour les flux de travail agentiques à long terme où la quantité appropriée de raisonnement varie d'une étape à l'autre.

Pour savoir comment activer la réflexion, comment lire la sortie de réflexion, et la sortie de réflexion sur Claude Fable 5 et Claude Mythos 5, consultez la vue d'ensemble de la Réflexion. Cette page couvre la façon dont Claude décide quand réfléchir, comment orienter cette décision, et les mécanismes de mise en cache, de coût et de tarification qui en découlent.



Comment Claude décide quand réfléchir

La réflexion est facultative pour le modèle. À chaque requête, Claude évalue la complexité de l'entrée et décide si un raisonnement plus approfondi améliorerait la réponse. Une simple question factuelle peut recevoir une réponse directe sans aucun bloc de réflexion ; un problème mathématique en plusieurs étapes ou une tâche de débogage délicate déclenche un raisonnement plus approfondi.

La décision se prend par requête. La même conversation peut contenir des tours avec et sans réflexion, et un tour où Claude a choisi de ne pas réfléchir ne contient aucun bloc de réflexion. Ne construisez pas de logique applicative qui suppose que chaque tour de l'assistant commence par un tel bloc.

Le contrôle principal sur cette décision est le paramètre effort, qui agit comme une directive souple sur la propension de Claude à réfléchir et sur la profondeur de sa réflexion ; consultez Niveaux d'effort sur cette page pour savoir ce que fait chaque niveau.

Si vous voulez que Claude réfléchisse moins souvent, abaissez le niveau d'effort avant de recourir à l'orientation basée sur les prompts.

La réflexion s'entrelace également automatiquement avec l'utilisation d'outils : Claude peut réfléchir entre les appels d'outils, en réfléchissant à chaque résultat d'outil avant de décider quoi faire ensuite (réflexion entrelacée). Vous n'avez pas besoin d'un en-tête bêta ni d'aucune configuration supplémentaire pour cela.

Pour une vue complète de la façon dont la configuration de réflexion et le paramètre d'effort interagissent, consultez Réflexion et effort.



Orienter la fréquence de réflexion de Claude

Le fait que Claude réfléchisse ou non lors d'un tour donné peut être influencé par le prompt. L'effort définit la posture globale, mais vous pouvez également façonner la décision directement avec des directives en langage naturel, soit globalement dans l'invite système, soit par message depuis le tour de l'utilisateur.

Utilisez les deux leviers ensemble dans cet ordre :

1. Définissez le niveau d'effort qui correspond à l'équilibre par défaut entre qualité et latence de votre charge de travail.
2. Ajoutez des directives dans le prompt uniquement si le déclenchement de Claude ne correspond toujours pas à vos besoins à ce niveau.

Pour des conseils plus larges sur les prompts avec la réflexion, consultez tirer parti des capacités de réflexion et de réflexion entrelacée.



Niveaux d'effort

L'effort est le principal levier d'orientation pour la réflexion. Chaque niveau définit un comportement par défaut différent pour la fréquence et la profondeur de la réflexion de Claude :

Ce tableau décrit comment chaque niveau modifie le comportement de réflexion. Pour des conseils sur le niveau à choisir pour une charge de travail donnée, y compris des recommandations par modèle, consultez Quand ajuster le paramètre d'effort sur la page consacrée à l'effort.

L'effort est défini dans output_config.effort, et non à l'intérieur de l'objet thinking ; pour des exemples complets par langage, consultez Effort.

{
  "model": "claude-opus-4-8",
  "max_tokens": 4096,
  "output_config": { "effort": "medium" },
  "messages": [{ "role": "user", "content": "..." }]
}

La disponibilité des niveaux varie selon le modèle ; le tableau de disponibilité de l'effort sur la page consacrée à l'effort fait autorité quant aux niveaux pris en charge par chaque modèle.



Directives dans l'invite système

Les directives dans l'invite système modifient le seuil de réflexion de Claude pour chaque requête de la conversation. Si Claude réfléchit plus souvent que votre charge de travail ne l'exige, ajoutez des directives comme celles-ci à 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 multistep reasoning. When in doubt, respond directly.

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

This task involves multistep 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.



Orientation par message

Vous pouvez également orienter la réflexion message par message depuis le tour de l'utilisateur, indépendamment de l'invite système. Ajouter "Please think hard before responding." à un message utilisateur encourage Claude à réfléchir lors de ce tour ; "Answer directly without deliberating." la supprime.

L'orientation par message est utile lorsque seules certaines requêtes d'une conversation justifient un raisonnement étendu. Un harnais d'agent, par exemple, peut ajouter la formulation d'encouragement sur les étapes de planification et la formulation de suppression sur les confirmations de routine, sans toucher à l'invite système ni modifier aucun paramètre de requête entre les tours.



Vérifiez l'orientation sur votre charge de travail

L'orientation basée sur les prompts modifie le comportement du modèle, traitez-la donc comme tout autre changement de prompt : mesurez avant de déployer. Exécutez un échantillon représentatif de votre trafic avec et sans les directives, et comparez la fréquence de déclenchement de la réflexion (la présence de blocs de réflexion dans les réponses), l'utilisation de tokens de sortie, la latence et la qualité des réponses sur les cas qui comptent pour vous.



Mécanismes

Trois mécanismes découlent du fait que Claude gère sa propre réflexion : la validation des tours, la mise en cache des prompts, et la façon dont vous limitez le coût.



Validation des tours

Les tours de l'assistant n'ont pas besoin de commencer par un bloc de réflexion. (Les modèles utilisant un budget de réflexion manuel hérité imposent que le dernier tour de l'assistant d'une requête avec réflexion activée commence par un tel bloc ; consultez Structure des tours en mode manuel.)

Pour les applications multi-tours, cela signifie que vous pouvez renvoyer l'historique de conversation dans la forme où vous l'avez :

• Les tours de l'assistant où Claude a choisi de ne pas réfléchir constituent un historique valide tel quel.
• Vous pouvez reprendre une conversation qui a commencé sans réflexion, ou qui utilisait une configuration de réflexion différente, sans réécrire son historique.
• Un historique assemblé à partir de sources mixtes n'a pas besoin que des blocs de réflexion soient réinsérés au début de chaque tour de l'assistant pour passer la validation.

Cet assouplissement concerne la validation, pas ce que vous devriez envoyer. Lorsque vous avez des blocs de réflexion, renvoyez-les sans modification, en particulier pendant l'utilisation d'outils, où ils portent le raisonnement derrière les appels d'outils de Claude. Consultez la vue d'ensemble de la Réflexion pour les règles complètes.



Mise en cache des prompts

Les requêtes consécutives qui conservent la même configuration de réflexion et le même niveau d'effort préservent la mise en cache des prompts ; consultez Réflexion et mise en cache des prompts pour les règles complètes. La valeur d'effort résolue est rendue dans le prompt, donc la modifier entre les requêtes invalide les points de rupture du cache, tout comme le fait la modification du paramètre hérité budget_tokens sur les modèles qui l'utilisent. Définir explicitement effort à la valeur par défaut du modèle équivaut à l'omettre et ne casse pas le cache.

La conséquence pratique : choisissez une configuration de réflexion et un niveau d'effort par conversation et conservez-les. Si certains tours nécessitent plus ou moins de réflexion, orientez avec des prompts par message : les directives ajoutées au message utilisateur le plus récent laissent intacts les points de rupture de cache antérieurs, alors qu'un changement de configuration ou d'effort ne le fait pas.

L'exemple suivant démontre l'invalidation avec un script multi-tours que vous pouvez exécuter vous-même :



Contrôle des coûts

Vous ne définissez pas de budget de tokens de réflexion. Deux contrôles limitent le coût :

• max_tokens est un plafond strict sur la sortie totale de la requête, réflexion et texte de réponse combinés. Claude ne génère jamais au-delà. Dans une boucle d'utilisation d'outils, chaque requête du tour a son propre max_tokens, il ne limite donc pas la dépense de l'ensemble du tour.
• effort est une directive souple sur la part de cette sortie que Claude alloue à la réflexion. Il façonne le comportement mais ne garantit pas un nombre de tokens.

Comme la réflexion compte dans max_tokens, définissez-le suffisamment haut pour laisser de la place à la fois au raisonnement et à la réponse. Un max_tokens dimensionné pour une réponse sans réflexion est souvent trop petit une fois que Claude commence à réfléchir sur des requêtes difficiles.

À l'effort high et au-delà, Claude peut réfléchir de manière extensive et est plus susceptible d'épuiser le budget. Si vous voyez stop_reason: "max_tokens" dans les réponses, vous avez deux remèdes :

• Augmentez max_tokens pour donner au modèle plus de place pour la réflexion plus la réponse.
• Abaissez le niveau d'effort pour que Claude réfléchisse moins et laisse une plus grande partie du budget pour le texte de réponse.

Le bon choix dépend de la question de savoir si les réponses tronquées avaient besoin du raisonnement. Si la qualité sur ces requêtes compte, augmentez le plafond ; si elles étaient sur-réfléchies, abaissez l'effort.



Tarification

La réflexion entraîne des frais pour :

• Les tokens que Claude utilise pendant la réflexion (facturés comme tokens de sortie)
• Les blocs de réflexion des tours précédents de l'assistant qui restent dans le contexte, selon le comportement de préservation par défaut : tous les tours par défaut sur les modèles qui conservent tout, uniquement le dernier tour ailleurs (facturés comme tokens d'entrée)
• Les tokens de sortie de texte standard

Ce qui vous est facturé est identique quel que soit le paramètre display ; seul ce que vous voyez change :

Pour voir combien de tokens de sortie facturés ont été consacrés au raisonnement interne, lisez usage.output_tokens_details.thinking_tokens dans la réponse. Cette valeur reflète le raisonnement brut que le modèle a généré (pas le texte résumé renvoyé dans le corps) et est toujours inférieure ou égale à output_tokens. Soustrayez-la de output_tokens pour approximer la partie non liée au raisonnement de la sortie. En streaming, cette répartition n'apparaît que sur l'événement message_delta final.

{
  "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 répartition en lecture seule à des fins d'observabilité. Pour des informations complètes sur la tarification, y compris les tarifs de base, les écritures en cache, les lectures en cache et les tokens de sortie, consultez Tarification.



Prochaines étapes