---
title: Orçamentos de tarefa
url: https://platform.claude.com/docs/pt-BR/build-with-claude/task-budgets
description: Dê ao Claude um orçamento consultivo de tokens para todo o loop agêntico, ajudando o modelo a se autorregular em tarefas agênticas longas.
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
---

Os "task budgets" (orçamentos de tarefa) permitem que você diga ao Claude quantos tokens ele tem para um loop agêntico completo, incluindo pensamento, chamadas de ferramentas, resultados de ferramentas e saída. O modelo vê uma contagem regressiva contínua e a usa para priorizar o trabalho e finalizar de forma graciosa à medida que o orçamento é consumido.

## Quando usar orçamentos de tarefa

Os orçamentos de tarefa funcionam melhor em fluxos de trabalho agênticos nos quais o Claude faz várias chamadas de ferramentas e toma várias decisões antes de finalizar sua saída para aguardar a próxima resposta humana. Use-os quando:

* Você quer que o Claude autorregule o gasto de tokens em tarefas de longo horizonte.
* Você tem um teto previsível de custo ou latência por tarefa a ser aplicado.
* Você quer que o modelo finalize de forma graciosa (resumindo descobertas, relatando o progresso) à medida que se aproxima do orçamento, em vez de ser interrompido no meio de uma ação.

Os orçamentos de tarefa complementam o [parâmetro effort](https://platform.claude.com/docs/pt-BR/build-with-claude/effort): o effort controla o quão minuciosamente o Claude raciocina sobre cada etapa, enquanto os orçamentos de tarefa limitam o trabalho total que o Claude pode realizar ao longo de um loop agêntico.

## Definindo um orçamento de tarefa

Adicione `task_budget` a `output_config` e inclua o cabeçalho beta:

<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'],
  );

  // O evento message_delta final contém o uso cumulativo de tokens da requisição.
  $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>

O objeto `task_budget` tem três campos:

* `type`: sempre `"tokens"`.
* `total`: o número de tokens que o Claude pode gastar ao longo do loop agêntico, incluindo pensamento, chamadas de ferramentas, resultados de ferramentas e saída.
* `remaining` (opcional): o restante do orçamento transferido de uma requisição anterior. O padrão é `total` quando omitido.

## Como funciona a contagem regressiva do orçamento

O Claude vê um marcador de contagem regressiva do orçamento injetado no lado do servidor ao longo da conversa. O marcador mostra quantos tokens restam no loop agêntico atual e é atualizado à medida que o modelo gera pensamento, chamadas de ferramentas e saída, e à medida que processa resultados de ferramentas. O Claude usa esse sinal para controlar seu ritmo e concluir de forma adequada à medida que o orçamento é consumido.

<Note>
  **A contagem regressiva é visível apenas para o modelo.** As respostas da API não incluem um campo de orçamento restante: não há informações de `task_budget` no objeto `usage` da resposta, e o SDK não tem um acessor para isso. Para acompanhar o gasto no lado do cliente, some o uso de tokens entre as solicitações do seu loop, conforme mostrado em [Meça seu uso atual](https://platform.claude.com/docs/pt-BR/build-with-claude/task-budgets#measure-your-current-usage), ou repasse seu próprio valor com `remaining` ao [transferir um orçamento através da compactação](https://platform.claude.com/docs/pt-BR/build-with-claude/task-budgets#carrying-a-budget-across-compaction-with-remaining).
</Note>

<Warning>
  **A contagem regressiva reflete os tokens que o Claude processou no loop agêntico atual, não os tokens que você reenvia entre solicitações.** Se o seu cliente envia o histórico completo da conversa em cada solicitação de acompanhamento, a contagem de tokens no lado do cliente pode diferir do orçamento que o Claude está acompanhando. Se você também decrementar `remaining` enquanto reenvia o histórico completo, o modelo vê um orçamento subnotificado e a contagem regressiva cai mais rápido do que deveria, fazendo com que o Claude encerre antes do que o orçamento realmente permite. Defina um orçamento generoso e deixe o modelo se autorregular com base na contagem regressiva, em vez de tentar espelhá-la no lado do cliente.
</Warning>

### O que conta como um turno

O orçamento cobre um turno agêntico, também chamado de loop agêntico: tudo o que o Claude faz em resposta a uma mensagem do usuário que não contém resultados de ferramentas. Um turno pode abranger várias solicitações.

Uma mensagem do usuário que não contém resultados de ferramentas inicia um novo turno com um orçamento renovado. Atualmente, a contagem regressiva ainda contabiliza o histórico de turnos anteriores enquanto ele permanece no contexto. Um caso comum é uma mensagem de acompanhamento depois que o Claude encerrou seu turno, por exemplo, porque o orçamento se esgotou:

```json
{ "role": "user", "content": "Continue." }
```

Uma mensagem do usuário que contém blocos `tool_result` continua o turno atual, porque seu cliente está resolvendo chamadas de ferramentas que fazem parte desse turno:

```json
{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01", "content": "<npm audit output>" }
  ]
}
```

Isso vale mesmo quando a mensagem adiciona novo conteúdo junto com os resultados de ferramentas:

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

A ["compaction" (compactação)](https://platform.claude.com/docs/pt-BR/build-with-claude/compaction-threshold) no lado do servidor durante um turno não redefine o orçamento: os tokens que o turno consumiu antes da compactação ainda contam contra ele. Os tokens de antes do início do turno não contam, mesmo quando uma compactação no início de um turno os resume. Atualmente, essa exclusão se aplica apenas ao orçamento transportado através de uma compactação no lado do servidor; o histórico de turnos anteriores ainda conta enquanto permanece no contexto.

### Exemplo prático: contagem do orçamento entre solicitações

O orçamento de tarefa conta o que o Claude **vê** (pensamento, chamadas e resultados de ferramentas, e texto), não o que está no payload da sua solicitação. Em um loop agêntico, seu cliente reenvia a conversa completa em cada solicitação, então o payload continua crescendo, mas o orçamento só é decrementado pelo que é novo: os tokens que o Claude gera e o conteúdo que ele ainda não viu. O exemplo a seguir é um [turno agêntico](https://platform.claude.com/docs/pt-BR/build-with-claude/task-budgets#what-counts-as-a-turn) composto por três solicitações: a primeira contém a mensagem do usuário, e as duas seguintes reenviam o histórico com um resultado de ferramenta anexado.

Considere um loop com `task_budget: {type: "tokens", total: 100000}` e uma única ferramenta `bash`.

**Solicitação 1.** Você envia a solicitação inicial:

```json
{
  "messages": [
    { "role": "user", "content": "Audit this repo for security issues and report findings." }
  ]
}
```

O Claude pensa, depois emite uma chamada de ferramenta e para com `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" }
    }
  ]
}
```

Suponha que essa mensagem do assistente (pensamento mais a chamada de ferramenta) totalize 5.000 tokens gerados. A contagem regressiva que o Claude viu durante a geração terminou perto de `remaining` ≈ 95.000.

**Solicitação 2.** Seu cliente executa a ferramenta e, em seguida, reenvia o histórico completo com o resultado da ferramenta anexado:

```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>"
        }
      ]
    }
  ]
}
```

As mensagens reenviadas da solicitação 1 não são contadas novamente, mas o resultado de ferramenta de 2.800 tokens é conteúdo novo e conta contra o orçamento. O Claude gasta outros 4.000 tokens em pensamento e em uma segunda chamada de ferramenta (`grep -rn "eval(" src/`). A contagem regressiva termina perto de `remaining` ≈ 88.200.

**Solicitação 3.** O histórico completo é reenviado novamente com o segundo resultado de ferramenta (1.200 tokens de saída do grep) anexado. O Claude escreve um relatório final de descobertas de 6.000 tokens e para com `stop_reason: "end_turn"`. `remaining` ≈ 81.000.

Colocar as três solicitações lado a lado torna explícita a distinção entre o tamanho do payload e o gasto do orçamento:

| Solicitação | Payload da solicitação (tokens de entrada aproximados que você enviou) | Tokens contados contra o orçamento nesta solicitação                        | `remaining` do orçamento depois |
| ----------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------- |
| 1           | \~20                                                                   | 5.000 (pensamento + `tool_use`)                                             | \~95.000                        |
| 2           | \~7.800 (mensagens da solicitação 1 + resultado de ferramenta)         | 6.800 (2.800 de resultado de ferramenta + 4.000 de pensamento e `tool_use`) | \~88.200                        |
| 3           | \~13.000 (histórico completo + segundo resultado de ferramenta)        | 7.200 (1.200 de resultado de ferramenta + 6.000 de `text`)                  | \~81.000                        |
| **Total**   | **\~20.820 enviados entre as solicitações**                            | **19.000 contados contra o orçamento**                                      | N/A                             |

Seu cliente enviou a mensagem original do usuário três vezes e a primeira mensagem do assistente duas vezes, mas cada uma foi contada uma única vez. O orçamento gastou 19.000 de 100.000 tokens, embora o payload cumulativo que seu cliente transmitiu tenha sido maior e a entrada em cache de prompt nas solicitações 2 e 3 tenha sido maior ainda.

### Transferindo um orçamento através da compactação com `remaining`

Se o seu próprio código compacta ou reescreve o histórico de mensagens entre solicitações (por exemplo, resumindo mensagens anteriores), o servidor não tem memória de quanto orçamento foi gasto antes da compactação. Passe `remaining` na próxima solicitação para que a contagem regressiva continue de onde você parou, em vez de ser redefinida para `total`:

<CodeGroup exclude="shell">
  ```python Python
  # Tokens gastos antes da compactação, rastreados no lado do cliente
  tokens_spent_so_far = 45000

  output_config = {
      "effort": "high",
      "task_budget": {
          "type": "tokens",
          "total": 128000,
          "remaining": 128000 - tokens_spent_so_far,
      },
  }
  ```

  ```typescript TypeScript
  // Tokens gastos antes da compactação, rastreados no lado do cliente
  const tokensSpentSoFar = 45000;

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

  ```csharp C#
  // Tokens gastos antes da compactação, rastreados no lado do cliente
  var tokensSpentSoFar = 45000;

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

  ```go Go
  // Tokens gastos antes da compactação, rastreados no lado do cliente
  tokensSpentSoFar := int64(45000)

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

  ```java Java
  // Tokens gastos antes da compactação, rastreados no lado do cliente
  long tokensSpentSoFar = 45000;

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

  ```php PHP
  // Tokens gastos antes da compactação, rastreados no lado do cliente
  $tokensSpentSoFar = 45000;

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

  ```ruby Ruby
  # Tokens gastos antes da compactação, rastreados no lado do cliente
  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>

Neste exemplo, os tokens gastos antes da compactação são o uso de todas as mensagens que você removeu do histórico até agora, medido como em [Meça seu uso atual](https://platform.claude.com/docs/pt-BR/build-with-claude/task-budgets#measure-your-current-usage). Deixe de fora qualquer coisa ainda presente nas mensagens que você envia, incluindo qualquer resumo que você adicionou, porque o servidor conta esses tokens por conta própria. Atualize esse valor apenas quando substituir o histórico dessa forma; não o decremente a cada solicitação. Passe o `remaining` resultante em todas as solicitações, não apenas naquela que faz a compactação.

Para loops que reenviam o histórico completo não compactado em cada solicitação, omita `remaining` e deixe o servidor acompanhar a contagem regressiva.

## Alterando o orçamento no meio da conversa

`task_budget` é uma configuração no nível da requisição. Para alterar o orçamento no meio de uma tarefa, por exemplo para estendê-lo quando o usuário amplia a solicitação, defina um novo `task_budget` em `output_config` na próxima requisição. Tenha em mente a consequência para o cache: o valor do orçamento participa do prompt renderizado, portanto um valor alterado não corresponde às entradas de cache criadas com o valor antigo (consulte [Suporte a recursos](https://platform.claude.com/docs/pt-BR/build-with-claude/task-budgets#feature-support) abaixo).

## Orçamentos de tarefa são consultivos, não impostos

Os orçamentos de tarefa são uma **sugestão flexível, não um limite rígido**. O Claude pode ocasionalmente exceder o orçamento se estiver no meio de uma ação que seria mais prejudicial interromper do que concluir. O limite imposto sobre o total de tokens de saída continua sendo `max_tokens`, que trunca a resposta com `stop_reason: "max_tokens"` quando atingido.

Para um limite rígido de custo ou latência, combine orçamentos de tarefa com um valor razoável de `max_tokens`:

* Use `task_budget` para dar ao Claude uma meta em relação à qual dosar seu ritmo.
* Use `max_tokens` como o teto absoluto que impede a geração descontrolada.

Como `task_budget` abrange o loop agêntico completo (potencialmente muitas requisições), enquanto `max_tokens` limita cada requisição individual, os dois valores são independentes; não é necessário que um seja igual ou inferior ao outro.

<Warning>
  **Um orçamento pequeno demais para a tarefa pode causar comportamento semelhante a recusa.** Quando o Claude vê um orçamento claramente insuficiente para o trabalho solicitado (por exemplo, um orçamento de 20.000 tokens para uma tarefa de codificação agêntica de várias horas), ele pode se recusar a tentar a tarefa, reduzir agressivamente seu escopo ou parar cedo com um resultado parcial, em vez de iniciar um trabalho que não consegue concluir. Se você observar recusas inesperadas ou paradas prematuras após definir um orçamento, aumente o orçamento antes de depurar outros parâmetros. Dimensione os orçamentos com base na distribuição real da duração das suas tarefas, em vez de um padrão fixo; consulte [Escolhendo um orçamento](https://platform.claude.com/docs/pt-BR/build-with-claude/task-budgets#choosing-a-budget).
</Warning>

## Escolhendo um orçamento

O orçamento certo depende de quanto trabalho seu loop agêntico realiza atualmente. Em vez de adivinhar, meça primeiro seu uso de tokens existente e depois ajuste a partir daí.

### Meça seu uso atual

Execute uma amostra representativa de tarefas **sem** `task_budget` definido e registre o total de tokens que o Claude gasta por tarefa. Para um loop agêntico, some `usage.output_tokens` de todas as requisições do loop, mais os tokens dos resultados de ferramentas que você anexa entre as requisições:

<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."}
      ],
  )

  # Some os output_tokens (texto + pensamento + chamadas de ferramentas) de todas as requisições do seu loop.
  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." }]
  });

  // Some os output_tokens (texto + pensamento + chamadas de ferramentas) de todas as requisições do seu loop.
  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." }],
  });

  // Some OutputTokens (texto + pensamento + chamadas de ferramentas) de todas as requisições do seu loop.
  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)
  }

  // Some OutputTokens (texto + pensamento + chamadas de ferramentas) de todas as requisições do seu loop.
  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);
  // Some outputTokens (texto + pensamento + chamadas de ferramentas) de todas as requisições do seu loop.
  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.'],
      ],
  );

  // Some outputTokens (texto + pensamento + chamadas de ferramentas) de todas as requisições do seu loop.
  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." }
    ]
  )

  # Some os output_tokens (texto + pensamento + chamadas de ferramentas) de todas as requisições do seu loop.
  puts response.usage.output_tokens
  ```
</CodeGroup>

Execute isso em um conjunto representativo de tarefas e registre a distribuição. Comece com o p99 do seu gasto de tokens por tarefa para entender como fornecer ao modelo um orçamento de tarefa pode modificar o comportamento do modelo e, em seguida, teste para cima ou para baixo conforme necessário.

O `task_budget.total` mínimo aceito é de **20.000 tokens** em todos os modelos que suportam orçamentos de tarefa (consulte [Suporte a recursos](https://platform.claude.com/docs/pt-BR/build-with-claude/task-budgets#feature-support)). Valores menores retornam um erro 400.

## Interação com outros parâmetros

* **`max_tokens`:** Ortogonal aos orçamentos de tarefa. `max_tokens` é um limite rígido por solicitação sobre os tokens gerados, enquanto `task_budget` é um limite consultivo ao longo de todo o loop agêntico (potencialmente abrangendo muitas solicitações). Com esforço `xhigh` ou `max`, defina `max_tokens` como pelo menos 64k para dar ao Claude espaço para pensar e agir em cada solicitação.
* **[Esforço](https://platform.claude.com/docs/pt-BR/build-with-claude/effort):** O esforço controla a profundidade com que o Claude raciocina em cada etapa. Os orçamentos de tarefa controlam quanto trabalho total o Claude faz ao longo de um loop agêntico. Os dois são complementares: o esforço ajusta a profundidade, os orçamentos de tarefa ajustam a amplitude.
* **[Pensamento adaptativo](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking):** Os orçamentos de tarefa incluem os tokens de pensamento na contagem, então o pensamento adaptativo é reduzido à medida que o orçamento se esgota.
* **[Cache de prompt](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching):** O marcador de contagem regressiva do orçamento é injetado no lado do servidor em cada solicitação, então ele não corresponde entre solicitações. Se o seu cliente decrementar `task_budget.remaining` em cada solicitação de acompanhamento, o valor alterado invalida qualquer prefixo de cache que o contenha. Para preservar o cache, defina o orçamento uma vez na solicitação inicial e deixe o modelo se autorregular com base na contagem regressiva do lado do servidor, em vez de alterar o orçamento no lado do cliente.

## Suporte a recursos

| Modelo            | Suporte                                             |
| ----------------- | --------------------------------------------------- |
| Claude Fable 5.1  | Beta (defina o cabeçalho `task-budgets-2026-03-13`) |
| Claude Mythos 5.1 | Beta (defina o cabeçalho `task-budgets-2026-03-13`) |
| Claude Opus 5.5   | Beta (defina o cabeçalho `task-budgets-2026-03-13`) |
| Claude Opus 5     | Beta (defina o cabeçalho `task-budgets-2026-03-13`) |
| Claude Fable 5    | Beta (defina o cabeçalho `task-budgets-2026-03-13`) |
| Claude Mythos 5   | Beta (defina o cabeçalho `task-budgets-2026-03-13`) |
| Claude Sonnet 5.5 | Beta (defina o cabeçalho `task-budgets-2026-03-13`) |
| Claude Sonnet 5   | Não suportado                                       |
| Claude Haiku 5.5  | Beta (defina o cabeçalho `task-budgets-2026-03-13`) |
| Claude Opus 4.8   | Beta (defina o cabeçalho `task-budgets-2026-03-13`) |
| Claude Opus 4.7   | Beta (defina o cabeçalho `task-budgets-2026-03-13`) |
| Claude Opus 4.6   | Não suportado                                       |
| Claude Sonnet 4.6 | Não suportado                                       |
| Claude Haiku 4.5  | Não suportado                                       |

Os orçamentos de tarefa não são suportados no [Claude Code](https://code.claude.com/docs/en/overview) nem nas superfícies do Cowork. Use os orçamentos de tarefa diretamente por meio da Messages API em um [modelo suportado](https://platform.claude.com/docs/pt-BR/build-with-claude/task-budgets#feature-support).

## Próximos passos

<CardGroup>
  <Card title="Effort" icon="gauge" href="https://platform.claude.com/docs/pt-BR/build-with-claude/effort">
    Controle o quão minuciosamente o Claude raciocina sobre cada etapa de um loop agêntico.
  </Card>

  <Card title="Pensamento adaptativo" icon="brain" href="https://platform.claude.com/docs/pt-BR/build-with-claude/thinking">
    Deixe o Claude determinar quando e quanto usar o pensamento estendido.
  </Card>

  <Card title="Compactação" icon="arrows-clockwise" href="https://platform.claude.com/docs/pt-BR/build-with-claude/compaction">
    Gerencie o contexto em conversas de longa duração com compactação no lado do servidor.
  </Card>

  <Card title="Cache de prompt" icon="database" href="https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching">
    Reduza o custo e a latência em prompts repetidos armazenando prefixos de prompt em cache.
  </Card>
</CardGroup>