Orçamentos de tarefas

Os orçamentos de tarefas permitem que você diga ao Claude quantos tokens ele tem para um loop agentic 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 terminar graciosamente conforme o orçamento é consumido.

Quando usar orçamentos de tarefas

Os orçamentos de tarefas funcionam melhor para fluxos de trabalho agentic onde Claude faz múltiplas 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 custo previsível por tarefa ou um limite de latência para aplicar.
• Você quer que o modelo termine graciosamente (resumir descobertas, relatar progresso) conforme se aproxima do orçamento em vez de ser cortado no meio de uma ação.

Os orçamentos de tarefas complementam o parâmetro de esforço: o esforço controla como Claude raciocina profundamente sobre cada etapa, enquanto os orçamentos de tarefas limitam o trabalho total que Claude pode fazer em um loop agentic.

Definindo um orçamento de tarefas

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",
    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"],
)

O objeto task_budget tem três campos:

• type: sempre "tokens".
• total: o número de tokens que Claude pode gastar em todo o loop agentic, incluindo pensamento, chamadas de ferramentas, resultados de ferramentas e saída.
• remaining (opcional): o restante do orçamento transferido de uma solicitação anterior. Padrão para total quando omitido.

Como funciona a contagem regressiva do orçamento

Claude vê um marcador de contagem regressiva de orçamento injetado no lado do servidor em toda a conversa. O marcador mostra quantos tokens permanecem no loop agentic atual e é atualizado conforme o modelo gera pensamento, chamadas de ferramentas e saída, e conforme processa resultados de ferramentas. Claude usa este sinal para se manter no ritmo e terminar graciosamente conforme o orçamento é consumido.

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

O orçamento de tarefas conta o que Claude vê (pensamento, chamadas de ferramentas e resultados, e texto), não o que está em sua carga de solicitação. Em um loop agentic seu cliente reenvia a conversa completa em cada solicitação, então a carga cresce turno após turno, mas o orçamento apenas decrementa 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 solicitaçã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, depois 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 do 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 Claude vê neste turno e conta contra o orçamento. Claude gasta outros 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 grep) anexado. Claude escreve um relatório de descobertas finais de 6.000 tokens e para com stop_reason: "end_turn". remaining ≈ 81.000.

Colocar os três turnos lado a lado torna a distinção entre tamanho de carga e gasto de orçamento explícita:

Seu cliente enviou a mensagem do 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, mesmo que a carga cumulativa que seu cliente transmitiu fosse maior e a entrada em cache de prompt nos turnos 2 e 3 fosse ainda maior.

Transferindo um orçamento entre compactação com remaining

Se seu loop agentic compacta ou reescreve contexto entre solicitaçõ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 solicitação para que a contagem regressiva continue de onde parou em vez de redefinir 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 tarefas são consultivos, não aplicados

Os orçamentos de tarefas são uma dica suave, 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 terminar. O limite aplicado no 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 em custo ou latência, combine orçamentos de tarefas com um valor max_tokens razoável:

• Use task_budget para dar ao Claude um alvo para se manter no ritmo.
• Use max_tokens como o teto absoluto que previne geração descontrolada.

Como task_budget abrange o loop agentic completo (potencialmente muitas solicitações) enquanto max_tokens limita cada solicitação individual, os dois valores são independentes; um não é obrigado a estar em ou abaixo do outro.

Escolhendo um orçamento

O orçamento certo depende de quanto trabalho seu loop agentic atualmente faz. Em vez de adivinhar, meça seu uso de tokens existente primeiro 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 agentic, some usage.output_tokens mais tokens de pensamento e resultado de ferramenta em cada solicitação no 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:
        response = client.beta.messages.create(
            model="claude-opus-4-7",
            max_tokens=128000,
            messages=messages,
            tools=tools,
            betas=["task-budgets-2026-03-13"],
        )
        # Count what Claude generated this turn (output covers text + thinking + tool calls).
        # Tool-result tokens also count against the budget; add the token count of the
        # tool_result blocks you append below if you want client-side tracking to match
        # the server-side countdown.
        total_spend += response.usage.output_tokens
        if response.stop_reason == "end_turn":
            return total_spend
        # Append the assistant turn and your tool results, then continue the 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 tarefas pode modificar o comportamento do modelo, depois teste para cima ou para baixo conforme necessário.

O task_budget.total mínimo aceito é 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 tarefas. max_tokens é um limite rígido por solicitação em tokens gerados, enquanto task_budget é um limite consultivo em todo o loop agentic (potencialmente abrangendo muitas solicitações). Em esforço xhigh ou max, defina max_tokens para pelo menos 64k para dar ao Claude espaço para pensar e agir em cada solicitação.
• Esforço: O esforço controla como Claude raciocina profundamente por etapa. Os orçamentos de tarefas controlam quanto trabalho total Claude faz em um loop agentic. Os dois são complementares: o esforço ajusta a profundidade, os orçamentos de tarefas ajustam a amplitude.
• Pensamento adaptativo: Os orçamentos de tarefas incluem tokens de pensamento na contagem, então o pensamento adaptativo naturalmente diminui conforme o orçamento se esgota.
• Cache de prompt: O marcador de contagem regressiva de orçamento é injetado no lado do servidor por turno, então não corresponde entre solicitações. Se 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 contra a contagem regressiva no lado do servidor em vez de mutar o orçamento no lado do cliente.

Suporte de recursos

Os orçamentos de tarefas não são suportados em superfícies Claude Code ou Cowork no lançamento. Use orçamentos de tarefas diretamente via a API de Mensagens no Claude Opus 4.7.