Task Budgets — des plafonds de tokens consultatifs qui font terminer les agents avec élégance

Avancé

What you'll learn

Comprendre ce qu'est un task budget — un décompte de tokens consultatif, visible par le modèle, sur toute une boucle agentique
Configurer task_budget correctement — dans output_config, avec l'en-tête bêta task-budgets-2026-03-13, sur un modèle pris en charge
Savoir ce qui se déduit réellement du budget (les tokens que Claude voit à ce tour) par opposition à ce qui ne compte pas (la charge répétée de l'historique renvoyé)
Choisir une taille de budget qui aide plutôt qu'elle ne déclenche un comportement proche du refus — mesurer d'abord, puis régler généreusement
Reporter un budget à travers la compaction avec le champ remaining, et éviter le piège d'invalidation de la mise en cache des prompts
Distinguer task budgets, session budgets, effort et max_tokens — quatre leviers, quatre rôles différents

Les agents à long horizon consomment des tokens de façons difficiles à prédire de l'extérieur. Une seule requête qui se déploie en une douzaine de tours de réflexion et d'appels d'outils peut discrètement coûter 10× ce que coûte votre tour habituel. Les task budgets sont la réponse d'Anthropic : donnez à Claude un plafond de tokens consultatif pour toute la boucle agentique et laissez le modèle s'autoréguler — doser sa réflexion, prioriser ses actions et conclure par un résumé à mesure que le budget s'épuise, au lieu de se faire couper au milieu d'un appel d'outil par max_tokens.

Deux choses distinguent les task budgets de tous les autres leviers de coût que vous connaissez peut-être déjà :

Le décompte est visible par le modèle. Claude voit un marqueur « tokens restants » injecté côté serveur et ajuste son comportement en conséquence. Votre client ne voit jamais ce marqueur dans un champ d'usage.
Il est consultatif, pas imposé. Les task budgets sont un indice souple ; le plafond dur reste max_tokens. C'est une fonctionnalité — Claude peut occasionnellement dépasser le budget si interrompre une action en cours serait plus perturbant que de la terminer.

Comment fonctionne le décompte du budget

Le décompte reflète les tokens que Claude a traités dans cette boucle — réflexion, appels d'outils, résultats d'outils et sortie — pas la taille de la charge utile de votre requête. Quand votre client renvoie toute la conversation à chaque tour, la charge utile croît de façon monotone mais le budget ne se décrémente que de ce qui est nouveau pour Claude à ce tour.

Watch out

Le décompte n'est visible que par le modèle. Les réponses de l'API n'incluent pas de champ de budget restant — pas d'entrée task_budget dans usage, pas d'accesseur SDK pour cela. Pour suivre la dépense côté client, additionnez output_tokens sur les requêtes de votre boucle.
Si votre client envoie tout l'historique à chaque relance ET décrémente remaining en même temps, le modèle voit un budget sous-évalué et conclut plus tôt que le budget ne le permet réellement. Fixez un budget généreux et laissez le modèle s'autoréguler contre le décompte côté serveur.

Lancez votre première requête budgétée

Guided walkthrough1 of 4

Ajoutez anthropic-beta: task-budgets-2026-03-13 à la requête. Sans lui, output_config.task_budget est ignoré.

Requête minimale — budgéter un agent de revue de code à 64k tokens

curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: task-budgets-2026-03-13" \
-H "content-type: application/json" \
-d '{
  "model": "claude-opus-5",
  "max_tokens": 128000,
  "stream": true,
  "messages": [{
    "role": "user",
    "content": "Review the codebase and propose a refactor plan."
  }],
  "output_config": {
    "effort": "high",
    "task_budget": {"type": "tokens", "total": 64000}
  }
}'

Quels modèles le prennent réellement en charge

Modèle	Prise en charge
Claude Opus 5	Bêta — définir `task-budgets-2026-03-13`
Claude Fable 5	Bêta — définir `task-budgets-2026-03-13`
Claude Mythos 5	Bêta — définir `task-budgets-2026-03-13`
Claude Sonnet 5	Non pris en charge
Claude Opus 4.8	Bêta — définir `task-budgets-2026-03-13`
Claude Opus 4.7	Bêta — définir `task-budgets-2026-03-13`
Claude Opus 4.6	Non pris en charge
Claude Sonnet 4.6	Non pris en charge
Claude Haiku 4.5	Non pris en charge

Les task budgets ne sont pas pris en charge sur Claude Code ni sur les surfaces Cowork — utilisez-les directement via l'API Messages sur l'un des modèles pris en charge. S'il vous faut plutôt un plafond dur en dollars sur une session Managed Agents, c'est une fonctionnalité distincte : Budgets de session Managed Agents.

Choisir un budget — mesurez d'abord, ne devinez pas

Le bon budget dépend de la quantité de travail que fait actuellement votre boucle. La recommandation d'Anthropic elle-même : mesurez d'abord, puis réglez.

Guided walkthrough1 of 3

Pour chaque tâche de l'échantillon, additionnez usage.output_tokens sur toutes les requêtes de la boucle, plus la taille en tokens de tous les résultats d'outils que vous avez ajoutés entre les requêtes. C'est le total que le modèle a vu.

Watch out

Un budget trop petit pour la tâche peut provoquer un comportement proche du refus. Quand Claude voit un budget clairement insuffisant pour le travail (disons 20 000 tokens pour une tâche de codage agentique de plusieurs heures), il peut refuser de tenter la tâche, en réduire agressivement le périmètre, ou s'arrêter tôt avec un résultat partiel — plutôt que d'entamer un travail qu'il ne peut pas finir.
Si vous observez des refus inattendus ou des arrêts prématurés après avoir ajouté un budget, augmentez le budget avant de déboguer d'autres paramètres. Dimensionnez contre votre distribution réelle de longueur de tâche, pas contre une valeur par défaut fixe.

Reporter un budget à travers la compaction

Si votre boucle compacte ou réécrit le contexte entre les requêtes — par exemple en résumant les tours antérieurs pour réduire la charge utile — le serveur n'a aucune mémoire du budget dépensé avant la compaction. Passez remaining sur la requête suivante pour que le décompte reprenne là où vous l'avez laissé :

Python — reporter remaining à travers la compaction

# Tokens spent before compaction, tracked client-side
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 tout l'historique non compacté à chaque tour, omettez remaining et laissez le serveur suivre le décompte. Le définir manuellement quand ce n'est pas nécessaire invite une dérive entre ce que votre client croit avoir dépensé et ce que Claude a réellement vu.

Interactions avec les autres paramètres

Interagit avec	Comment l'interaction se joue
`max_tokens`	Orthogonal. `max_tokens` est un plafond dur par requête ; `task_budget` est un plafond consultatif sur toute la boucle. Aucun des deux n'a besoin d'être inférieur ou égal à l'autre. Combinez-les : `task_budget` donne à Claude une cible sur laquelle se cadencer, `max_tokens` empêche une génération incontrôlée sur une requête donnée.
Effort	Complémentaire. L'effort contrôle la profondeur du raisonnement de Claude à chaque étape (ampleur de la réflexion). Les task budgets contrôlent la quantité totale de travail que la boucle peut accomplir (ampleur de l'itération). Réglez les deux ensemble.
Réflexion adaptative	Les task budgets incluent les tokens de réflexion dans le décompte, donc la réflexion adaptative se réduit naturellement à mesure que le budget s'épuise.
Mise en cache des prompts	Piège d'invalidation du cache. Le marqueur de décompte du budget est injecté à chaque tour et ne correspond pas d'une requête à l'autre. Si votre client décrémente `task_budget.remaining` à chaque relance, la valeur modifiée invalide tout préfixe de cache qui la contient. Fixez le budget une seule fois sur la requête initiale et laissez le modèle s'autoréguler.

Task budget face aux autres budgets

Ailmanac couvre déjà trois fonctionnalités en forme de « budget ». Elles ne sont pas interchangeables.

Fonctionnalité	Unité	Portée	Application	En-tête nécessaire
Task budgets (cette page)	Tokens	Une boucle agentique (possiblement plusieurs requêtes)	Consultative — indice souple au modèle	`anthropic-beta: task-budgets-2026-03-13`
`max_tokens`	Tokens	Une requête	Dure — tronque avec `stop_reason: max_tokens`	Aucun
`output_config.effort`	Niveau d'effort	Profondeur par étape	Consultative (contrôlée par le modèle)	Aucun
Budgets de session Managed Agents	Cents US	Toute une session Managed Agents	Dure — le serveur met en pause à `budget_reached`	En-têtes bêta Managed Agents

Voyez les choses ainsi : max_tokens est un fusible (il saute à un point fixe), le task budget est un coach qui souffle le score à Claude (il ajuste son jeu), l'effort est le style de jeu, et le budget de session est le comptable qui fait respecter le plafond de masse salariale. Utilisez les quatre ensemble quand il vous faut des agents bornés, autorégulés et plafonnés en dollars.

Testez-vous

Check yourself

0/3

Vous fixez task_budget.total à 100000 sur un agent d'audit de code. Pendant l'exécution, la charge utile cumulée de votre client atteint 250000 tokens sur l'ensemble des requêtes parce que vous renvoyez tout l'historique à chaque tour. Que fait le décompte que Claude voit à la fin ?
Vous compactez le contexte entre les requêtes. Pour être sûr que le décompte ne se réinitialise pas, que faites-vous ?
Vous fixez task_budget.total à 20000 pour une longue tâche de codage agentique, et Claude refuse soudainement ou s'arrête tôt avec un résultat partiel. Quel est le correctif ?

Vocabulaire

Glossaire des task budgets

Appuyez sur Entrée ou Espace pour retourner la carte. Utilisez les flèches gauche et droite pour naviguer entre les cartes.Terme affiché.

1 / 6

À retenir

Key takeaways

Les task budgets sont un décompte de tokens VISIBLE PAR LE MODÈLE et CONSULTATIF sur toute la boucle agentique — Claude s'autorégule contre lui
Activez-les avec l'en-tête bêta task-budgets-2026-03-13 sur un modèle pris en charge — Opus 5, Fable 5, Mythos 5, Opus 4.8 ou Opus 4.7. Sonnet, Haiku et Claude Code ne le prennent pas en charge
Le décompte compte les tokens QUE CLAUDE VOIT à ce tour — pas la taille de la charge utile renvoyée — donc l'historique répété n'est pas facturé deux fois
Mesurez d'abord (le p99 de votre distribution de tokens par tâche), puis réglez généreusement. Des budgets sous-dimensionnés provoquent un comportement proche du refus
Utilisez remaining pour reporter le budget à travers la compaction ; omettez-le quand vous renvoyez un historique non compacté et laissez le serveur suivre
Associez-le à max_tokens pour un fusible dur et à l'effort pour régler la profondeur par étape — quatre leviers qui remplissent quatre rôles différents

Pour aller plus loin

Réglage de l'effort — les cinq niveaux d'effort et leur interaction avec les task budgets
Budgets de session Managed Agents — plafonds durs en dollars sur une session, imposés par la plateforme
Mise en cache des prompts — comment le piège d'invalidation du cache se manifeste avec des valeurs de budget mutantes
Outil d'exécution de code — le runtime en bac à sable sur lequel s'appuient souvent les agents longs
Construire des agents sur Claude — le cycle de vie complet de la boucle agentique que ces budgets façonnent

Partager cette page

Comment fonctionne le décompte du budget​

Lancez votre première requête budgétée​

Requête minimale — budgéter un agent de revue de code à 64k tokens

Quels modèles le prennent réellement en charge​

Choisir un budget — mesurez d'abord, ne devinez pas​

Reporter un budget à travers la compaction​

Python — reporter remaining à travers la compaction

Interactions avec les autres paramètres​

Task budget face aux autres budgets​

Testez-vous​