Budgets de tâches

Les budgets de tâches vous permettent de dire à Claude combien de jetons il a pour une boucle agentic 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 gracieusement à mesure que le budget est consommé.

Quand utiliser les budgets de tâches

Les budgets de tâches fonctionnent mieux pour les flux de travail agentic où Claude effectue plusieurs appels d'outils et prend des décisions avant de finaliser sa sortie pour attendre la prochaine réponse humaine. Utilisez-les quand :

• Vous voulez que Claude s'auto-régule sur la dépense de jetons pour les tâches à long terme.
• Vous avez un coût ou un plafond de latence prévisible par tâche à appliquer.
• Vous voulez que le modèle termine gracieusement (résumer les résultats, signaler la progression) à mesure qu'il approche du budget plutôt que de s'arrêter au milieu d'une action.

Les budgets de tâches complètent le paramètre effort : l'effort contrôle la profondeur du raisonnement de Claude sur chaque étape, tandis que les budgets de tâches limitent le travail total que Claude peut faire dans une boucle agentic.

Définir un budget de tâche

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

L'objet task_budget a trois champs :

• type : toujours "tokens".
• total : le nombre de jetons que Claude peut dépenser dans la boucle agentic complète, 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 demande antérieure. Par défaut à total quand 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 jetons restent dans la boucle agentic actuelle et se met à jour à mesure que le modèle génère la réflexion, les appels d'outils et la sortie, et à mesure qu'il traite les résultats d'outils. Claude utilise ce signal pour se cadencer et terminer gracieusement à mesure que le budget est consommé.

Exemple travaillé : comptage du budget entre les tours

Le budget de tâche compte ce que Claude voit (réflexion, appels d'outils et résultats, et texte), pas ce qui se trouve dans votre charge utile de demande. Dans une boucle agentic, votre client renvoie la conversation complète à chaque demande, donc la charge utile augmente tour après tour, mais le budget ne décrémente que par les jetons 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 demande 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 assistant (réflexion plus l'appel d'outil) totalise 5 000 jetons 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 de l'outil de 2 800 jetons est un nouveau contenu que Claude voit ce tour et qui compte contre le budget. Claude dépense 4 000 jetons supplémentaires sur la 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 jetons de sortie grep) ajouté. Claude rédige un rapport de résultats final de 6 000 jetons et s'arrête avec stop_reason: "end_turn". remaining ≈ 81 000.

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

Votre client a envoyé le message utilisateur du tour 1 trois fois et le message assistant du tour 1 deux fois, mais chacun a été compté une fois. Le budget a dépensé 19 000 des 100 000 jetons, même si la charge utile cumulative que votre client a transmise était plus grande et l'entrée mise en cache par le prompt sur les tours 2 et 3 était encore plus grande.

Transporter un budget entre la compaction avec remaining

Si votre boucle agentic compacte ou réécrit le contexte entre les demandes (par exemple, en résumant les tours antérieurs), le serveur n'a aucune mémoire du budget dépensé avant la compaction. Passez remaining à la demande suivante pour que le compte à rebours continue à partir de là où vous l'aviez laissé plutôt que de réinitialiser à total :

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âches sont consultatifs, non appliqués

Les budgets de tâches sont une indication douce, pas un plafond dur. Claude peut occasionnellement dépasser le budget s'il est au milieu d'une action qui serait plus perturbatrice à interrompre qu'à terminer. La limite appliquée sur le nombre total de jetons de sortie est toujours max_tokens, qui tronque la réponse avec stop_reason: "max_tokens" quand elle est atteinte.

Pour un plafond dur sur le coût ou la latence, combinez les budgets de tâches avec une valeur max_tokens raisonnable :

• Utilisez task_budget pour donner à Claude une cible pour se cadencer.
• Utilisez max_tokens comme plafond absolu qui empêche la génération incontrôlée.

Parce que task_budget s'étend sur la boucle agentic complète (potentiellement de nombreuses demandes) tandis que max_tokens limite chaque demande individuelle, les deux valeurs sont indépendantes ; l'une n'est pas requise d'être à ou en dessous de l'autre.

Choisir un budget

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

Mesurez votre utilisation actuelle

Exécutez un échantillon représentatif de tâches sans task_budget défini et enregistrez le nombre total de jetons que Claude dépense par tâche. Pour une boucle agentic, additionnez usage.output_tokens plus les jetons de réflexion et de résultat d'outil à travers chaque demande dans la boucle :

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

Le task_budget.total minimum accepté est 20 000 jetons ; les valeurs en dessous du minimum retournent une erreur 400.

Interaction avec d'autres paramètres

• max_tokens : Orthogonal aux budgets de tâches. max_tokens est un plafond dur par demande sur les jetons générés, tandis que task_budget est un plafond consultatif sur la boucle agentic complète (potentiellement s'étendant sur de nombreuses demandes). À xhigh ou max effort, définissez max_tokens à au moins 64k pour donner à Claude de la place pour réfléchir et agir à chaque demande.
• Effort : L'effort contrôle la profondeur du raisonnement de Claude par étape. Les budgets de tâches contrôlent la quantité totale de travail que Claude fait dans une boucle agentic. Les deux sont complémentaires : l'effort règle la profondeur, les budgets de tâches règlent la largeur.
• Réflexion adaptative : Les budgets de tâches incluent les jetons 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 invites : Le marqueur de compte à rebours du budget est injecté côté serveur par tour, donc il ne correspond pas entre les demandes. Si votre client décrémente task_budget.remaining à chaque demande 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 fois à la demande initiale et laissez le modèle s'auto-réguler par rapport au compte à rebours côté serveur plutôt que de muter le budget côté client.

Support des fonctionnalités

Les budgets de tâches ne sont pas supportés sur les surfaces Claude Code ou Cowork au lancement. Utilisez les budgets de tâches directement via l'API Messages sur Claude Opus 4.7.