Budget di task

I "task budgets" (budget di task) ti permettono di indicare a Claude quanti token ha a disposizione per un intero ciclo agentico, inclusi il pensiero, le chiamate agli strumenti, i risultati degli strumenti e l'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 di task

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

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

I budget di task sono complementari al parametro effort: effort controlla quanto approfonditamente Claude ragiona su ogni passaggio, mentre i budget di task limitano il lavoro totale che Claude può svolgere nell'arco di un ciclo agentico.



Impostare un budget di task

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

L'oggetto task_budget ha tre campi:

• type: sempre "tokens".
• total: il numero di token che Claude può spendere nell'arco del 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 marcatore di conto alla rovescia del budget iniettato lato server durante tutta la conversazione. Il marcatore 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 di task conta ciò che Claude vede (pensiero, chiamate agli strumenti e relativi risultati, e testo), non ciò che è presente 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 viene decrementato 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) ammonti a 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 utente e assistente 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 in una seconda chiamata allo strumento (grep -rn "eval(" src/). Il conto alla rovescia termina vicino a remaining ≈ 88.200.

Turno 3. Cronologia completa 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 fianco a fianco rende esplicita la distinzione tra dimensione del payload e spesa del budget:

Il tuo client ha inviato il messaggio utente del turno 1 tre volte e il messaggio assistente del turno 1 due volte, ma ciascuno è stato conteggiato una sola volta. Il budget ha speso 19.000 dei 100.000 token, anche se il payload cumulativo trasmesso dal tuo client era più grande e l'input memorizzato nella 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 sia stato speso prima della compattazione. Passa remaining nella richiesta successiva in modo che il conto alla rovescia continui da dove si era interrotto invece di reimpostarsi a total:

# Token consumati prima della compattazione, tracciati lato client
tokens_spent_so_far = 45000

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

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



Modificare il budget a metà conversazione

task_budget è un'impostazione a livello di richiesta. Per modificare il budget a metà di un task, ad esempio per estenderlo quando l'utente amplia la richiesta, imposta un nuovo task_budget in output_config nella richiesta successiva. Tieni presente la conseguenza sulla cache: il valore del budget partecipa al prompt renderizzato, quindi un valore modificato non corrisponde alle voci di cache create con quello precedente (vedi Supporto delle funzionalità di seguito).



I budget di task sono consultivi, non vincolanti

I budget di task sono un suggerimento soft, 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 vincolante sui token di output totali 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 di task con un valore ragionevole di max_tokens:

• Usa task_budget per dare a Claude un obiettivo rispetto al quale regolare il ritmo.
• Usa max_tokens come tetto assoluto che impedisce una generazione incontrollata.

Poiché task_budget copre l'intero ciclo agentico (potenzialmente molte richieste) mentre max_tokens limita ogni singola richiesta, i due valori sono indipendenti; non è richiesto 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 task senza impostare task_budget e registra i token totali che Claude spende per task. Per un ciclo agentico, somma usage.output_tokens su ogni richiesta del ciclo, più i token dei risultati degli strumenti che aggiungi tra le richieste:

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."}
    ],
)

# Somma gli output_tokens (testo + pensiero + chiamate agli strumenti) per ogni richiesta nel tuo ciclo.
print(response.usage.output_tokens)

Esegui questo su un insieme rappresentativo di task e registra la distribuzione. Inizia con il p99 della tua spesa di token per task per capire come fornire al modello un budget di task potrebbe modificarne il comportamento, poi testa valori più alti o più bassi secondo necessità.

Il valore minimo accettato per task_budget.total è specifico per modello; su ogni modello che attualmente supporta i budget di task (vedi Supporto delle funzionalità) è di 20.000 token, e valori inferiori al minimo restituiscono un errore 400.



Interazione con altri parametri

• max_tokens: Ortogonale ai budget di task. max_tokens è un limite rigido per richiesta sui token generati, mentre task_budget è un limite consultivo 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 in profondità Claude ragiona per ogni passaggio. I budget di task controllano quanto lavoro totale Claude svolge nell'arco di un ciclo agentico. I due sono complementari: effort regola la profondità, i budget di task regolano l'ampiezza.
• Pensiero adattivo: I budget di task includono i token di pensiero nel conteggio, quindi il pensiero adattivo si riduce naturalmente man mano che il budget si esaurisce.
• Cache dei prompt: Il marcatore 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 delle funzionalità

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



Passaggi successivi