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

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:

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

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

{
  "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) 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 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:

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

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

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:

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

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

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). 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: 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: 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: 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

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

Próximos passos

Compatibility