Budgets de tâche

Les « task budgets » (budgets de tâche) vous permettent d'indiquer à Claude le nombre de tokens dont il dispose pour une boucle agentique complète, y compris la réflexion, les appels d'outils, les résultats d'outils et la sortie. Le modèle voit un compte à rebours en continu et l'utilise pour prioriser le travail et terminer proprement à mesure que le budget est consommé.

Quand utiliser les budgets de tâche

Les budgets de tâche fonctionnent le mieux pour les flux de travail agentiques dans lesquels Claude effectue plusieurs appels d'outils et prend plusieurs décisions avant de finaliser sa sortie pour attendre la prochaine réponse humaine. Utilisez-les lorsque :

• Vous souhaitez que Claude autorégule sa dépense de tokens sur des tâches à long horizon.
• Vous avez un plafond prévisible de coût ou de latence par tâche à faire respecter.
• Vous souhaitez que le modèle termine proprement (résumer ses conclusions, rendre compte de sa progression) à l'approche du budget plutôt que de s'interrompre au milieu d'une action.

Les budgets de tâche complètent le paramètre effort : l'effort contrôle la minutie avec laquelle Claude raisonne à chaque étape, tandis que les budgets de tâche plafonnent le travail total que Claude peut effectuer au cours d'une boucle agentique.

Définir un budget de tâche

Ajoutez task_budget à output_config et incluez l'en-tête bêta :

client = anthropic.Anthropic()

with client.beta.messages.stream(
    model="claude-opus-5-5",
    max_tokens=128000,
    output_config={
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 64000},
    },
    messages=[
        {"role": "user", "content": "Review the codebase and propose a refactor plan."}
    ],
    betas=["task-budgets-2026-03-13"],
) as stream:
    response = stream.get_final_message()

print(response.usage)

L'objet task_budget comporte trois champs :

• type : toujours "tokens".
• total : le nombre de tokens que Claude peut dépenser au cours de la boucle agentique, y compris la réflexion, les appels d'outils, les résultats d'outils et la sortie.
• remaining (facultatif) : le reliquat de budget reporté depuis une requête précédente. Vaut total par défaut lorsqu'il est omis.

Fonctionnement du compte à rebours du budget

Claude voit un marqueur de compte à rebours du budget injecté côté serveur tout au long de la conversation. Le marqueur indique combien de tokens restent dans la boucle agentique en cours et se met à jour à mesure que le modèle génère de la réflexion, des appels d'outils et de la sortie, et à mesure qu'il traite les résultats d'outils. Claude utilise ce signal pour doser son rythme et terminer proprement à mesure que le budget est consommé.

Ce qui compte comme un tour

Le budget couvre un tour agentique, également appelé boucle agentique : tout ce que Claude fait en réponse à un message utilisateur qui ne contient aucun résultat d'outil. Un tour peut s'étendre sur plusieurs requêtes.

Un message utilisateur qui ne contient aucun résultat d'outil démarre un nouveau tour avec un budget neuf. Aujourd'hui, le compte à rebours compte toujours l'historique des tours précédents tant qu'il reste dans le contexte. Un cas courant est un suivi après que Claude a terminé son tour, par exemple parce que le budget était épuisé :

{ "role": "user", "content": "Continue." }

Un message utilisateur qui contient des blocs tool_result poursuit le tour actuel, car votre client résout des appels d'outils qui font partie de ce tour :

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01", "content": "<npm audit output>" }
  ]
}

Cela reste vrai même lorsque le message ajoute du nouveau contenu à côté des résultats d'outils :

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01", "content": "<npm audit output>" },
    { "type": "text", "text": "Also check the Dockerfile." }
  ]
}

La compaction côté serveur pendant un tour ne réinitialise pas le budget : les tokens consommés par le tour avant la compaction continuent d'être décomptés. Les tokens antérieurs au début du tour ne sont pas comptés, même lorsqu'une compaction au début d'un tour les résume. Aujourd'hui, cette exclusion ne s'applique qu'au budget reporté à travers une compaction côté serveur ; l'historique des tours précédents est toujours compté tant qu'il reste dans le contexte.

Exemple concret : comptage du budget à travers les requêtes

Le budget de tâche compte ce que Claude voit (réflexion, appels et résultats d'outils, et texte), et non ce qui se trouve dans la charge utile de votre requête. Dans une boucle agentique, votre client renvoie la conversation complète à chaque requête, de sorte que la charge utile continue de croître, mais le budget ne décrémente que de ce qui est nouveau : les tokens que Claude génère et le contenu qu'il n'a pas vu auparavant. L'exemple suivant est un tour agentique composé de trois requêtes : la première porte le message utilisateur, et les deux suivantes renvoient chacune l'historique avec un résultat d'outil ajouté.

Considérons une boucle avec task_budget: {type: "tokens", total: 100000} et un seul outil bash.

Requête 1. Vous envoyez la requête initiale :

{
  "messages": [
    { "role": "user", "content": "Audit this repo for security issues and report findings." }
  ]
}

Claude réfléchit, puis émet un appel d'outil et s'arrête avec stop_reason: "tool_use" :

{
  "role": "assistant",
  "content": [
    {
      "type": "thinking",
      "thinking": "I'll start by listing dependencies to look for known-vulnerable packages..."
    },
    {
      "type": "tool_use",
      "id": "toolu_01",
      "name": "bash",
      "input": { "command": "cat package.json && npm audit --json" }
    }
  ]
}

Supposons que ce message de l'assistant (réflexion plus l'appel d'outil) totalise 5 000 tokens générés. Le compte à rebours que Claude a vu pendant la génération s'est terminé près de remaining ≈ 95 000.

Requête 2. Votre client exécute l'outil, puis renvoie l'historique complet avec le résultat d'outil ajouté :

{
  "messages": [
    { "role": "user", "content": "Audit this repo for security issues and report findings." },
    {
      "role": "assistant",
      "content": [
        { "type": "thinking", "thinking": "I'll start by listing dependencies..." },
        {
          "type": "tool_use",
          "id": "toolu_01",
          "name": "bash",
          "input": { "command": "cat package.json && npm audit --json" }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_01",
          "content": "<2,800 tokens of npm audit output>"
        }
      ]
    }
  ]
}

Les messages renvoyés de la requête 1 ne sont pas comptés à nouveau, mais le résultat d'outil de 2 800 tokens est du nouveau contenu et compte contre le budget. Claude dépense 4 000 tokens supplémentaires en réflexion et un deuxième appel d'outil (grep -rn "eval(" src/). Le compte à rebours se termine près de remaining ≈ 88 200.

Requête 3. L'historique complet est renvoyé à nouveau avec le deuxième résultat d'outil (1 200 tokens de sortie grep) ajouté. Claude rédige un rapport de conclusions final de 6 000 tokens et s'arrête avec stop_reason: "end_turn". remaining ≈ 81 000.

Mettre les trois requêtes côte à côte rend explicite la distinction entre la taille de la charge utile et la dépense du budget :

Votre client a envoyé le message utilisateur d'origine trois fois et le premier message de l'assistant deux fois, mais chacun a été compté une seule fois. Le budget a dépensé 19 000 des 100 000 tokens, même si la charge utile cumulée que votre client a transmise était plus importante et que l'entrée mise en cache via le prompt sur les requêtes 2 et 3 était encore plus importante.

Reporter un budget après compaction avec remaining

Si votre propre code compacte ou réécrit l'historique des messages entre les requêtes (par exemple, en résumant les messages antérieurs), le serveur n'a aucune mémoire de la quantité de budget dépensée avant la compaction. Transmettez remaining à la requête suivante afin que le compte à rebours continue là où vous l'avez laissé plutôt que de se réinitialiser à total :

# Tokens dépensés avant la compaction, suivis côté client
tokens_spent_so_far = 45000

output_config = {
    "effort": "high",
    "task_budget": {
        "type": "tokens",
        "total": 128000,
        "remaining": 128000 - tokens_spent_so_far,
    },
}

Dans cet exemple, les tokens dépensés avant la compaction correspondent à l'utilisation de tous les messages que vous avez retirés de l'historique jusqu'à présent, mesurée comme dans Mesurer votre utilisation actuelle. Laissez de côté tout ce qui est encore présent dans les messages que vous envoyez, y compris tout résumé que vous avez ajouté, car le serveur compte ces tokens lui-même. Mettez à jour ce chiffre uniquement lorsque vous remplacez l'historique de cette manière ; ne le décrémentez pas à chaque requête. Transmettez le remaining résultant à chaque requête, pas seulement à celle qui compacte.

Pour les boucles qui renvoient l'historique complet non compacté à chaque requête, omettez remaining et laissez le serveur suivre le compte à rebours.

Modifier le budget en cours de conversation

task_budget est un paramètre au niveau de la requête. Pour modifier le budget en cours de tâche, par exemple pour l'étendre lorsque l'utilisateur élargit sa demande, définissez un nouveau task_budget dans output_config lors de la requête suivante. Gardez à l'esprit la conséquence sur la mise en cache : la valeur du budget participe au prompt rendu, de sorte qu'une valeur modifiée ne correspond pas aux entrées de cache créées avec l'ancienne valeur (voir Prise en charge de la fonctionnalité ci-dessous).

Les budgets de tâche sont indicatifs, non contraignants

Les budgets de tâche sont une indication souple, et non un plafond strict. Claude peut occasionnellement dépasser le budget s'il est au milieu d'une action qu'il serait plus perturbant d'interrompre que de terminer. La limite contraignante sur le total des tokens de sortie reste max_tokens, qui tronque la réponse avec stop_reason: "max_tokens" lorsqu'elle est atteinte.

Pour un plafond strict de coût ou de latence, combinez les budgets de tâche avec une valeur max_tokens raisonnable :

• Utilisez task_budget pour donner à Claude une cible sur laquelle régler son rythme.
• Utilisez max_tokens comme plafond absolu qui empêche une génération incontrôlée.

Comme task_budget couvre l'ensemble de la boucle agentique (potentiellement de nombreuses requêtes) tandis que max_tokens plafonne chaque requête individuelle, les deux valeurs sont indépendantes ; l'une n'a pas à être inférieure ou égale à l'autre.

Choisir un budget

Le bon budget dépend de la quantité de travail que votre boucle agentique effectue actuellement. Plutôt que de deviner, mesurez d'abord votre utilisation de tokens existante, puis ajustez à partir de là.

Mesurer votre utilisation actuelle

Exécutez un échantillon représentatif de tâches sans définir task_budget et enregistrez le total de tokens que Claude dépense par tâche. Pour une boucle agentique, additionnez usage.output_tokens sur chaque requête de la boucle, plus les tokens des résultats d'outils que vous ajoutez entre les requêtes :

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Review the codebase and propose a refactor plan."}
    ],
)

# Additionnez les output_tokens (texte + réflexion + appels d'outils) de chaque requête de votre boucle.
print(response.usage.output_tokens)

Exécutez ceci sur un ensemble représentatif de tâches et enregistrez la distribution. Commencez par le p99 de votre dépense de tokens par tâche pour comprendre comment le fait de fournir un budget de tâche au modèle peut modifier son comportement, puis testez à la hausse ou à la baisse selon les besoins.

Le task_budget.total minimum accepté est de 20 000 tokens sur chaque modèle qui prend en charge les budgets de tâche (voir Prise en charge de la fonctionnalité). Les valeurs plus petites renvoient une erreur 400.

Interaction avec les autres paramètres

• max_tokens : Orthogonal aux budgets de tâche. max_tokens est un plafond strict par requête sur les tokens générés, tandis que task_budget est un plafond indicatif sur l'ensemble de la boucle agentique (s'étendant potentiellement sur de nombreuses requêtes). À un effort xhigh ou max, définissez max_tokens à au moins 64k pour donner à Claude de la marge pour réfléchir et agir à chaque requête.
• Effort : L'effort contrôle la profondeur avec laquelle Claude raisonne par étape. Les budgets de tâche contrôlent la quantité totale de travail que Claude effectue au cours d'une boucle agentique. Les deux sont complémentaires : l'effort ajuste la profondeur, les budgets de tâche ajustent l'étendue.
• Réflexion adaptative : Les budgets de tâche incluent les tokens de réflexion dans le décompte, de sorte que la réflexion adaptative se réduit à mesure que le budget s'épuise.
• Mise en cache des prompts : Le marqueur de compte à rebours du budget est injecté côté serveur à chaque requête, de sorte qu'il ne correspond pas d'une requête à l'autre. Si votre client décrémente task_budget.remaining à chaque requête de suivi, la valeur modifiée invalide tout préfixe de cache qui la contient. Pour préserver la mise en cache, définissez le budget une seule fois à la requête initiale et laissez le modèle s'autoréguler par rapport au compte à rebours côté serveur plutôt que de muter le budget côté client.

Prise en charge de la fonctionnalité

Les budgets de tâche ne sont pas pris en charge sur Claude Code ni sur les surfaces Cowork. Utilisez les budgets de tâche directement via l'API Messages sur un modèle pris en charge.

Étapes suivantes

Compatibility