Construire avec la pensée étendue

La pensée étendue donne à Claude des capacités de raisonnement améliorées pour les tâches complexes, tout en fournissant différents niveaux de transparence dans son processus de réflexion étape par étape avant qu’il ne livre sa réponse finale.

Modèles pris en charge

La pensée étendue est prise en charge dans les modèles suivants :

• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)

Le comportement de l’API diffère entre les modèles Claude Sonnet 3.7 et Claude 4, mais les formes de l’API restent exactement les mêmes.

Pour plus d’informations, voir Différences dans la pensée entre les versions de modèles.

Comment fonctionne la pensée étendue

Lorsque la pensée étendue est activée, Claude crée des blocs de contenu thinking où il produit son raisonnement interne. Claude intègre les insights de ce raisonnement avant de créer une réponse finale.

La réponse de l’API inclura des blocs de contenu thinking, suivis de blocs de contenu text.

Voici un exemple du format de réponse par défaut :

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Laissez-moi analyser ceci étape par étape...",
      "signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
    },
    {
      "type": "text",
      "text": "Basé sur mon analyse..."
    }
  ]
}

Pour plus d’informations sur le format de réponse de la pensée étendue, voir la Référence de l’API Messages.

Comment utiliser la pensée étendue

Voici un exemple d’utilisation de la pensée étendue dans l’API Messages :

Shell

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 16000,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 10000
    },
    "messages": [
        {
            "role": "user",
            "content": "Y a-t-il un nombre infini de nombres premiers tels que n mod 4 == 3 ?"
        }
    ]
}'

Pour activer la pensée étendue, ajoutez un objet thinking, avec le paramètre type défini sur enabled et le budget_tokens sur un budget de tokens spécifié pour la pensée étendue.

Le paramètre budget_tokens détermine le nombre maximum de tokens que Claude est autorisé à utiliser pour son processus de raisonnement interne. Dans les modèles Claude 4, cette limite s’applique aux tokens de pensée complets, et non à la sortie résumée. Des budgets plus importants peuvent améliorer la qualité de la réponse en permettant une analyse plus approfondie pour les problèmes complexes, bien que Claude puisse ne pas utiliser tout le budget alloué, surtout dans les plages supérieures à 32k.

budget_tokens doit être défini sur une valeur inférieure à max_tokens. Cependant, lors de l’utilisation de la pensée entrelacée avec les outils, vous pouvez dépasser cette limite car la limite de tokens devient votre fenêtre de contexte entière (200k tokens).

Pensée résumée

Avec la pensée étendue activée, l’API Messages pour les modèles Claude 4 retourne un résumé du processus de pensée complet de Claude. La pensée résumée fournit tous les avantages d’intelligence de la pensée étendue, tout en prévenant les abus.

Voici quelques considérations importantes pour la pensée résumée :

• Vous êtes facturé pour les tokens de pensée complets générés par la demande originale, pas les tokens de résumé.
• Le nombre de tokens de sortie facturés ne correspondra pas au nombre de tokens que vous voyez dans la réponse.
• Les premières lignes de sortie de pensée sont plus verbeuses, fournissant un raisonnement détaillé qui est particulièrement utile à des fins d’ingénierie de prompt.
• Alors qu’Anthropic cherche à améliorer la fonctionnalité de pensée étendue, le comportement de résumé est sujet à changement.
• Le résumé préserve les idées clés du processus de pensée de Claude avec une latence ajoutée minimale, permettant une expérience utilisateur diffusable et une migration facile des modèles Claude Sonnet 3.7 vers Claude 4.
• Le résumé est traité par un modèle différent de celui que vous ciblez dans vos demandes. Le modèle de pensée ne voit pas la sortie résumée.

Claude Sonnet 3.7 continue de retourner la sortie de pensée complète.

Dans les rares cas où vous avez besoin d’accès à la sortie de pensée complète pour les modèles Claude 4, contactez notre équipe de vente.

Diffusion de la pensée

Vous pouvez diffuser les réponses de pensée étendue en utilisant les événements envoyés par le serveur (SSE).

Lorsque la diffusion est activée pour la pensée étendue, vous recevez le contenu de pensée via les événements thinking_delta.

Pour plus de documentation sur la diffusion via l’API Messages, voir Diffusion de Messages.

Voici comment gérer la diffusion avec la pensée :

Shell

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 16000,
    "stream": true,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 10000
    },
    "messages": [
        {
            "role": "user",
            "content": "Qu'est-ce que 27 * 453 ?"
        }
    ]
}'

Essayer dans la Console

Exemple de sortie de diffusion :

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-sonnet-4-20250514", "stop_reason": null, "stop_sequence": null}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "thinking", "thinking": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "Laissez-moi résoudre ceci étape par étape :\n\n1. D'abord décomposer 27 * 453"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n2. 453 = 400 + 50 + 3"}}

// Deltas de pensée supplémentaires...

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "text", "text": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "27 * 453 = 12,231"}}

// Deltas de texte supplémentaires...

event: content_block_stop
data: {"type": "content_block_stop", "index": 1}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null}}

event: message_stop
data: {"type": "message_stop"}

Lors de l’utilisation de la diffusion avec la pensée activée, vous pourriez remarquer que le texte arrive parfois en gros blocs alternant avec une livraison plus petite, token par token. C’est un comportement attendu, surtout pour le contenu de pensée.

Le système de diffusion doit traiter le contenu par lots pour des performances optimales, ce qui peut résulter en ce modèle de livraison “par blocs”, avec des délais possibles entre les événements de diffusion. Nous travaillons continuellement à améliorer cette expérience, avec des mises à jour futures axées sur rendre le contenu de pensée plus fluide à diffuser.

Pensée étendue avec l’utilisation d’outils

La pensée étendue peut être utilisée aux côtés de l’utilisation d’outils, permettant à Claude de raisonner à travers la sélection d’outils et le traitement des résultats.

Lors de l’utilisation de la pensée étendue avec l’utilisation d’outils, soyez conscient des limitations suivantes :

1. Limitation du choix d’outil : L’utilisation d’outils avec la pensée ne prend en charge que tool_choice: {"type": "auto"} (par défaut) ou tool_choice: {"type": "none"}. L’utilisation de tool_choice: {"type": "any"} ou tool_choice: {"type": "tool", "name": "..."} résultera en une erreur car ces options forcent l’utilisation d’outils, ce qui est incompatible avec la pensée étendue.

2. Préservation des blocs de pensée : Pendant l’utilisation d’outils, vous devez passer les blocs thinking de retour à l’API pour le dernier message assistant. Incluez le bloc complet non modifié de retour à l’API pour maintenir la continuité du raisonnement.

Exemple : Passer des blocs de pensée avec des résultats d'outils

Voici un exemple pratique montrant comment préserver les blocs de pensée lors de la fourniture de résultats d’outils :

Python

weather_tool = {
    "name": "get_weather",
    "description": "Obtenir la météo actuelle pour un lieu",
    "input_schema": {
        "type": "object",
        "properties": {
            "location": {"type": "string"}
        },
        "required": ["location"]
    }
}

# Première demande - Claude répond avec la pensée et la demande d'outil
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "Quel temps fait-il à Paris ?"}
    ]
)

La réponse de l’API inclura des blocs de pensée, de texte et d’utilisation d’outils :

{
    "content": [
        {
            "type": "thinking",
            "thinking": "L'utilisateur veut connaître la météo actuelle à Paris. J'ai accès à une fonction `get_weather`...",
            "signature": "BDaL4VrbR2Oj0hO4XpJxT28J5TILnCrrUXoKiiNBZW9P+nr8XSj1zuZzAl4egiCCpQNvfyUuFFJP5CncdYZEQPPmLxYsNrcs...."
        },
        {
            "type": "text",
            "text": "Je peux vous aider à obtenir les informations météorologiques actuelles pour Paris. Laissez-moi vérifier cela pour vous"
        },
        {
            "type": "tool_use",
            "id": "toolu_01CswdEQBMshySk6Y9DFKrfq",
            "name": "get_weather",
            "input": {
                "location": "Paris"
            }
        }
    ]
}

Maintenant continuons la conversation et utilisons l’outil

Python

# Extraire le bloc de pensée et le bloc d'utilisation d'outil
thinking_block = next((block for block in response.content
                      if block.type == 'thinking'), None)
tool_use_block = next((block for block in response.content
                      if block.type == 'tool_use'), None)

# Appeler votre API météo réelle, c'est ici que votre appel API réel irait
# prétendons que c'est ce que nous obtenons en retour
weather_data = {"temperature": 88}

# Deuxième demande - Inclure le bloc de pensée et le résultat d'outil
# Aucun nouveau bloc de pensée ne sera généré dans la réponse
continuation = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "Quel temps fait-il à Paris ?"},
        # notez que le thinking_block est passé ainsi que le tool_use_block
        # si ceci n'est pas passé, une erreur est levée
        {"role": "assistant", "content": [thinking_block, tool_use_block]},
        {"role": "user", "content": [{
            "type": "tool_result",
            "tool_use_id": tool_use_block.id,
            "content": f"Température actuelle : {weather_data['temperature']}°F"
        }]}
    ]
)

La réponse de l’API n’inclura maintenant que du texte

{
    "content": [
        {
            "type": "text",
            "text": "Actuellement à Paris, la température est de 88°F (31°C)"
        }
    ]
}

Préservation des blocs de pensée

Pendant l’utilisation d’outils, vous devez passer les blocs thinking de retour à l’API, et vous devez inclure le bloc complet non modifié de retour à l’API. Ceci est critique pour maintenir le flux de raisonnement du modèle et l’intégrité de la conversation.

Bien que vous puissiez omettre les blocs thinking des tours assistant précédents, nous suggérons de toujours passer tous les blocs de pensée de retour à l’API pour toute conversation multi-tours. L’API va :

• Filtrer automatiquement les blocs de pensée fournis
• Utiliser les blocs de pensée pertinents nécessaires pour préserver le raisonnement du modèle
• Facturer seulement les tokens d’entrée pour les blocs montrés à Claude

Quand Claude invoque des outils, il met en pause sa construction d’une réponse pour attendre des informations externes. Quand les résultats d’outils sont retournés, Claude continuera à construire cette réponse existante. Ceci nécessite de préserver les blocs de pensée pendant l’utilisation d’outils, pour quelques raisons :

1. Continuité du raisonnement : Les blocs de pensée capturent le raisonnement étape par étape de Claude qui a mené aux demandes d’outils. Quand vous postez des résultats d’outils, inclure la pensée originale assure que Claude peut continuer son raisonnement d’où il s’est arrêté.

2. Maintenance du contexte : Bien que les résultats d’outils apparaissent comme des messages utilisateur dans la structure de l’API, ils font partie d’un flux de raisonnement continu. Préserver les blocs de pensée maintient ce flux conceptuel à travers plusieurs appels API. Pour plus d’informations sur la gestion du contexte, voir notre guide sur les fenêtres de contexte.

Important : Lors de la fourniture de blocs thinking, toute la séquence de blocs thinking consécutifs doit correspondre aux sorties générées par le modèle pendant la demande originale ; vous ne pouvez pas réarranger ou modifier la séquence de ces blocs.

Pensée entrelacée

La pensée étendue avec l’utilisation d’outils dans les modèles Claude 4 prend en charge la pensée entrelacée, qui permet à Claude de penser entre les appels d’outils et de faire un raisonnement plus sophistiqué après avoir reçu les résultats d’outils.

Avec la pensée entrelacée, Claude peut :

• Raisonner sur les résultats d’un appel d’outil avant de décider quoi faire ensuite
• Enchaîner plusieurs appels d’outils avec des étapes de raisonnement entre eux
• Prendre des décisions plus nuancées basées sur des résultats intermédiaires

Pour activer la pensée entrelacée, ajoutez l’en-tête beta interleaved-thinking-2025-05-14 à votre demande API.

Voici quelques considérations importantes pour la pensée entrelacée :

• Avec la pensée entrelacée, le budget_tokens peut dépasser le paramètre max_tokens, car il représente le budget total à travers tous les blocs de pensée dans un tour assistant.
• La pensée entrelacée n’est prise en charge que pour les outils utilisés via l’API Messages.
• La pensée entrelacée est prise en charge pour les modèles Claude 4 seulement, avec l’en-tête beta interleaved-thinking-2025-05-14.
• Les appels directs à l’API d’Anthropic vous permettent de passer interleaved-thinking-2025-05-14 dans les demandes à n’importe quel modèle, sans effet.
• Sur les plateformes tierces (par exemple, Amazon Bedrock et Vertex AI), si vous passez interleaved-thinking-2025-05-14 à n’importe quel modèle autre que Claude Opus 4.1, Opus 4, ou Sonnet 4, votre demande échouera.

Utilisation d'outils sans pensée entrelacée

Python

import anthropic

client = anthropic.Anthropic()

# Définir les outils
calculator_tool = {
    "name": "calculator",
    "description": "Effectuer des calculs mathématiques",
    "input_schema": {
        "type": "object",
        "properties": {
            "expression": {
                "type": "string",
                "description": "Expression mathématique à évaluer"
            }
        },
        "required": ["expression"]
    }
}

database_tool = {
    "name": "database_query",
    "description": "Interroger la base de données de produits",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "Requête SQL à exécuter"
            }
        },
        "required": ["query"]
    }
}

# Première demande - Claude pense une fois avant tous les appels d'outils
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    messages=[{
        "role": "user",
        "content": "Quel est le chiffre d'affaires total si nous vendons 150 unités du produit A à 50$ chacune, et comment cela se compare-t-il à notre chiffre d'affaires mensuel moyen de la base de données ?"
    }]
)

# La réponse inclut la pensée suivie des utilisations d'outils
# Note : Claude pense une fois au début, puis prend toutes les décisions d'outils
print("Première réponse :")
for block in response.content:
    if block.type == "thinking":
        print(f"Pensée (résumée) : {block.thinking}")
    elif block.type == "tool_use":
        print(f"Utilisation d'outil : {block.name} avec entrée {block.input}")
    elif block.type == "text":
        print(f"Texte : {block.text}")

# Vous exécuteriez les outils et retourneriez les résultats...
# Après avoir obtenu les deux résultats d'outils, Claude répond directement sans pensée supplémentaire

Dans cet exemple sans pensée entrelacée :

1. Claude pense une fois au début pour comprendre la tâche
2. Prend toutes les décisions d’utilisation d’outils à l’avance
3. Quand les résultats d’outils sont retournés, Claude fournit immédiatement une réponse sans pensée supplémentaire

Utilisation d'outils avec pensée entrelacée

Python

import anthropic

client = anthropic.Anthropic()

# Mêmes définitions d'outils qu'avant
calculator_tool = {
    "name": "calculator",
    "description": "Effectuer des calculs mathématiques",
    "input_schema": {
        "type": "object",
        "properties": {
            "expression": {
                "type": "string",
                "description": "Expression mathématique à évaluer"
            }
        },
        "required": ["expression"]
    }
}

database_tool = {
    "name": "database_query",
    "description": "Interroger la base de données de produits",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "Requête SQL à exécuter"
            }
        },
        "required": ["query"]
    }
}

# Première demande avec pensée entrelacée activée
response = client.beta.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    betas=["interleaved-thinking-2025-05-14"],
    messages=[{
        "role": "user",
        "content": "Quel est le chiffre d'affaires total si nous vendons 150 unités du produit A à 50$ chacune, et comment cela se compare-t-il à notre chiffre d'affaires mensuel moyen de la base de données ?"
    }]
)

print("Réponse initiale :")
thinking_blocks = []
tool_use_blocks = []

for block in response.content:
    if block.type == "thinking":
        thinking_blocks.append(block)
        print(f"Pensée : {block.thinking}")
    elif block.type == "tool_use":
        tool_use_blocks.append(block)
        print(f"Utilisation d'outil : {block.name} avec entrée {block.input}")
    elif block.type == "text":
        print(f"Texte : {block.text}")

# Premier résultat d'outil (calculatrice)
calculator_result = "7500"  # 150 * 50

# Continuer avec le premier résultat d'outil
response2 = client.beta.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    betas=["interleaved-thinking-2025-05-14"],
    messages=[
        {
            "role": "user",
            "content": "Quel est le chiffre d'affaires total si nous vendons 150 unités du produit A à 50$ chacune, et comment cela se compare-t-il à notre chiffre d'affaires mensuel moyen de la base de données ?"
        },
        {
            "role": "assistant",
            "content": [thinking_blocks[0], tool_use_blocks[0]]
        },
        {
            "role": "user",
            "content": [{
                "type": "tool_result",
                "tool_use_id": tool_use_blocks[0].id,
                "content": calculator_result
            }]
        }
    ]
)

print("\nAprès le résultat de la calculatrice :")
# Avec la pensée entrelacée, Claude peut penser au résultat de la calculatrice
# avant de décider d'interroger la base de données
for block in response2.content:
    if block.type == "thinking":
        thinking_blocks.append(block)
        print(f"Pensée entrelacée : {block.thinking}")
    elif block.type == "tool_use":
        tool_use_blocks.append(block)
        print(f"Utilisation d'outil : {block.name} avec entrée {block.input}")

# Deuxième résultat d'outil (base de données)
database_result = "5200"  # Exemple de chiffre d'affaires mensuel moyen

# Continuer avec le deuxième résultat d'outil
response3 = client.beta.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    betas=["interleaved-thinking-2025-05-14"],
    messages=[
        {
            "role": "user",
            "content": "Quel est le chiffre d'affaires total si nous vendons 150 unités du produit A à 50$ chacune, et comment cela se compare-t-il à notre chiffre d'affaires mensuel moyen de la base de données ?"
        },
        {
            "role": "assistant",
            "content": [thinking_blocks[0], tool_use_blocks[0]]
        },
        {
            "role": "user",
            "content": [{
                "type": "tool_result",
                "tool_use_id": tool_use_blocks[0].id,
                "content": calculator_result
            }]
        },
        {
            "role": "assistant",
            "content": thinking_blocks[1:] + tool_use_blocks[1:]
        },
        {
            "role": "user",
            "content": [{
                "type": "tool_result",
                "tool_use_id": tool_use_blocks[1].id,
                "content": database_result
            }]
        }
    ]
)

print("\nAprès le résultat de la base de données :")
# Avec la pensée entrelacée, Claude peut penser aux deux résultats
# avant de formuler la réponse finale
for block in response3.content:
    if block.type == "thinking":
        print(f"Pensée finale : {block.thinking}")
    elif block.type == "text":
        print(f"Réponse finale : {block.text}")

Dans cet exemple avec pensée entrelacée :

1. Claude pense à la tâche initialement
2. Après avoir reçu le résultat de la calculatrice, Claude peut penser à nouveau à ce que ce résultat signifie
3. Claude décide ensuite comment interroger la base de données basé sur le premier résultat
4. Après avoir reçu le résultat de la base de données, Claude pense une fois de plus aux deux résultats avant de formuler une réponse finale
5. Le budget de pensée est distribué à travers tous les blocs de pensée dans le tour

Ce modèle permet des chaînes de raisonnement plus sophistiquées où la sortie de chaque outil informe la décision suivante.

Pensée étendue avec mise en cache de prompt

La mise en cache de prompt avec la pensée a plusieurs considérations importantes :

Les tâches de pensée étendue prennent souvent plus de 5 minutes à compléter. Considérez utiliser la durée de cache de 1 heure pour maintenir les hits de cache à travers des sessions de pensée plus longues et des flux de travail multi-étapes.

Suppression du contexte des blocs de pensée

• Les blocs de pensée des tours précédents sont supprimés du contexte, ce qui peut affecter les points de rupture du cache
• Lors de la continuation de conversations avec l’utilisation d’outils, les blocs de pensée sont mis en cache et comptent comme tokens d’entrée quand lus depuis le cache
• Ceci crée un compromis : bien que les blocs de pensée ne consomment pas d’espace de fenêtre de contexte visuellement, ils comptent toujours vers votre utilisation de tokens d’entrée quand mis en cache
• Si la pensée devient désactivée, les demandes échoueront si vous passez du contenu de pensée dans le tour d’utilisation d’outil actuel. Dans d’autres contextes, le contenu de pensée passé à l’API est simplement ignoré

Modèles d’invalidation de cache

• Les changements aux paramètres de pensée (activé/désactivé ou allocation de budget) invalident les points de rupture de cache de message
• La pensée entrelacée amplifie l’invalidation de cache, car les blocs de pensée peuvent survenir entre plusieurs appels d’outils
• Les prompts système et les outils restent mis en cache malgré les changements de paramètres de pensée ou la suppression de blocs

Bien que les blocs de pensée soient supprimés pour la mise en cache et les calculs de contexte, ils doivent être préservés lors de la continuation de conversations avec l’utilisation d’outils, surtout avec la pensée entrelacée.

Comprendre le comportement de mise en cache des blocs de pensée

Lors de l’utilisation de la pensée étendue avec l’utilisation d’outils, les blocs de pensée exhibent un comportement de mise en cache spécifique qui affecte le comptage de tokens :

Comment ça fonctionne :

1. La mise en cache ne survient que quand vous faites une demande subséquente qui inclut des résultats d’outils
2. Quand la demande subséquente est faite, l’historique de conversation précédent (incluant les blocs de pensée) peut être mis en cache
3. Ces blocs de pensée mis en cache comptent comme tokens d’entrée dans vos métriques d’utilisation quand lus depuis le cache
4. Quand un bloc utilisateur non-résultat-d’outil est inclus, tous les blocs de pensée précédents sont ignorés et supprimés du contexte

Exemple de flux détaillé :

Demande 1 :

Utilisateur : "Quel temps fait-il à Paris ?"

Réponse 1 :

[bloc_de_pensée_1] + [bloc d'utilisation d'outil 1]

Demande 2 :

Utilisateur : ["Quel temps fait-il à Paris ?"], 
Assistant : [bloc_de_pensée_1] + [bloc d'utilisation d'outil 1], 
Utilisateur : [résultat_d'outil_1, cache=True]

Réponse 2 :

[bloc_de_pensée_2] + [bloc de texte 2]

La demande 2 écrit un cache du contenu de la demande (pas la réponse). Le cache inclut le message utilisateur original, le premier bloc de pensée, le bloc d’utilisation d’outil, et le résultat d’outil.

Demande 3 :

Utilisateur : ["Quel temps fait-il à Paris ?"], 
Assistant : [bloc_de_pensée_1] + [bloc d'utilisation d'outil 1], 
Utilisateur : [résultat_d'outil_1, cache=True], 
Assistant : [bloc_de_pensée_2] + [bloc de texte 2], 
Utilisateur : [Réponse texte, cache=True]

Parce qu’un bloc utilisateur non-résultat-d’outil a été inclus, tous les blocs de pensée précédents sont ignorés. Cette demande sera traitée de la même façon que :

Utilisateur : ["Quel temps fait-il à Paris ?"], 
Assistant : [bloc d'utilisation d'outil 1], 
Utilisateur : [résultat_d'outil_1, cache=True], 
Assistant : [bloc de texte 2], 
Utilisateur : [Réponse texte, cache=True]

Points clés :

• Ce comportement de mise en cache arrive automatiquement, même sans marqueurs cache_control explicites
• Ce comportement est cohérent que vous utilisiez la pensée régulière ou la pensée entrelacée

Mise en cache de prompt système (préservée quand la pensée change)

Python

from anthropic import Anthropic
import requests
from bs4 import BeautifulSoup

client = Anthropic()

def fetch_article_content(url):
    response = requests.get(url)
    soup = BeautifulSoup(response.content, 'html.parser')

    # Supprimer les éléments script et style
    for script in soup(["script", "style"]):
        script.decompose()

    # Obtenir le texte
    text = soup.get_text()

    # Diviser en lignes et supprimer l'espace de début et de fin sur chaque
    lines = (line.strip() for line in text.splitlines())
    # Diviser les multi-titres en une ligne chacun
    chunks = (phrase.strip() for line in lines for phrase in line.split("  "))
    # Supprimer les lignes vides
    text = '\n'.join(chunk for chunk in chunks if chunk)

    return text

# 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[:5000]

SYSTEM_PROMPT=[
    {
        "type": "text",
        "text": "Vous êtes un assistant IA chargé d'analyse littéraire. Analysez le texte suivant avec attention.",
    },
    {
        "type": "text",
        "text": LARGE_TEXT,
        "cache_control": {"type": "ephemeral"}
    }
]

MESSAGES = [
    {
        "role": "user",
        "content": "Analysez le ton de ce passage."
    }
]

# Première demande - établir le cache
print("Première demande - établissement du cache")
response1 = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 4000
    },
    system=SYSTEM_PROMPT,
    messages=MESSAGES
)

print(f"Utilisation de la première réponse : {response1.usage}")

MESSAGES.append({
    "role": "assistant",
    "content": response1.content
})
MESSAGES.append({
    "role": "user",
    "content": "Analysez les personnages dans ce passage."
})
# Deuxième demande - mêmes paramètres de pensée (hit de cache attendu)
print("\nDeuxième demande - mêmes paramètres de pensée (hit de cache attendu)")
response2 = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 4000
    },
    system=SYSTEM_PROMPT,
    messages=MESSAGES
)

print(f"Utilisation de la deuxième réponse : {response2.usage}")

# Troisième demande - paramètres de pensée différents (miss de cache pour les messages)
print("\nTroisième demande - paramètres de pensée différents (miss de cache pour les messages)")
response3 = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 8000  # Budget de pensée changé
    },
    system=SYSTEM_PROMPT,  # Le prompt système reste mis en cache
    messages=MESSAGES  # Le cache des messages est invalidé
)

print(f"Utilisation de la troisième réponse : {response3.usage}")

Mise en cache de messages (invalidée quand la pensée change)

Python

from anthropic import Anthropic
import requests
from bs4 import BeautifulSoup

client = Anthropic()

def fetch_article_content(url):
    response = requests.get(url)
    soup = BeautifulSoup(response.content, 'html.parser')

    # Supprimer les éléments script et style
    for script in soup(["script", "style"]):
        script.decompose()

    # Obtenir le texte
    text = soup.get_text()

    # Diviser en lignes et supprimer l'espace de début et de fin sur chaque
    lines = (line.strip() for line in text.splitlines())
    # Diviser les multi-titres en une ligne chacun
    chunks = (phrase.strip() for line in lines for phrase in line.split("  "))
    # Supprimer les lignes vides
    text = '\n'.join(chunk for chunk in chunks if chunk)

    return text

# 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[:5000]

# Pas de prompt 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": "Analysez le ton de ce passage."
            }
        ]
    }
]

# Première demande - établir le cache
print("Première demande - établissement du cache")
response1 = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 4000
    },
    messages=MESSAGES
)

print(f"Utilisation de la première réponse : {response1.usage}")

MESSAGES.append({
    "role": "assistant",
    "content": response1.content
})
MESSAGES.append({
    "role": "user",
    "content": "Analysez les personnages dans ce passage."
})
# Deuxième demande - mêmes paramètres de pensée (hit de cache attendu)
print("\nDeuxième demande - mêmes paramètres de pensée (hit de cache attendu)")
response2 = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 4000  # Même budget de pensée
    },
    messages=MESSAGES
)

print(f"Utilisation de la deuxième réponse : {response2.usage}")

MESSAGES.append({
    "role": "assistant",
    "content": response2.content
})
MESSAGES.append({
    "role": "user",
    "content": "Analysez le cadre dans ce passage."
})

# Troisième demande - budget de pensée différent (miss de cache attendu)
print("\nTroisième demande - budget de pensée différent (miss de cache attendu)")
response3 = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 8000  # Budget de pensée différent casse le cache
    },
    messages=MESSAGES
)

print(f"Utilisation de la troisième réponse : {response3.usage}")

Voici la sortie du script (vous pourriez voir des nombres légèrement différents)

Première demande - établissement du cache
Utilisation de la première réponse : { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 17, output_tokens: 700 }

Deuxième demande - mêmes paramètres de pensée (hit de cache attendu)

Utilisation de la deuxième réponse : { cache_creation_input_tokens: 0, cache_read_input_tokens: 1370, input_tokens: 303, output_tokens: 874 }

Troisième demande - budget de pensée différent (miss de cache attendu)
Utilisation de la troisième réponse : { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 747, output_tokens: 619 }

Cet exemple démontre que quand la mise en cache est configurée dans le tableau de messages, changer les paramètres de pensée (budget_tokens augmenté de 4000 à 8000) invalide le cache. La troisième demande ne montre aucun hit de cache avec cache_creation_input_tokens=1370 et cache_read_input_tokens=0, prouvant que la mise en cache basée sur les messages est invalidée quand les paramètres de pensée changent.

Tokens max et taille de fenêtre de contexte avec la pensée étendue

Dans les anciens modèles Claude (antérieurs à Claude Sonnet 3.7), si la somme des tokens de prompt et max_tokens dépassait la fenêtre de contexte du modèle, le système ajustait automatiquement max_tokens pour s’adapter dans la limite de contexte. Cela signifiait que vous pouviez définir une grande valeur max_tokens et le système la réduirait silencieusement selon les besoins.

Avec les modèles Claude 3.7 et 4, max_tokens (qui inclut votre budget de pensée quand la pensée est activée) est appliqué comme une limite stricte. Le système retournera maintenant une erreur de validation si tokens de prompt + max_tokens dépasse la taille de la fenêtre de contexte.

Vous pouvez lire notre guide sur les fenêtres de contexte pour une plongée plus approfondie.

La fenêtre de contexte avec la pensée étendue

Lors du calcul de l’utilisation de la fenêtre de contexte avec la pensée activée, il y a quelques considérations à connaître :

• Les blocs de pensée des tours précédents sont supprimés et ne comptent pas vers votre fenêtre de contexte
• La pensée du tour actuel compte vers votre limite max_tokens pour ce tour

Le diagramme ci-dessous démontre la gestion spécialisée des tokens quand la pensée étendue est activée :

La fenêtre de contexte effective est calculée comme :

fenêtre de contexte =
  (tokens d'entrée actuels - tokens de pensée précédents) +
  (tokens de pensée + tokens de pensée chiffrés + tokens de sortie de texte)

Nous recommandons d’utiliser l’API de comptage de tokens pour obtenir des comptes de tokens précis pour votre cas d’usage spécifique, surtout lors du travail avec des conversations multi-tours qui incluent la pensée.

La fenêtre de contexte avec la pensée étendue et l’utilisation d’outils

Lors de l’utilisation de la pensée étendue avec l’utilisation d’outils, les blocs de pensée doivent être explicitement préservés et retournés avec les résultats d’outils.

Le calcul de fenêtre de contexte effective pour la pensée étendue avec l’utilisation d’outils devient :

fenêtre de contexte =
  (tokens d'entrée actuels + tokens de pensée précédents + tokens d'utilisation d'outils) +
  (tokens de pensée + tokens de pensée chiffrés + tokens de sortie de texte)

Le diagramme ci-dessous illustre la gestion des tokens pour la pensée étendue avec l’utilisation d’outils :

Gestion des tokens avec la pensée étendue

Étant donné le comportement de la fenêtre de contexte et max_tokens avec les modèles de pensée étendue Claude 3.7 et 4, vous pourriez avoir besoin de :

• Surveiller et gérer plus activement votre utilisation de tokens
• Ajuster les valeurs max_tokens à mesure que votre longueur de prompt change
• Potentiellement utiliser les endpoints de comptage de tokens plus fréquemment
• Être conscient que les blocs de pensée précédents ne s’accumulent pas dans votre fenêtre de contexte

Ce changement a été fait pour fournir un comportement plus prévisible et transparent, surtout alors que les limites de tokens maximum ont augmenté significativement.

Chiffrement de la pensée

Le contenu de pensée complet est chiffré et retourné dans le champ signature. Ce champ est utilisé pour vérifier que les blocs de pensée ont été générés par Claude quand passés de retour à l’API.

Il n’est strictement nécessaire de renvoyer les blocs de pensée que lors de l’utilisation d’outils avec la pensée étendue. Sinon vous pouvez omettre les blocs de pensée des tours précédents, ou laisser l’API les supprimer pour vous si vous les passez de retour.

Si vous renvoyez des blocs de pensée, nous recommandons de tout passer de retour comme vous l’avez reçu pour la cohérence et pour éviter des problèmes potentiels.

Voici quelques considérations importantes sur le chiffrement de la pensée :

• Lors de la diffusion de réponses, la signature est ajoutée via un signature_delta à l’intérieur d’un événement content_block_delta juste avant l’événement content_block_stop.
• Les valeurs signature sont significativement plus longues dans les modèles Claude 4 que dans les modèles précédents.
• Le champ signature est un champ opaque et ne devrait pas être interprété ou analysé - il existe uniquement à des fins de vérification.
• Les valeurs signature sont compatibles à travers les plateformes (APIs Anthropic, Amazon Bedrock, et Vertex AI). Les valeurs générées sur une plateforme seront compatibles avec une autre.

Rédaction de la pensée

Occasionnellement, le raisonnement interne de Claude sera signalé par nos systèmes de sécurité. Quand cela survient, nous chiffrons une partie ou la totalité du bloc thinking et vous le retournons comme un bloc redacted_thinking. Les blocs redacted_thinking sont déchiffrés quand passés de retour à l’API, permettant à Claude de continuer sa réponse sans perdre le contexte.

Lors de la construction d’applications orientées client qui utilisent la pensée étendue :

• Soyez conscient que les blocs de pensée rédactés contiennent du contenu chiffré qui n’est pas lisible par l’humain
• Considérez fournir une explication simple comme : “Une partie du raisonnement interne de Claude a été automatiquement chiffrée pour des raisons de sécurité. Cela n’affecte pas la qualité des réponses.”
• Si vous montrez des blocs de pensée aux utilisateurs, vous pouvez filtrer les blocs rédactés tout en préservant les blocs de pensée normaux
• Soyez transparent que l’utilisation des fonctionnalités de pensée étendue peut occasionnellement résulter en un raisonnement chiffré
• Implémentez une gestion d’erreur appropriée pour gérer gracieusement la pensée rédactée sans casser votre UI

Voici un exemple montrant à la fois des blocs de pensée normaux et rédactés :

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Laissez-moi analyser ceci étape par étape...",
      "signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
    },
    {
      "type": "redacted_thinking",
      "data": "EmwKAhgBEgy3va3pzix/LafPsn4aDFIT2Xlxh0L5L8rLVyIwxtE3rAFBa8cr3qpPkNRj2YfWXGmKDxH4mPnZ5sQ7vB9URj2pLmN3kF8/dW5hR7xJ0aP1oLs9yTcMnKVf2wRpEGjH9XZaBt4UvDcPrQ..."
    },
    {
      "type": "text",
      "text": "Basé sur mon analyse..."
    }
  ]
}

Voir des blocs de pensée rédactés dans votre sortie est un comportement attendu. Le modèle peut toujours utiliser ce raisonnement rédacté pour informer ses réponses tout en maintenant les garde-fous de sécurité.

Si vous avez besoin de tester la gestion de pensée rédactée dans votre application, vous pouvez utiliser cette chaîne de test spéciale comme votre prompt : ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CB

Lors du passage de blocs thinking et redacted_thinking de retour à l’API dans une conversation multi-tours, vous devez inclure le bloc complet non modifié de retour à l’API pour le dernier tour assistant. Ceci est critique pour maintenir le flux de raisonnement du modèle. Nous suggérons de toujours passer tous les blocs de pensée de retour à l’API. Pour plus de détails, voir la section Préservation des blocs de pensée ci-dessus.

Exemple : Travailler avec des blocs de pensée rédactés

Cet exemple démontre comment gérer les blocs redacted_thinking qui peuvent apparaître dans les réponses quand le raisonnement interne de Claude contient du contenu signalé par les systèmes de sécurité :

Python

import anthropic

client = anthropic.Anthropic()

# Utiliser un prompt spécial qui déclenche la pensée rédactée (à des fins de démonstration seulement)
response = client.messages.create(
    model="claude-3-7-sonnet-20250219",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    messages=[{
        "role": "user",
        "content": "ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CB"
    }]
)

# Identifier les blocs de pensée rédactés
has_redacted_thinking = any(
    block.type == "redacted_thinking" for block in response.content
)

if has_redacted_thinking:
    print("La réponse contient des blocs de pensée rédactés")
    # Ces blocs sont toujours utilisables dans les demandes subséquentes

    # Extraire tous les blocs (rédactés et non-rédactés)
    all_thinking_blocks = [
        block for block in response.content
        if block.type in ["thinking", "redacted_thinking"]
    ]

    # Lors du passage aux demandes subséquentes, inclure tous les blocs sans modification
    # Ceci préserve l'intégrité du raisonnement de Claude

    print(f"Trouvé {len(all_thinking_blocks)} blocs de pensée au total")
    print(f"Ces blocs sont toujours facturables comme tokens de sortie")

Essayer dans la Console

Différences dans la pensée entre les versions de modèles

L’API Messages gère la pensée différemment entre les modèles Claude Sonnet 3.7 et Claude 4, principalement dans le comportement de rédaction et de résumé.

Voir le tableau ci-dessous pour une comparaison condensée :

Fonctionnalité	Claude Sonnet 3.7	Modèles Claude 4
Sortie de Pensée	Retourne la sortie de pensée complète	Retourne la pensée résumée
Pensée Entrelacée	Non prise en charge	Prise en charge avec l’en-tête beta interleaved-thinking-2025-05-14

Tarification

La pensée étendue utilise le schéma de tarification de tokens standard :

Modèle	Tokens d’Entrée de Base	Écritures de Cache	Hits de Cache	Tokens de Sortie
Claude Opus 4.1	15$ / MTok	18,75$ / MTok	1,50$ / MTok	75$ / MTok
Claude Opus 4	15$ / MTok	18,75$ / MTok	1,50$ / MTok	75$ / MTok
Claude Sonnet 4	3$ / MTok	3,75$ / MTok	0,30$ / MTok	15$ / MTok
Claude Sonnet 3.7	3$ / MTok	3,75$ / MTok	0,30$ / MTok	15$ / MTok

Le processus de pensée entraîne des frais pour :

• Les tokens utilisés pendant la pensée (tokens de sortie)
• Les blocs de pensée du dernier tour assistant inclus dans les demandes subséquentes (tokens d’entrée)
• Les tokens de sortie de texte standard

Quand la pensée étendue est activée, un prompt système spécialisé est automatiquement inclus pour prendre en charge cette fonctionnalité.

Lors de l’utilisation de la pensée résumée :

• Tokens d’entrée : Tokens dans votre demande originale (exclut les tokens de pensée des tours précédents)
• Tokens de sortie (facturés) : Les tokens de pensée originaux que Claude a générés en interne
• Tokens de sortie (visibles) : Les tokens de pensée résumés que vous voyez dans la réponse
• Aucun frais : Tokens utilisés pour générer le résumé

Le nombre de tokens de sortie facturés ne correspondra pas au nombre de tokens visibles dans la réponse. Vous êtes facturé pour le processus de pensée complet, pas le résumé que vous voyez.

Meilleures pratiques et considérations pour la pensée étendue

Travailler avec les budgets de pensée

• Optimisation du budget : Le budget minimum est de 1 024 tokens. Nous suggérons de commencer au minimum et d’augmenter le budget de pensée de manière incrémentale pour trouver la plage optimale pour votre cas d’usage. Des comptes de tokens plus élevés permettent un raisonnement plus complet mais avec des rendements décroissants selon la tâche. Augmenter le budget peut améliorer la qualité de la réponse au compromis d’une latence accrue. Pour les tâches critiques, testez différents paramètres pour trouver l’équilibre optimal. Notez que le budget de pensée est un objectif plutôt qu’une limite stricte—l’utilisation réelle de tokens peut varier selon la tâche.
• Points de départ : Commencez avec des budgets de pensée plus importants (16k+ tokens) pour les tâches complexes et ajustez selon vos besoins.
• Gros budgets : Pour les budgets de pensée au-dessus de 32k, nous recommandons d’utiliser le traitement par lots pour éviter les problèmes de réseau. Les demandes poussant le modèle à penser au-dessus de 32k tokens causent des demandes de longue durée qui pourraient se heurter aux timeouts système et aux limites de connexion ouverte.
• Suivi de l’utilisation de tokens : Surveillez l’utilisation de tokens de pensée pour optimiser les coûts et les performances.

Considérations de performance

• Temps de réponse : Préparez-vous à des temps de réponse potentiellement plus longs dus au traitement supplémentaire requis pour le processus de raisonnement. Tenez compte que générer des blocs de pensée peut augmenter le temps de réponse global.
• Exigences de diffusion : La diffusion est requise quand max_tokens est supérieur à 21 333. Lors de la diffusion, préparez-vous à gérer à la fois les blocs de contenu de pensée et de texte à mesure qu’ils arrivent.

Compatibilité des fonctionnalités

• La pensée n’est pas compatible avec les modifications de temperature ou top_k ainsi qu’avec l’utilisation forcée d’outils.
• Quand la pensée est activée, vous pouvez définir top_p à des valeurs entre 1 et 0,95.
• Vous ne pouvez pas pré-remplir les réponses quand la pensée est activée.
• Les changements au budget de pensée invalident les préfixes de prompt mis en cache qui incluent des messages. Cependant, les prompts système mis en cache et les définitions d’outils continueront de fonctionner quand les paramètres de pensée changent.

Directives d’utilisation

• Sélection de tâche : Utilisez la pensée étendue pour des tâches particulièrement complexes qui bénéficient d’un raisonnement étape par étape comme les mathématiques, le codage, et l’analyse.
• Gestion du contexte : Vous n’avez pas besoin de supprimer les blocs de pensée précédents vous-même. L’API Anthropic ignore automatiquement les blocs de pensée des tours précédents et ils ne sont pas inclus lors du calcul de l’utilisation du contexte.
• Ingénierie de prompt : Consultez nos conseils de prompting pour la pensée étendue si vous voulez maximiser les capacités de pensée de Claude.

Prochaines étapes

Essayez le cookbook de pensée étendue

Explorez des exemples pratiques de pensée dans notre cookbook.

Conseils de prompting pour la pensée étendue

Apprenez les meilleures pratiques d’ingénierie de prompt pour la pensée étendue.