Orçamentos de tarefa

Os orçamentos de tarefa permitem que você informe 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 em execução e a usa para priorizar o trabalho e finalizar de forma adequada à medida que o orçamento é consumido.



Quando usar orçamentos de tarefa

Os orçamentos de tarefa funcionam melhor para fluxos de trabalho agênticos em que o Claude faz várias chamadas de ferramentas e toma 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 adequada (resumir descobertas, relatar 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: 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 fazer 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:

client = anthropic.Anthropic()

with client.beta.messages.stream(
    model="claude-opus-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)

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 regular seu ritmo e finalizar de forma adequada à medida que o orçamento é consumido.



Exemplo prático: contagem do orçamento entre turnos

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 requisição. Em um loop agêntico, seu cliente reenvia a conversa completa em cada requisição, então o payload cresce turno após turno, mas o orçamento só é decrementado pelos tokens que o Claude vê neste turno.

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

Turno 1. Você envia a requisição inicial:

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

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

Suponha que este turno 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.

Turno 2. Seu cliente executa a ferramenta e então reenvia o histórico completo com o resultado da ferramenta anexado:

{
  "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 de usuário e assistente do turno 1 reenviadas não são contadas novamente, mas o resultado da ferramenta de 2.800 tokens é conteúdo novo que o Claude vê neste turno e conta contra o orçamento. O Claude gasta mais 4.000 tokens em pensamento e uma segunda chamada de ferramenta (grep -rn "eval(" src/). A contagem regressiva termina perto de remaining ≈ 88.200.

Turno 3. Histórico completo reenviado novamente com o segundo resultado da 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 os três turnos lado a lado torna explícita a distinção entre tamanho do payload e gasto do orçamento:

Seu cliente enviou a mensagem de usuário do turno 1 três vezes e a mensagem do assistente do turno 1 duas vezes, mas cada uma foi contada uma 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 nos turnos 2 e 3 tenha sido ainda maior.



Transferindo um orçamento entre compactações com remaining

Se o seu loop agêntico compacta ou reescreve o contexto entre requisições (por exemplo, resumindo turnos anteriores), o servidor não tem memória de quanto orçamento foi gasto antes da compactação. Passe remaining na próxima requisição para que a contagem regressiva continue de onde você parou, em vez de reiniciar em total:

# 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,
    },
}

Para loops que reenviam o histórico completo não compactado em cada turno, omita remaining e deixe o servidor rastrear 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, então um valor alterado não corresponde a entradas de cache criadas sob o valor antigo (consulte Suporte de recursos 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 disruptiva interromper do que finalizar. O limite imposto sobre o total de tokens de saída ainda é 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 para regular seu ritmo.
• Use max_tokens como o teto absoluto que impede 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; um não precisa ser igual ou menor que o outro.



Escolhendo um orçamento

O orçamento certo depende de quanto trabalho seu loop agêntico faz 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 no loop, mais os tokens dos resultados de ferramentas que você anexa entre requisições:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Review the codebase and propose a refactor plan."}
    ],
)

# Some output_tokens (texto + pensamento + chamadas de ferramentas) em todas as requisições do seu loop.
print(response.usage.output_tokens)

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 então teste valores maiores ou menores conforme necessário.

O task_budget.total mínimo aceito é específico do modelo; em todos os modelos que atualmente suportam orçamentos de tarefa (consulte Suporte de recursos), ele é de 20.000 tokens, e valores abaixo do mínimo 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 requisição sobre tokens gerados, enquanto task_budget é um limite consultivo ao longo do loop agêntico completo (potencialmente abrangendo muitas requisições). Com effort xhigh ou max, defina max_tokens para pelo menos 64k para dar ao Claude espaço para pensar e agir em cada requisição.
• Effort: O effort controla a profundidade com que o Claude raciocina por 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 effort ajusta a profundidade, os orçamentos de tarefa ajustam a amplitude.
• Pensamento adaptativo: Os orçamentos de tarefa incluem tokens de pensamento na contagem, então o pensamento adaptativo naturalmente diminui à medida que o orçamento se esgota.
• Cache de prompt: O marcador de contagem regressiva do orçamento é injetado no lado do servidor por turno, então ele não corresponde entre requisições. Se o seu cliente decrementa task_budget.remaining em cada requisição subsequente, o valor alterado invalida qualquer prefixo de cache que o contenha. Para preservar o cache, defina o orçamento uma vez na requisiçã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 de recursos

Os orçamentos de tarefa não são suportados no Claude Code ou em superfícies do Cowork. Use orçamentos de tarefa diretamente através da Messages API em um modelo suportado.



Próximos passos