La réflexion de Claude (thinking)

Certains problèmes méritent mieux qu’une réponse du premier jet. La réflexion (thinking) donne à Claude le temps de raisonner avant de répondre : sur les tâches difficiles, la qualité s’améliore, et vous pouvez lire un résumé du raisonnement qui y a mené.

Ce qui a changé depuis le cours officiel

Le cours de l’Academy présente la réflexion étendue « manuelle » : thinking={"type": "enabled", "budget_tokens": N}. Sur tous les modèles Claude 5 comme sur Claude Opus 4.7 et 4.8, cette forme renvoie une erreur 400. Elle ne fonctionne plus que sur des modèles plus anciens, comme Claude Haiku 4.5, Sonnet 4.5 ou Opus 4.5. Les modèles actuels pratiquent la réflexion adaptative, objet de cette leçon.

Une réflexion adaptative, active par défaut

Sur les modèles Claude 5 (Fable 5.1, Opus 5.5, Sonnet 5.5, Haiku 5.5…), la réflexion est active par défaut, sans aucun paramètre. Elle est adaptative : à chaque requête, Claude décide s’il a besoin de réfléchir, et jusqu’où. Une question factuelle simple reçoit une réponse directe, sans bloc de réflexion ; un calcul en plusieurs étapes ou un débogage délicat déclenche un raisonnement plus long. Votre code ne doit donc pas supposer que chaque réponse commence par un bloc de réflexion.

Sur Claude Opus 4.8, Opus 4.7, Opus 4.6 et Sonnet 4.6, la réflexion est désactivée par défaut : on l’active avec thinking={"type": "adaptive"}.

Ce que contient la réponse

Quand Claude réfléchit, la réponse contient un ou plusieurs blocs thinking avant les blocs text :

{
  "content": [
    {"type": "thinking", "thinking": "", "signature": "EosnCkYICxIMMb3LzNrMu..."},
    {"type": "text", "text": "Le PGCD de 1071 et 462 est 21."}
  ]
}

Sur les modèles Claude 5, le texte de réflexion est masqué par défaut (display vaut "omitted") : le bloc arrive avec un champ thinking vide. Pour lire le raisonnement, demandez-en un résumé avec thinking={"type": "adaptive", "display": "summarized"}. Ce texte est toujours un résumé, jamais le raisonnement brut.

La fonction text_from_message de la leçon 27, qui ne garde que les blocs text, continue de fonctionner telle quelle.

Régler la profondeur : effort

Le levier principal est effort, placé dans output_config et non dans l’objet thinking. Il règle la quantité de travail de toute la réponse, réflexion comprise :

effort est une indication souple ; le plafond strict reste max_tokens, dans lequel la réflexion compte. Pour réduire le coût ou la latence, la documentation conseille de baisser d’abord effort.

Couper complètement la réflexion dépend du modèle. Claude Haiku 5.5 et Opus 5 acceptent thinking={"type": "disabled"} jusqu’à l’effort high. Sonnet 5.5 refuse disabled, mais accepte thinking={"type": "between_tools"}, son réglage le plus bas, qui supprime la réflexion en début de réponse. Opus 5.5 et Fable 5.1 ne permettent pas de la couper.

Quand y toucher

La démarche reste celle de tout ce cours : décidez sur vos évaluations. Partez des réglages par défaut, mesurez, puis ajustez effort : à la hausse si la qualité ne suffit pas sur des tâches vraiment difficiles, à la baisse si la latence ou le coût pèsent plus que le gain mesuré.

Les jetons de réflexion sont facturés comme des jetons de sortie, même quand le texte est masqué : vous payez la réflexion complète. Masquer le texte réduit la latence d’affichage, pas la facture.

Signature et blocs à renvoyer

Chaque bloc thinking porte une signature : une copie chiffrée du raisonnement complet, qui permet à l’API de vérifier que le bloc vient bien de Claude. Ce champ est opaque : on ne l’interprète pas.

• Quand vous renvoyez un résultat d’outil, les blocs de réflexion du message de Claude doivent revenir intacts : un bloc modifié, réordonné ou filtré provoque une erreur 400.
• En dehors des outils, vous pouvez omettre les blocs de réflexion des tours précédents.
• Une partie du raisonnement peut être expurgée par les systèmes de sécurité : vous recevez alors un bloc redacted_thinking, dont le champ data est chiffré. Il se renvoie lui aussi tel quel. Si votre code filtre par type, gardez thinking et redacted_thinking.

Ajouter la réponse entière à l’historique, comme le fait add_assistant_message, respecte toutes ces règles.

Implémentation

La fonction chat gagne deux paramètres : le niveau d’effort, et l’affichage du résumé.

def chat(messages, system=None, tools=None, effort=None, show_thinking=False):
    params = {"model": model, "max_tokens": 16000, "messages": messages}
    if tools:
        params["tools"] = tools
    if system:
        params["system"] = system
    if effort:
        params["output_config"] = {"effort": effort}
    if show_thinking:
        params["thinking"] = {"type": "adaptive", "display": "summarized"}
    return client.messages.create(**params)

message = chat(messages, effort="high", show_thinking=True)
for block in message.content:
    if block.type == "thinking":
        print("Raisonnement (résumé) :", block.thinking)
print(text_from_message(message))

max_tokens passe à 16 000, car la réflexion et la réponse partagent ce plafond. Au-delà d’environ 21 000, le SDK exige le streaming, pour éviter les délais d’attente HTTP.

À vous de jouer

Comparer deux niveaux d’effort. Posez un problème en plusieurs étapes, par exemple un calcul de planning, avec effort="low" puis effort="high". Comparez la justesse, la latence et usage.output_tokens. Vérifiez aussi que votre code fonctionne quand la réponse ne contient aucun bloc de réflexion.

Sources officielles : Extended thinking (Claude Academy) · Thinking (documentation Claude : réglages par modèle, affichage, signature, blocs expurgés) · Effort (documentation Claude)

Points clés à retenir

• Sur les modèles Claude 5, la réflexion est adaptative et active par défaut ; budget_tokens y renvoie une erreur 400.
• effort, dans output_config, règle la profondeur ; max_tokens reste le plafond strict.
• Le texte de réflexion est masqué par défaut ; display: "summarized" en donne un résumé.
• La réflexion est facturée en totalité, même masquée.
• Renvoyez les blocs thinking et redacted_thinking intacts, au moins quand des outils sont en jeu.