Orçamentos de tarefa

Os "task budgets" (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 andamento e a usa para priorizar o trabalho e finalizar de forma elegante à 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 Claude faz várias chamadas de ferramentas e decisões antes de finalizar sua saída para aguardar a próxima resposta humana. Use-os quando:

• Você quer que Claude se autorregule no 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 elegante (resumir descobertas, relatar progresso) à medida que se aproxima do orçamento, em vez de interromper no meio de uma ação.

Os orçamentos de tarefa complementam o parâmetro effort: effort controla o quão minuciosamente Claude raciocina sobre cada etapa, enquanto os orçamentos de tarefa limitam o trabalho total que 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-4-8",
    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 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

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. Claude usa esse sinal para controlar seu ritmo e finalizar de forma elegante à medida que o orçamento é consumido.



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

O orçamento de tarefa conta o que 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 a turno, mas o orçamento só é decrementado pelos tokens que 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." }
  ]
}

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 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 Claude vê neste turno e conta contra o orçamento. 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 de ferramenta (1.200 tokens de saída do grep) anexado. 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 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 com cache de prompt nos turnos 2 e 3 tenha sido ainda maior.



Transferindo um orçamento através de 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 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 para total:

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.



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. Claude pode ocasionalmente exceder o orçamento se estiver no meio de uma ação que seria mais disruptivo 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 um alvo para controlar 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 estar igual ou abaixo do 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 Claude gasta por tarefa. Para um loop agêntico, some usage.output_tokens mais os tokens de pensamento e de resultados de ferramentas em todas as requisições do loop:

def run_task_and_count_tokens(messages: list) -> int:
    """Runs an agentic loop to completion and returns total tokens spent."""
    total_spend = 0
    while True:
        with client.beta.messages.stream(
            model="claude-opus-4-8",
            max_tokens=128000,
            messages=messages,
            tools=tools,
            betas=["task-budgets-2026-03-13"],
        ) as stream:
            response = stream.get_final_message()
        # Conta o que Claude gerou neste turno (a saída abrange texto + pensamento + chamadas de ferramentas).
        # Os tokens de resultados de ferramentas também contam para o orçamento; some a contagem de tokens dos
        # blocos tool_result que você anexa abaixo se quiser que o rastreamento no lado do cliente corresponda
        # à contagem regressiva no lado do servidor.
        total_spend += response.usage.output_tokens
        if response.stop_reason == "end_turn":
            return total_spend
        # Anexe o turno do assistente e seus resultados de ferramentas e, em seguida, continue o loop.
        messages += [
            {"role": "assistant", "content": response.content},
            {"role": "user", "content": run_tools(response.content)},
        ]

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, depois teste para cima ou para baixo conforme necessário.

O mínimo aceito para task_budget.total é 20.000 tokens; 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: Effort controla a profundidade com que Claude raciocina por etapa. Os orçamentos de tarefa controlam quanto trabalho total Claude faz ao longo de um loop agêntico. Os dois são complementares: effort ajusta a profundidade, 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 a cada turno, portanto não corresponde entre requisições. Se o seu cliente decrementar 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 em relação à contagem regressiva do lado do servidor, em vez de alterar o orçamento no lado do cliente.



Suporte do recurso

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.