Budget per attività

I "task budgets" (budget per attività) ti permettono di indicare a Claude quanti token ha a disposizione per un intero ciclo agentico, inclusi pensiero, chiamate agli strumenti, risultati degli strumenti e output. Il modello vede un conto alla rovescia in tempo reale e lo usa per dare priorità al lavoro e concludere in modo ordinato man mano che il budget viene consumato.



Quando usare i budget per attività

I budget per attività funzionano al meglio per i flussi di lavoro agentici in cui Claude effettua più chiamate agli strumenti e decisioni prima di finalizzare il suo output in attesa della successiva risposta umana. Usali quando:

• Vuoi che Claude autoregoli la spesa di token in attività a lungo orizzonte.
• Hai un tetto prevedibile di costo o latenza per attività da far rispettare.
• Vuoi che il modello concluda in modo ordinato (riassumendo i risultati, riportando i progressi) man mano che si avvicina al budget, invece di interrompersi a metà di un'azione.

I budget per attività sono complementari al parametro effort: effort controlla quanto a fondo Claude ragiona su ogni passaggio, mentre i budget per attività limitano il lavoro totale che Claude può svolgere in un ciclo agentico.



Impostare un budget per attività

Aggiungi task_budget a output_config e includi l'header 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)

L'oggetto task_budget ha tre campi:

• type: sempre "tokens".
• total: il numero di token che Claude può spendere nell'intero ciclo agentico, inclusi pensiero, chiamate agli strumenti, risultati degli strumenti e output.
• remaining (opzionale): il budget residuo riportato da una richiesta precedente. Se omesso, il valore predefinito è total.



Come funziona il conto alla rovescia del budget

Claude vede un indicatore di conto alla rovescia del budget iniettato lato server durante tutta la conversazione. L'indicatore mostra quanti token rimangono nel ciclo agentico corrente e si aggiorna man mano che il modello genera pensiero, chiamate agli strumenti e output, e man mano che elabora i risultati degli strumenti. Claude usa questo segnale per regolare il proprio ritmo e concludere in modo ordinato man mano che il budget viene consumato.



Esempio pratico: conteggio del budget tra i turni

Il budget per attività conta ciò che Claude vede (pensiero, chiamate agli strumenti e risultati, e testo), non ciò che è nel payload della tua richiesta. In un ciclo agentico il tuo client reinvia l'intera conversazione a ogni richiesta, quindi il payload cresce turno dopo turno, ma il budget si decrementa solo dei token che Claude vede in questo turno.

Considera un ciclo con task_budget: {type: "tokens", total: 100000} e un singolo strumento bash.

Turno 1. Invii la richiesta iniziale:

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

Claude pensa, poi emette una chiamata allo strumento e si ferma con 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" }
    }
  ]
}

Supponiamo che questo turno dell'assistente (pensiero più la chiamata allo strumento) totalizzi 5.000 token generati. Il conto alla rovescia che Claude ha visto durante la generazione è terminato vicino a remaining ≈ 95.000.

Turno 2. Il tuo client esegue lo strumento, poi reinvia la cronologia completa con il risultato dello strumento aggiunto in coda:

{
  "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>"
        }
      ]
    }
  ]
}

I messaggi user e assistant del turno 1 reinviati non vengono conteggiati di nuovo, ma il risultato dello strumento da 2.800 token è contenuto nuovo che Claude vede in questo turno e viene conteggiato nel budget. Claude spende altri 4.000 token in pensiero e una seconda chiamata allo strumento (grep -rn "eval(" src/). Il conto alla rovescia termina vicino a remaining ≈ 88.200.

Turno 3. La cronologia completa viene reinviata di nuovo con il secondo risultato dello strumento (1.200 token di output di grep) aggiunto in coda. Claude scrive un report finale dei risultati da 6.000 token e si ferma con stop_reason: "end_turn". remaining ≈ 81.000.

Mettere i tre turni uno accanto all'altro rende esplicita la distinzione tra dimensione del payload e spesa del budget:

Il tuo client ha inviato il messaggio user del turno 1 tre volte e il messaggio assistant del turno 1 due volte, ma ciascuno è stato conteggiato una sola volta. Il budget ha speso 19.000 di 100.000 token, anche se il payload cumulativo trasmesso dal tuo client era più grande e l'input in cache dei prompt nei turni 2 e 3 era ancora più grande.



Riportare un budget attraverso la compattazione con remaining

Se il tuo ciclo agentico compatta o riscrive il contesto tra le richieste (ad esempio, riassumendo i turni precedenti), il server non ha memoria di quanto budget è stato speso prima della compattazione. Passa remaining nella richiesta successiva in modo che il conto alla rovescia continui da dove eri rimasto invece di ripartire da total:

output_config = {
    "effort": "high",
    "task_budget": {
        "type": "tokens",
        "total": 128000,
        "remaining": 128000 - tokens_spent_so_far,
    },
}

Per i cicli che reinviano l'intera cronologia non compattata a ogni turno, ometti remaining e lascia che il server tracci il conto alla rovescia.



I budget per attività sono indicativi, non imposti

I budget per attività sono un suggerimento flessibile, non un limite rigido. Claude può occasionalmente superare il budget se si trova nel mezzo di un'azione che sarebbe più dannoso interrompere che completare. Il limite imposto sul totale dei token di output rimane max_tokens, che tronca la risposta con stop_reason: "max_tokens" quando viene raggiunto.

Per un limite rigido su costo o latenza, combina i budget per attività con un valore ragionevole di max_tokens:

• Usa task_budget per dare a Claude un obiettivo su cui regolare il proprio ritmo.
• Usa max_tokens come tetto assoluto che previene una generazione fuori controllo.

Poiché task_budget copre l'intero ciclo agentico (potenzialmente molte richieste) mentre max_tokens limita ogni singola richiesta, i due valori sono indipendenti; non è necessario che uno sia pari o inferiore all'altro.



Scegliere un budget

Il budget giusto dipende da quanto lavoro svolge attualmente il tuo ciclo agentico. Invece di tirare a indovinare, misura prima il tuo utilizzo di token esistente e poi regola da lì.



Misura il tuo utilizzo attuale

Esegui un campione rappresentativo di attività senza task_budget impostato e registra il totale dei token che Claude spende per attività. Per un ciclo agentico, somma usage.output_tokens più i token di pensiero e dei risultati degli strumenti per ogni richiesta nel ciclo:

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 ciò che Claude ha generato in questo turno (l'output copre testo + pensiero + chiamate agli strumenti).
        # Anche i token dei risultati degli strumenti contano nel budget; aggiungi il conteggio dei token dei
        # blocchi tool_result che accodi qui sotto se vuoi che il tracciamento lato client corrisponda
        # al conto alla rovescia lato server.
        total_spend += response.usage.output_tokens
        if response.stop_reason == "end_turn":
            return total_spend
        # Accoda il turno dell'assistente e i risultati dei tuoi strumenti, poi continua il ciclo.
        messages += [
            {"role": "assistant", "content": response.content},
            {"role": "user", "content": run_tools(response.content)},
        ]

Esegui questo su un insieme rappresentativo di attività e registra la distribuzione. Inizia con il p99 della tua spesa di token per attività per capire come fornire al modello un budget per attività possa modificarne il comportamento, poi testa verso l'alto o verso il basso secondo necessità.

Il valore minimo accettato per task_budget.total è 20.000 token; valori inferiori al minimo restituiscono un errore 400.



Interazione con altri parametri

• max_tokens: Ortogonale ai budget per attività. max_tokens è un limite rigido per richiesta sui token generati, mentre task_budget è un limite indicativo sull'intero ciclo agentico (che potenzialmente copre molte richieste). Con effort xhigh o max, imposta max_tokens ad almeno 64k per dare a Claude spazio per pensare e agire in ogni richiesta.
• Effort: Effort controlla quanto a fondo Claude ragiona per ogni passaggio. I budget per attività controllano quanto lavoro totale Claude svolge in un ciclo agentico. I due sono complementari: effort regola la profondità, i budget per attività regolano l'ampiezza.
• Pensiero adattivo: I budget per attività includono i token di pensiero nel conteggio, quindi il pensiero adattivo si riduce naturalmente man mano che il budget si esaurisce.
• Cache dei prompt: L'indicatore di conto alla rovescia del budget viene iniettato lato server a ogni turno, quindi non corrisponde tra le richieste. Se il tuo client decrementa task_budget.remaining a ogni richiesta successiva, il valore modificato invalida qualsiasi prefisso di cache che lo contiene. Per preservare la cache, imposta il budget una sola volta nella richiesta iniziale e lascia che il modello si autoregoli rispetto al conto alla rovescia lato server invece di modificare il budget lato client.



Supporto della funzionalità

I budget per attività non sono supportati su Claude Code o sulle superfici Cowork. Usa i budget per attività direttamente tramite la Messages API su un modello supportato.