Budgets de tâche

Les « task budgets » (budgets de tâche) vous permettent d'indiquer à Claude combien de tokens il dispose pour une boucle agentique complète, incluant la réflexion, les appels d'outils, les résultats d'outils et la sortie. Le modèle voit un compte à rebours en temps réel 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 workflows agentiques où Claude effectue plusieurs appels d'outils et prend plusieurs décisions avant de finaliser sa sortie en attendant la prochaine réponse humaine. Utilisez-les lorsque :

• Vous souhaitez que Claude autorégule sa consommation 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 les résultats, rendre compte de l'avancement) lorsqu'il approche du budget plutôt que de s'interrompre en pleine action.

Les budgets de tâche complètent le paramètre effort : l'effort contrôle la rigueur avec laquelle Claude raisonne à chaque étape, tandis que les budgets de tâche plafonnent le travail total que Claude peut effectuer sur l'ensemble 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",
    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 sur l'ensemble de la boucle agentique, incluant la réflexion, les appels d'outils, les résultats d'outils et la sortie.
• remaining (facultatif) : le reste du budget reporté d'une requête précédente. Prend la valeur de 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 actuelle 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 réguler son rythme et terminer proprement à mesure que le budget est consommé.



Exemple détaillé : comptage du budget sur plusieurs tours

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 grossit tour après tour, mais le budget ne se décrémente que des tokens que Claude voit à ce tour.

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

Tour 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 tour de l'assistant (réflexion plus 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.

Tour 2. Votre client exécute l'outil, puis renvoie l'historique complet avec le résultat de l'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 utilisateur et assistant du tour 1 renvoyés ne sont pas comptés à nouveau, mais le résultat d'outil de 2 800 tokens est un nouveau contenu que Claude voit à ce tour et qui compte dans 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.

Tour 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 final de résultats de 6 000 tokens et s'arrête avec stop_reason: "end_turn". remaining ≈ 81 000.

La mise en parallèle des trois tours rend explicite la distinction entre la taille de la charge utile et la consommation du budget :

Votre client a envoyé le message utilisateur du tour 1 trois fois et le message assistant du tour 1 deux fois, mais chacun n'a été compté qu'une seule fois. Le budget a consommé 19 000 des 100 000 tokens, même si la charge utile cumulée transmise par votre client était plus importante et que l'entrée mise en cache des prompts aux tours 2 et 3 l'était encore davantage.



Reporter un budget après compaction avec remaining

Si votre boucle agentique compacte ou réécrit le contexte entre les requêtes (par exemple, en résumant les tours précédents), le serveur n'a aucune mémoire de la quantité de budget dépensée avant la compaction. Passez remaining dans la requête suivante afin que le compte à rebours reprenne là où vous vous étiez arrêté plutôt que de se réinitialiser à total :

# Jetons 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,
    },
}

Pour les boucles qui renvoient l'historique complet non compacté à chaque tour, 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 la demande, définissez un nouveau task_budget dans output_config sur 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 sous 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, pas 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 appliquée 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 sur le coût ou la latence, combinez les budgets de tâche avec une valeur max_tokens raisonnable :

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

Étant donné que 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'est pas tenue d'ê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",
    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) pour 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 consommation de tokens par tâche pour comprendre comment fournir au modèle un budget de tâche pourrait modifier son comportement, puis testez à la hausse ou à la baisse selon les besoins.

Le minimum accepté pour task_budget.total est spécifique au modèle ; sur chaque modèle qui prend actuellement en charge les budgets de tâche (voir Prise en charge de la fonctionnalité), il est de 20 000 tokens, et les valeurs inférieures au minimum renvoient une erreur 400.



Interaction avec d'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 (pouvant s'étendre sur de nombreuses requêtes). À un effort xhigh ou max, définissez max_tokens à au moins 64k pour donner à Claude la marge nécessaire pour réfléchir et agir à chaque requête.
• Effort : L'effort contrôle la profondeur avec laquelle Claude raisonne à chaque étape. Les budgets de tâche contrôlent la quantité totale de travail que Claude effectue sur 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 diminue naturellement à mesure que le budget s'épuise.
• Mise en cache des prompts : Le marqueur de compte à rebours du budget est injecté côté serveur à chaque tour, il ne correspond donc 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 sur la requête initiale et laissez le modèle s'autoréguler en fonction du compte à rebours côté serveur plutôt que de modifier le budget côté client.



Prise en charge de la fonctionnalité

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



Étapes suivantes