Réflexion étendue

La réflexion étendue donne à Claude le temps de raisonner avant de répondre. On peut la voir comme son monologue intérieur : la réponse contient alors deux parties, le raisonnement et le texte final.

Deux parties dans la réponse

• Un bloc de raisonnement (reasoningContent) : la façon dont Claude décompose le problème.
• Un bloc de texte : la réponse attendue.

Le raisonnement aide à comprendre et à déboguer une tâche complexe. Il a deux coûts : tous les tokens de réflexion sont facturés, comme des tokens de sortie, et la réflexion prend du temps.

Sur les modèles actuels : la réflexion adaptative

Vous l’avez constaté dès la leçon 4 : Claude Haiku 5.5 réfléchit par défaut. C’est la réflexion adaptative : le modèle décide lui-même s’il faut réfléchir, et combien, selon la difficulté de la demande. Une question simple revient vite, avec peu ou pas de réflexion ; une question difficile reçoit plus de temps. D’après la documentation, sur Haiku 5.5 :

• la réflexion est active quand la requête ne dit rien ;
• son texte est omis par défaut : le bloc ne contient qu’une signature. Pour lire un résumé du raisonnement, on demande "display": "summarized" ;
• l’ancien réglage par budget de tokens ("type": "enabled" avec budget_tokens) renvoie une erreur ;
• on peut couper la réflexion avec "type": "disabled", mais seulement à un effort high ou inférieur.

Régler la profondeur : l’effort

L’effort guide la quantité de réflexion : low, medium (la valeur par défaut sur Haiku 5.5), high, xhigh ou max. Un effort plus bas réduit la réflexion, le coût et l’attente ; un effort plus haut laisse plus de temps aux problèmes durs. Avec l’API Converse, il passe dans outputConfig ; la configuration de la réflexion, elle, passe par additionalModelRequestFields, le champ des paramètres propres au modèle :

def chat(messages, system=None, tools=None, thinking=None, effort=None):
    params = {"modelId": model_id, "messages": messages}
    if system:
        params["system"] = [{"text": system}]
    if tools:
        params["toolConfig"] = {"tools": tools}
    if thinking:
        params["additionalModelRequestFields"] = {"thinking": thinking}
    if effort:
        params["outputConfig"] = {"effort": effort}

    response = client.converse(**params)
    parts = response["output"]["message"]["content"]
    return {
        "parts": parts,
        "stop_reason": response["stopReason"],
        "text": "\n".join(part["text"] for part in parts if "text" in part),
        "reasoning": "\n".join(
            part["reasoningContent"]["reasoningText"]["text"]
            for part in parts
            if "reasoningText" in part.get("reasoningContent", {})
        ),
    }


messages = []
add_user_message(messages, "Un train part à 9 h 40 et roule 2 h 35. Une correspondance de 50 minutes suit. À quelle heure repart-on ?")
result = chat(messages, thinking={"type": "adaptive", "display": "summarized"}, effort="high")
print(result["reasoning"])
print(result["text"])

outputConfig.effort figure dans le modèle de l’API Converse de boto3 ; il demande une version récente du SDK. Le cours officiel règle aussi la réflexion par additionalModelRequestFields, avec la même structure thinking.

Pour Claude Haiku 4.5, le modèle du cours officiel, la réflexion adaptative n’existe pas : on l’active avec un budget, d’au moins 1 024 tokens, {"type": "enabled", "budget_tokens": 1024}.

La signature

Chaque bloc de raisonnement porte une signature cryptographique. Elle garantit que le raisonnement n’a pas été modifié quand on le renvoie à Claude dans la suite d’une conversation. Sur Haiku 5.5, la documentation AWS précise que les blocs de réflexion sont liés au modèle, au début de conversation qui les a produits et au compte AWS : renvoyez les tours précédents sans les modifier, sinon la requête échoue. C’est la raison pour laquelle la boucle d’outils de la leçon 28 garde chaque réponse intacte.

Le contenu expurgé

Il arrive que le raisonnement soit signalé par les systèmes de sécurité. Le bloc contient alors redactedContent au lieu de reasoningText : un contenu chiffré, illisible pour vous, mais qui fonctionne toujours si on le renvoie à Claude. Votre code doit accepter les deux formes, ce que fait le filtre de chat ci-dessus.

Quand y toucher

La décision s’appuie sur vos évaluations, comme tout le reste du cours. Optimisez d’abord le prompt ; si la précision manque encore sur une tâche complexe, montez l’effort, puis mesurez si le gain justifie le coût. À l’inverse, pour une tâche simple et fréquente, un effort plus bas réduit la facture.

À vous de jouer

Regarder la réflexion décider. Avec display à summarized, posez une question factuelle simple, puis un problème difficile de votre métier. Comparez la longueur du raisonnement, les tokens de sortie (usage) et la durée. Relancez le problème difficile avec effort="low" : la réponse reste-t-elle juste ?

Sources officielles : Extended thinking (Claude Academy) · Adaptive thinking (documentation Claude) · fiche Claude Haiku 5.5 (documentation AWS)

Points clés à retenir

• La réponse contient un bloc de raisonnement et un bloc de texte ; la réflexion est facturée en tokens de sortie.
• Haiku 5.5 réfléchit par défaut, de façon adaptative ; le texte du raisonnement est omis sauf "display": "summarized".
• L’effort règle la profondeur : outputConfig.effort avec Converse, medium par défaut sur Haiku 5.5.
• Les blocs de raisonnement sont signés et liés à la conversation : renvoyez-les intacts.
• Montez l’effort sur la foi de vos évaluations, pas par principe.