Orçamentos de tarefa

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

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 dosar seu ritmo e finalizar de forma graciosa à 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, depois 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, em seguida, 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 de ferramenta de 2.800 tokens é conteúdo novo que o Claude vê neste turno 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.

Turno 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 os três turnos lado a lado torna explícita a distinção entre o tamanho do payload e o gasto do orçamento:

Seu cliente enviou a mensagem de usuário do turno 1 três vezes e a mensagem de 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 com cache de prompt nos turnos 2 e 3 tenha sido maior ainda.

Transferindo um orçamento através da compactação 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 do 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 ser redefinida para 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 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 ao recurso 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.

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:

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) de todas as requisições no 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, em seguida, teste para cima ou para baixo conforme necessário.

O valor mínimo aceito de task_budget.total é específico de cada modelo. Em todos os modelos que suportam orçamentos de tarefa (consulte Suporte ao recurso), ele é de 20.000 tokens, e 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 requisição sobre os 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 como pelo menos 64k para dar ao Claude espaço para pensar e agir em cada requisição.
• Effort: O effort controla o quão profundamente o Claude raciocina por etapa. Os orçamentos de tarefa controlam quanto trabalho total o Claude realiza 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 os tokens de pensamento na contagem, portanto o pensamento adaptativo diminui à medida que o orçamento se esgota.
• Cache de prompt: O marcador de contagem regressiva do orçamento é injetado no lado do servidor a cada turno, portanto não corresponde entre requisições. Se o seu cliente decrementa task_budget.remaining em cada requisiçã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 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 ao recurso

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

Próximos passos

Compatibility