Orienter la réflexion

La réflexion de Claude, ou « thinking » (réflexion), est adaptative : le modèle évalue chaque requête et décide lui-même s'il doit réfléchir et dans quelle mesure. Vous définissez une intention, vous 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, ainsi que pour les flux de travail agentiques à long horizon où la bonne quantité de raisonnement varie d'une étape à l'autre.

Pour savoir comment activer la réflexion, comment lire la sortie de réflexion, et pour en savoir plus sur la sortie de réflexion sur Claude Fable 5 et Claude Mythos 5, consultez la vue d'ensemble Réflexion. Cette page explique comment Claude décide quand réfléchir, comment orienter cette décision, ainsi que 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 requête par requête. Une 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 principal contrôle sur cette décision est le paramètre effort, qui agit comme une indication souple de la propension de Claude à réfléchir et de la profondeur de cette réflexion ; consultez la section Niveaux d'effort de cette page pour savoir ce que fait chaque niveau.

Si vous souhaitez que Claude réfléchisse moins souvent, abaissez le niveau d'effort avant de recourir à l'orientation par prompt.

La réflexion s'entrelace également automatiquement avec l'« tool use » (utilisation d'outils) : Claude peut réfléchir entre les appels d'outils, en analysant chaque résultat d'outil avant de décider de la suite (réflexion entrelacée). Vous n'avez besoin d'aucun en-tête bêta ni d'aucune configuration supplémentaire pour cela.

Pour une vue complète de la manière dont la configuration de la 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 générale, mais vous pouvez également façonner directement la décision avec des consignes en langage naturel, soit globalement dans l'« system prompt » (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. N'ajoutez des consignes dans le prompt que si le déclenchement de la réflexion par Claude ne correspond toujours pas à vos besoins à ce niveau.

Pour des conseils plus généraux sur le prompting 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 de la réflexion. Chaque niveau définit une valeur par défaut différente 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 savoir quel niveau choisir pour une charge de travail donnée, y compris les recommandations par modèle, consultez Quand ajuster le paramètre d'effort sur la page consacrée à l'effort.

L'effort se définit dans output_config.effort, et non dans l'objet thinking ; pour des exemples complets dans chaque langage, consultez Effort.

{
  "model": "claude-opus-5",
  "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.

Consignes dans l'invite système

Les consignes dans l'invite système déplacent 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 le nécessite, ajoutez des consignes 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 au contraire, 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." à la fin d'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 incitative lors des étapes de planification et la formulation suppressive lors des confirmations de routine, sans toucher à l'invite système ni modifier aucun paramètre de requête entre les tours.

Vérifier l'orientation sur votre charge de travail

L'orientation par prompt modifie le comportement du modèle ; traitez-la donc comme toute autre modification de prompt : mesurez avant de déployer. Exécutez un échantillon représentatif de votre trafic avec et sans les consignes, et comparez la fréquence de déclenchement de la réflexion (la présence de blocs de réflexion dans les réponses), la consommation de jetons 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 manière dont vous bornez 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 ancien budget de réflexion manuel 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 sous la forme dont vous disposez :

• 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, et non ce que vous devriez envoyer. Lorsque vous disposez de blocs de réflexion, renvoyez-les sans modification, en particulier lors de l'utilisation d'outils, où ils portent le raisonnement derrière les appels d'outils de Claude. Consultez la vue d'ensemble 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 le « prompt caching » (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, de sorte que la modifier entre les requêtes invalide les points de rupture du cache, tout comme le fait la modification de l'ancien paramètre 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 le prompting par message : les consignes ajoutées au message utilisateur le plus récent laissent intacts les points de rupture de cache antérieurs, contrairement à un changement de configuration ou d'effort.

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

import requests

client = Anthropic()


def fetch_article_content(url):
    text = requests.get(url).text
    lines = (line.strip() for line in text.splitlines())
    return "\n".join(line for line in lines if line)


# Récupérer le contenu de l'article
book_url = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"
book_content = fetch_article_content(book_url)
# Utiliser juste assez de texte pour la mise en cache (premiers chapitres)
LARGE_TEXT = book_content[:10000]

# Pas d'invite système - mise en cache dans les messages à la place
MESSAGES = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": LARGE_TEXT,
                "cache_control": {"type": "ephemeral"},
            },
            {"type": "text", "text": "Analyze the tone of this passage."},
        ],
    }
]

# Première requête - établir le cache
print("First request - establishing cache")
response1 = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=MESSAGES,
)

print(f"First response usage: {response1.usage}")

MESSAGES.append({"role": "assistant", "content": response1.content})
MESSAGES.append({"role": "user", "content": "Analyze the characters in this passage."})

# Deuxième requête - même configuration (succès de cache attendu)
print("\nSecond request - same configuration (cache hit expected)")
response2 = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=MESSAGES,
)

print(f"Second response usage: {response2.usage}")

MESSAGES.append({"role": "assistant", "content": response2.content})
MESSAGES.append({"role": "user", "content": "Analyze the setting in this passage."})

# Troisième requête - niveau d'effort différent (échec de cache attendu)
print("\nThird request - different effort level (cache miss expected)")
response3 = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "medium"},
    messages=MESSAGES,
)

print(f"Third response usage: {response3.usage}")

First request - establishing cache
First response usage: { cache_creation_input_tokens: 3546, cache_read_input_tokens: 0, input_tokens: 15, output_tokens: 1033 }

Second request - same configuration (cache hit expected)
Second response usage: { cache_creation_input_tokens: 0, cache_read_input_tokens: 3546, input_tokens: 1062, output_tokens: 1630 }

Third request - different effort level (cache miss expected)
Third response usage: { cache_creation_input_tokens: 3546, cache_read_input_tokens: 0, input_tokens: 2706, output_tokens: 1468 }

Contrôle des coûts

Vous ne définissez pas de budget de jetons de réflexion. Deux contrôles bornent 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 possède son propre max_tokens, de sorte qu'il ne borne pas la dépense de l'ensemble du tour.
• effort est une indication souple de la part de cette sortie que Claude alloue à la réflexion. Il façonne le comportement mais ne garantit pas un nombre de jetons.

Comme la réflexion est comptabilisée 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 dès que Claude commence à réfléchir sur des requêtes difficiles.

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

• Augmentez max_tokens pour donner au modèle plus de place pour la réflexion et la réponse.
• Abaissez le niveau d'effort afin que Claude réfléchisse moins et laisse une plus grande part du budget au 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 jetons que Claude utilise pendant la réflexion (facturés comme jetons de sortie)
• Les blocs de réflexion des tours précédents de l'assistant qui restent dans le contexte, selon la 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 jetons d'entrée)
• Les jetons 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 jetons 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 généré par le modèle (et non le texte résumé renvoyé dans le corps) et est toujours inférieure ou égale à output_tokens. Soustrayez-la de output_tokens pour estimer la part de la sortie hors raisonnement. En streaming, cette ventilation n'apparaît que dans l'événement final message_delta.

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

output_tokens reste le total inclusif faisant autorité pour la facturation. output_tokens_details est une ventilation en lecture seule à des fins d'observabilité. Pour des informations tarifaires complètes, y compris les tarifs de base, les écritures en cache, les lectures en cache et les jetons de sortie, consultez Tarification.

Étapes suivantes