Budget delle attività

I "task budgets" (budget di attività) ti permettono di indicare a Claude quanti token ha a disposizione per un intero ciclo agentico, inclusi ragionamento, chiamate agli strumenti, risultati degli strumenti e output. Il modello vede un conto alla rovescia aggiornato 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 attività

I budget di attività funzionano al meglio nei flussi di lavoro agentici in cui Claude effettua più chiamate agli strumenti e prende più decisioni prima di finalizzare il proprio 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 di attività sono complementari al parametro effort: effort controlla quanto approfonditamente Claude ragiona su ogni passaggio, mentre i budget di attività limitano il lavoro totale che Claude può svolgere nell'arco di un ciclo agentico.

Impostare un budget di attività

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

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 ragionamento, chiamate agli strumenti, risultati degli strumenti e output.
• remaining (opzionale): il residuo di budget 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 inserito lato server nel corso della conversazione. Il marcatore mostra quanti token rimangono nel ciclo agentico corrente e si aggiorna man mano che il modello genera ragionamento, 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.

Cosa conta come un turno

Il budget copre un turno agentico, chiamato anche ciclo agentico: tutto ciò che Claude fa in risposta a un messaggio utente che non contiene risultati degli strumenti. Un turno può estendersi su più richieste.

Un messaggio utente che non contiene risultati degli strumenti avvia un nuovo turno con un budget nuovo. Attualmente, il conto alla rovescia continua a conteggiare la cronologia dei turni precedenti finché rimane nel contesto. Un caso comune è un messaggio successivo dopo che Claude ha terminato il proprio turno, ad esempio perché il budget si è esaurito:

{ "role": "user", "content": "Continue." }

Un messaggio utente che contiene blocchi tool_result prosegue il turno corrente, perché il tuo client sta risolvendo chiamate agli strumenti che fanno parte di quel turno:

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01", "content": "<npm audit output>" }
  ]
}

Ciò vale anche quando il messaggio aggiunge nuovo contenuto insieme ai risultati degli strumenti:

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01", "content": "<npm audit output>" },
    { "type": "text", "text": "Also check the Dockerfile." }
  ]
}

La compattazione lato server durante un turno non reimposta il budget: i token consumati dal turno prima della compattazione continuano a essere conteggiati. I token precedenti all'inizio del turno non vengono conteggiati, anche quando una compattazione all'inizio di un turno li riassume. Attualmente, tale esclusione si applica solo al budget riportato attraverso una compattazione lato server; la cronologia dei turni precedenti viene ancora conteggiata finché rimane nel contesto.

Esempio pratico: conteggio del budget tra le richieste

Il budget per attività conteggia ciò che Claude vede (ragionamento, chiamate e risultati degli strumenti, 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 continua a crescere, ma il budget diminuisce solo di ciò che è nuovo: i token che Claude genera e il contenuto che non ha mai visto prima. L'esempio seguente è un turno agentico composto da tre richieste: la prima contiene il messaggio utente, e le due successive reinviano ciascuna la cronologia con un risultato dello strumento aggiunto in coda.

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

Richiesta 1. Invii la richiesta iniziale:

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

Claude pensa, poi emette una chiamata a uno 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" }
    }
  ]
}

Supponi che questo messaggio dell'assistente (ragionamento più la chiamata allo strumento) ammonti a 5.000 token generati. Il conto alla rovescia che Claude ha visto durante la generazione si è concluso intorno a remaining ≈ 95.000.

Richiesta 2. Il tuo client esegue lo strumento, poi reinvia l'intera cronologia 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 reinviati dalla richiesta 1 non vengono conteggiati di nuovo, ma il risultato dello strumento da 2.800 token è contenuto nuovo e viene conteggiato nel budget. Claude spende altri 4.000 token in ragionamento e in una seconda chiamata allo strumento (grep -rn "eval(" src/). Il conto alla rovescia si conclude intorno a remaining ≈ 88.200.

Richiesta 3. L'intera cronologia 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 a confronto le tre richieste rende esplicita la distinzione tra dimensione del payload e consumo del budget:

Il tuo client ha inviato il messaggio utente originale tre volte e il primo messaggio dell'assistente due volte, ma ciascuno è stato conteggiato una sola volta. Il budget ha speso 19.000 token su 100.000, anche se il payload cumulativo trasmesso dal tuo client era maggiore e l'input memorizzato nella cache dei prompt nelle richieste 2 e 3 era ancora più grande.

Riportare un budget attraverso la compattazione con remaining

Se il tuo codice compatta o riscrive la cronologia dei messaggi tra una richiesta e l'altra (ad esempio, riassumendo i messaggi 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 prosegua da dove eri rimasto invece di ripartire da total:

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

In questo esempio, i token spesi prima della compattazione corrispondono all'utilizzo di tutti i messaggi che hai rimosso finora dalla cronologia, misurato come in Misura il tuo utilizzo attuale. Escludi tutto ciò che è ancora presente nei messaggi che invii, incluso qualsiasi riassunto che hai aggiunto, perché il server conteggia quei token autonomamente. Aggiorna questo valore solo quando sostituisci la cronologia in questo modo; non decrementarlo a ogni richiesta. Passa il valore remaining risultante in ogni richiesta, non solo in quella che esegue la compattazione.

Per i cicli che reinviano l'intera cronologia non compattata a ogni richiesta, ometti remaining e lascia che sia il server a tenere traccia del conto alla rovescia.

Modificare il budget a metà conversazione

task_budget è un'impostazione a livello di richiesta. Per modificare il budget nel corso di un'attività, 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à più sotto).

I budget di attività sono indicativi, non vincolanti

I budget di 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 vincolante sui token di output totali resta 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 attività 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 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 è 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 indovinare, misura prima il tuo utilizzo di token esistente e poi regola a partire da lì.

Misura il tuo utilizzo attuale

Esegui un campione rappresentativo di attività senza task_budget impostato e registra i token totali che Claude spende per attività. 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-5",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Review the codebase and propose a refactor plan."}
    ],
)

# Somma output_tokens (testo + thinking + chiamate agli strumenti) su tutte le richieste del tuo ciclo.
print(response.usage.output_tokens)

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 di attività possa modificarne il comportamento, poi prova ad aumentare o diminuire secondo necessità.

Il valore minimo accettato per task_budget.total è 20.000 token su tutti i modelli che supportano i budget per attività (vedi Supporto delle funzionalità). Valori inferiori restituiscono un errore 400.

Interazione con altri parametri

• max_tokens: Indipendente dai budget per attività. max_tokens è un limite rigido per richiesta sui token generati, mentre task_budget è un limite indicativo sull'intero ciclo agentico (che può estendersi su molte richieste). Con effort xhigh o max, imposta max_tokens ad almeno 64k per dare a Claude spazio per ragionare e agire in ogni richiesta.
• Effort: Effort controlla quanto in profondità Claude ragiona a ogni passaggio. I budget per attività controllano quanto lavoro totale Claude svolge nell'arco di un ciclo agentico. I due sono complementari: effort regola la profondità, i budget per attività regolano l'ampiezza.
• Ragionamento adattivo: I budget per attività includono i token di ragionamento nel conteggio, quindi il ragionamento adattivo si riduce man mano che il budget si esaurisce.
• Cache dei prompt: Il marcatore di conto alla rovescia del budget viene inserito lato server a ogni richiesta, quindi non corrisponde tra una richiesta e l'altra. 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 in base al conto alla rovescia lato server, invece di modificare il budget lato client.

Supporto delle funzionalità

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

Passaggi successivi

Compatibility