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, 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 cours 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 mieux pour les flux de travail agentiques où Claude effectue plusieurs appels d'outils et décisions avant de finaliser sa sortie en attendant la prochaine réponse humaine. Utilisez-les lorsque :

• Vous voulez 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 voulez que le modèle termine proprement (résumer les résultats, rapporter la 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 : effort contrôle la profondeur 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-4-8",
    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 (optionnel) : le reste du budget reporté d'une requête précédente. Par défaut égal à total lorsqu'il est omis.



Comment fonctionne le 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 se rythmer et terminer proprement à mesure que le budget est consommé.



Exemple détaillé : décompte du budget à travers les tours

Le budget de tâche compte ce que Claude voit (réflexion, appels et résultats d'outils, et texte), pas 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, donc la charge utile croît tour après tour, mais le budget ne se décrémente que des tokens que Claude voit à ce tour.

Considérez 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 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.

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 user 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 est décompté du budget. Claude dépense encore 4 000 tokens en réflexion et un second 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 second 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.

Mettre les trois tours 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 user 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 dépensé 19 000 tokens sur 100 000, même si la charge utile cumulée transmise par votre client était plus grande et que l'entrée mise en cache des prompts aux tours 2 et 3 était encore plus grande.



Reporter un budget à travers la 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. Transmettez remaining à la requête suivante afin que le compte à rebours continue là où vous vous étiez arrêté plutôt que de se réinitialiser à total :

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.



Les budgets de tâche sont consultatifs, pas imposés

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 imposé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 se rythmer.
• Utilisez max_tokens comme plafond absolu qui empêche une génération incontrôlée.

Comme task_budget couvre la boucle agentique complète (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 égale ou inférieure à 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 existante de tokens, 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 plus les tokens de réflexion et de résultats d'outils à travers chaque requête de la boucle :

def run_task_and_count_tokens(messages: list) -> int:
    """Runs an agentic loop to completion and returns total tokens spent."""
    total_spend = 0
    while True:
        with client.beta.messages.stream(
            model="claude-opus-4-8",
            max_tokens=128000,
            messages=messages,
            tools=tools,
            betas=["task-budgets-2026-03-13"],
        ) as stream:
            response = stream.get_final_message()
        # Compte ce que Claude a généré à ce tour (la sortie couvre le texte + la réflexion + les appels d'outils).
        # Les tokens de résultats d'outils comptent aussi dans le budget ; ajoutez le nombre de tokens des
        # blocs tool_result que vous ajoutez ci-dessous si vous voulez que le suivi côté client corresponde
        # au décompte côté serveur.
        total_spend += response.usage.output_tokens
        if response.stop_reason == "end_turn":
            return total_spend
        # Ajoutez le tour de l'assistant et vos résultats d'outils, puis continuez la boucle.
        messages += [
            {"role": "assistant", "content": response.content},
            {"role": "user", "content": run_tools(response.content)},
        ]

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

Le minimum accepté pour task_budget.total est de 20 000 tokens ; 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 consultatif sur la boucle agentique complète (pouvant s'étendre sur de nombreuses requêtes). À l'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 : 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 : effort règle la profondeur, les budgets de tâche règlent l'étendue.
• Réflexion adaptative : Les budgets de tâche 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 : Le marqueur de compte à rebours du budget est injecté côté serveur à chaque tour, il ne correspond donc pas entre les requêtes. 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 par rapport au 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 Claude Code ou les surfaces Cowork. Utilisez les budgets de tâche directement via l'API Messages sur un modèle pris en charge.