---
title: Budgets de tâche
url: https://platform.claude.com/docs/fr/build-with-claude/task-budgets
description: Donnez à Claude un budget de tokens indicatif pour l'ensemble de la boucle agentique afin d'aider le modèle à s'autoréguler lors de longues tâches agentiques.
featureMetadata:
  status: beta
  betaHeader: task-budgets-2026-03-13
  supportedModels:
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-opus-5-5
    - claude-opus-5
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-sonnet-5-5
    - claude-haiku-5-5
---

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](https://platform.claude.com/docs/fr/build-with-claude/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 :

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -N \
    -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-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}
      }
    }'
  ```

  ```bash CLI
  ant beta:messages create --beta task-budgets-2026-03-13 \
    --stream --format jsonl <<'YAML' | jq 'select(.type == "message_delta").usage'
  model: claude-opus-5-5
  max_tokens: 128000
  messages:
    - role: user
      content: Review the codebase and propose a refactor plan.
  output_config:
    effort: high
    task_budget:
      type: tokens
      total: 64000
  YAML
  ```

  ```python Python
  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)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const stream = 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"]
  });

  const response = await stream.finalMessage();
  console.log(response.usage);
  ```

  ```csharp C#

  var client = new AnthropicClient();

  var responseUpdates = client.Beta.Messages.CreateStreaming(new MessageCreateParams
  {
      Model = Messages::Model.ClaudeOpus5_5,
      MaxTokens = 128000,
      Messages = [new() { Role = Role.User, Content = "Review the codebase and propose a refactor plan." }],
      OutputConfig = new BetaOutputConfig
      {
          Effort = Effort.High,
          TaskBudget = new BetaTokenTaskBudget { Total = 64000 },
      },
      Betas = ["task-budgets-2026-03-13"],
  });

  var response = await responseUpdates.Aggregate();
  Console.WriteLine(response.Usage);
  ```

  ```go Go
  client := anthropic.NewClient()

  stream := client.Beta.Messages.NewStreaming(context.TODO(), anthropic.BetaMessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 128000,
  	Betas:     []anthropic.AnthropicBeta{"task-budgets-2026-03-13"},
  	Messages: []anthropic.BetaMessageParam{{
  		Role: anthropic.BetaMessageParamRoleUser,
  		Content: []anthropic.BetaContentBlockParamUnion{{
  			OfText: &anthropic.BetaTextBlockParam{Text: "Review the codebase and propose a refactor plan."},
  		}},
  	}},
  	OutputConfig: anthropic.BetaOutputConfigParam{
  		Effort: anthropic.BetaOutputConfigEffortHigh,
  		TaskBudget: anthropic.BetaTokenTaskBudgetParam{
  			Total: 64000,
  		},
  	},
  })

  message := anthropic.BetaMessage{}
  for stream.Next() {
  	event := stream.Current()
  	if err := message.Accumulate(event); err != nil {
  		panic(err)
  	}
  }
  if stream.Err() != nil {
  	panic(stream.Err())
  }

  fmt.Printf("Usage: input_tokens=%d, output_tokens=%d\n", message.Usage.InputTokens, message.Usage.OutputTokens)
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_OPUS_5_5)
      .maxTokens(128000L)
      .addUserMessage("Review the codebase and propose a refactor plan.")
      .outputConfig(BetaOutputConfig.builder()
          .effort(BetaOutputConfig.Effort.HIGH)
          .taskBudget(BetaTokenTaskBudget.builder().total(64000L).build())
          .build())
      .addBeta("task-budgets-2026-03-13")
      .build();

  BetaMessageAccumulator accumulator = BetaMessageAccumulator.create();
  try (StreamResponse<BetaRawMessageStreamEvent> stream =
          client.beta().messages().createStreaming(params)) {
      stream.stream().forEach(accumulator::accumulate);
  }

  BetaMessage response = accumulator.message();
  IO.println(response.usage());
  ```

  ```php PHP
  use Anthropic\Beta\Messages\BetaRawMessageDeltaEvent;

  $client = new Client();

  $stream = $client->beta->messages->createStream(
      model: 'claude-opus-5-5',
      maxTokens: 128000,
      messages: [
          ['role' => 'user', 'content' => 'Review the codebase and propose a refactor plan.'],
      ],
      outputConfig: [
          'effort' => 'high',
          'taskBudget' => ['type' => 'tokens', 'total' => 64000],
      ],
      betas: ['task-budgets-2026-03-13'],
  );

  // L'événement message_delta final contient l'utilisation cumulée des tokens pour la requête.
  $usage = null;
  foreach ($stream as $event) {
      if ($event instanceof BetaRawMessageDeltaEvent) {
          $usage = $event->usage;
      }
  }

  echo $usage;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

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

  response = stream.accumulated_message

  puts response.usage
  ```
</CodeGroup>

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

<Note>
  **Le compte à rebours n'est visible que par le modèle.** Les réponses de l'API n'incluent pas de champ de budget restant : il n'y a aucune information `task_budget` dans l'objet `usage` de la réponse, et le SDK ne dispose d'aucun accesseur pour celle-ci. Pour suivre la consommation côté client, additionnez l'utilisation des tokens sur l'ensemble des requêtes de votre boucle comme indiqué dans [Mesurer votre utilisation actuelle](https://platform.claude.com/docs/fr/build-with-claude/task-budgets#measure-your-current-usage), ou transmettez votre propre valeur avec `remaining` lorsque vous [reportez un budget après compaction](https://platform.claude.com/docs/fr/build-with-claude/task-budgets#carrying-a-budget-across-compaction-with-remaining).
</Note>

<Warning>
  **Le compte à rebours reflète les tokens que Claude a traités dans la boucle agentique en cours, et non les tokens que vous renvoyez entre les requêtes.** Si votre client envoie l'historique complet de la conversation à chaque requête de suivi, votre décompte de tokens côté client peut différer du budget suivi par Claude. Si vous décrémentez également `remaining` tout en renvoyant l'historique complet, le modèle voit un budget sous-estimé et le compte à rebours diminue plus vite qu'il ne le devrait, ce qui amène Claude à conclure plus tôt que ce que le budget permet réellement. Définissez un budget généreux et laissez le modèle s'autoréguler par rapport au compte à rebours plutôt que d'essayer de le reproduire côté client.
</Warning>

### 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é :

```json
{ "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 :

```json
{
  "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 :

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

La [compaction](https://platform.claude.com/docs/fr/build-with-claude/compaction-threshold) 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](https://platform.claude.com/docs/fr/build-with-claude/task-budgets#what-counts-as-a-turn) 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 :

```json
{
  "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"` :

```json
{
  "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é :

```json
{
  "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 :

| Requête   | Charge utile de la requête (tokens d'entrée approx. que vous avez envoyés) | Tokens comptés contre le budget pour cette requête             | Budget `remaining` après |
| --------- | -------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------ |
| 1         | \~20                                                                       | 5 000 (réflexion + `tool_use`)                                 | \~95 000                 |
| 2         | \~7 800 (messages de la requête 1 + résultat d'outil)                      | 6 800 (2 800 résultat d'outil + 4 000 réflexion et `tool_use`) | \~88 200                 |
| 3         | \~13 000 (historique complet + deuxième résultat d'outil)                  | 7 200 (1 200 résultat d'outil + 6 000 `text`)                  | \~81 000                 |
| **Total** | **\~20 820 envoyés sur l'ensemble des requêtes**                           | **19 000 comptés contre le budget**                            | N/A                      |

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` :

<CodeGroup exclude="shell">
  ```python Python
  # 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,
      },
  }
  ```

  ```typescript TypeScript
  // Tokens dépensés avant la compaction, suivis côté client
  const tokensSpentSoFar = 45000;

  const outputConfig = {
    effort: "high",
    task_budget: {
      type: "tokens",
      total: 128000,
      remaining: 128000 - tokensSpentSoFar
    }
  };
  ```

  ```csharp C#
  // Tokens consommés avant la compaction, suivis côté client
  var tokensSpentSoFar = 45000;

  var outputConfig = new BetaOutputConfig
  {
      Effort = Effort.High,
      TaskBudget = new BetaTokenTaskBudget
      {
          Total = 128000,
          Remaining = 128000 - tokensSpentSoFar,
      },
  };
  ```

  ```go Go
  // Tokens dépensés avant la compaction, suivis côté client
  tokensSpentSoFar := int64(45000)

  outputConfig := anthropic.BetaOutputConfigParam{
  	Effort: anthropic.BetaOutputConfigEffortHigh,
  	TaskBudget: anthropic.BetaTokenTaskBudgetParam{
  		Total:     128000,
  		Remaining: anthropic.Int(128000 - tokensSpentSoFar),
  	},
  }
  ```

  ```java Java
  // Tokens dépensés avant la compaction, suivis côté client
  long tokensSpentSoFar = 45000;

  BetaOutputConfig outputConfig = BetaOutputConfig.builder()
      .effort(BetaOutputConfig.Effort.HIGH)
      .taskBudget(BetaTokenTaskBudget.builder()
          .total(128000L)
          .remaining(128000L - tokensSpentSoFar)
          .build())
      .build();
  ```

  ```php PHP
  // Tokens dépensés avant la compaction, suivis côté client
  $tokensSpentSoFar = 45000;

  $outputConfig = [
      'effort' => 'high',
      'taskBudget' => [
          'type' => 'tokens',
          'total' => 128000,
          'remaining' => 128000 - $tokensSpentSoFar,
      ],
  ];
  ```

  ```ruby Ruby
  # Tokens dépensés avant la compaction, suivis côté client
  tokens_spent_so_far = 45_000

  output_config = {
    effort: :high,
    task_budget: {
      type: :tokens,
      total: 128_000,
      remaining: 128_000 - tokens_spent_so_far
    }
  }
  ```
</CodeGroup>

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](https://platform.claude.com/docs/fr/build-with-claude/task-budgets#measure-your-current-usage). 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é](https://platform.claude.com/docs/fr/build-with-claude/task-budgets#feature-support) 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.

<Warning>
  **Un budget trop petit pour la tâche peut provoquer un comportement proche du refus.** Lorsque Claude voit un budget manifestement insuffisant pour le travail demandé (par exemple, un budget de 20 000 tokens pour une tâche de codage agentique de plusieurs heures), il peut refuser de tenter la tâche, en réduire fortement la portée, ou s'arrêter prématurément avec un résultat partiel plutôt que de commencer un travail qu'il ne peut pas terminer. Si vous observez des refus inattendus ou des arrêts prématurés après avoir défini un budget, augmentez le budget avant de déboguer d'autres paramètres. Dimensionnez les budgets en fonction de la distribution réelle de la longueur de vos tâches plutôt que d'une valeur par défaut fixe ; consultez [Choisir un budget](https://platform.claude.com/docs/fr/build-with-claude/task-budgets#choosing-a-budget).
</Warning>

## 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 :

<CodeGroup exclude="shell:cURL">
  ```bash CLI
  ant messages create --transform 'usage.output_tokens' <<'YAML'
  model: claude-opus-5-5
  max_tokens: 4096
  messages:
    - role: user
      content: Review the codebase and propose a refactor plan.
  YAML
  ```

  ```python Python
  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)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const response = await 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 toutes les requêtes de votre boucle.
  console.log(response.usage.output_tokens);
  ```

  ```csharp C#

  var client = new AnthropicClient();

  var response = await client.Messages.Create(new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 4096,
      Messages = [new() { Role = Role.User, Content = "Review the codebase and propose a refactor plan." }],
  });

  // Additionnez OutputTokens (texte + réflexion + appels d'outils) sur toutes les requêtes de votre boucle.
  Console.WriteLine(response.Usage.OutputTokens);
  ```

  ```go Go
  client := anthropic.NewClient()

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 4096,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Review the codebase and propose a refactor plan.")),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }

  // Additionnez OutputTokens (texte + réflexion + appels d'outils) sur toutes les requêtes de votre boucle.
  fmt.Println(response.Usage.OutputTokens)
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_OPUS_5_5)
      .maxTokens(4096L)
      .addUserMessage("Review the codebase and propose a refactor plan.")
      .build();

  Message response = client.messages().create(params);
  // Additionnez outputTokens (texte + réflexion + appels d'outils) sur toutes les requêtes de votre boucle.
  IO.println(response.usage().outputTokens());
  ```

  ```php PHP
  $client = new Client();

  $response = $client->messages->create(
      model: 'claude-opus-5-5',
      maxTokens: 4096,
      messages: [
          ['role' => 'user', 'content' => 'Review the codebase and propose a refactor plan.'],
      ],
  );

  // Additionnez outputTokens (texte + réflexion + appels d'outils) sur toutes les requêtes de votre boucle.
  echo $response->usage->outputTokens . "\n";
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  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.
  puts response.usage.output_tokens
  ```
</CodeGroup>

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é](https://platform.claude.com/docs/fr/build-with-claude/task-budgets#feature-support)). 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](https://platform.claude.com/docs/fr/build-with-claude/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](https://platform.claude.com/docs/fr/build-with-claude/thinking) :** 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](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching) :** 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é

| Modèle            | Prise en charge                                    |
| ----------------- | -------------------------------------------------- |
| Claude Fable 5.1  | Bêta (définir l'en-tête `task-budgets-2026-03-13`) |
| Claude Mythos 5.1 | Bêta (définir l'en-tête `task-budgets-2026-03-13`) |
| Claude Opus 5.5   | Bêta (définir l'en-tête `task-budgets-2026-03-13`) |
| Claude Opus 5     | Bêta (définir l'en-tête `task-budgets-2026-03-13`) |
| Claude Fable 5    | Bêta (définir l'en-tête `task-budgets-2026-03-13`) |
| Claude Mythos 5   | Bêta (définir l'en-tête `task-budgets-2026-03-13`) |
| Claude Sonnet 5.5 | Bêta (définir l'en-tête `task-budgets-2026-03-13`) |
| Claude Sonnet 5   | Non pris en charge                                 |
| Claude Haiku 5.5  | Bêta (définir l'en-tête `task-budgets-2026-03-13`) |
| Claude Opus 4.8   | Bêta (définir l'en-tête `task-budgets-2026-03-13`) |
| Claude Opus 4.7   | Bêta (définir l'en-tête `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 budgets de tâche ne sont pas pris en charge sur [Claude Code](https://code.claude.com/docs/fr/overview) ni sur les surfaces Cowork. Utilisez les budgets de tâche directement via l'API Messages sur un [modèle pris en charge](https://platform.claude.com/docs/fr/build-with-claude/task-budgets#feature-support).

## Étapes suivantes

<CardGroup>
  <Card title="Effort" icon="gauge" href="https://platform.claude.com/docs/fr/build-with-claude/effort">
    Contrôlez la minutie avec laquelle Claude raisonne à chaque étape d'une boucle agentique.
  </Card>

  <Card title="Réflexion adaptative" icon="brain" href="https://platform.claude.com/docs/fr/build-with-claude/thinking">
    Laissez Claude déterminer quand et dans quelle mesure utiliser la réflexion étendue.
  </Card>

  <Card title="Compaction" icon="arrows-clockwise" href="https://platform.claude.com/docs/fr/build-with-claude/compaction">
    Gérez le contexte dans les conversations de longue durée grâce à la compaction côté serveur.
  </Card>

  <Card title="Mise en cache des prompts" icon="database" href="https://platform.claude.com/docs/fr/build-with-claude/prompt-caching">
    Réduisez les coûts et la latence sur les prompts répétés en mettant en cache les préfixes de prompts.
  </Card>
</CardGroup>