Budget di attività

I budget di attività ti permettono di dire a Claude quanti token ha a disposizione per un ciclo agenziale completo, incluso 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 utilizza per dare priorità al lavoro e terminare elegantemente man mano che il budget viene consumato.

Quando utilizzare i budget di attività

I budget di attività funzionano meglio per i flussi di lavoro agenziali in cui Claude effettua più chiamate agli strumenti e decisioni prima di finalizzare l'output in attesa della prossima risposta umana. Utilizzali quando:

• Vuoi che Claude autoregoli la spesa di token su attività a lungo termine.
• Hai un costo per attività prevedibile o un limite di latenza da applicare.
• Vuoi che il modello termini elegantemente (riassumere i risultati, segnalare i progressi) man mano che si avvicina al budget piuttosto che interrompersi a metà azione.

I budget di attività completano il parametro effort: effort controlla quanto accuratamente Claude ragiona su ogni passaggio, mentre i budget di attività limitano il lavoro totale che Claude può fare in un ciclo agenziale.

Impostazione di un budget di attività

Aggiungi task_budget a output_config e includi l'intestazione beta:

L'oggetto task_budget ha tre campi:

• type: sempre "tokens".
• total: il numero di token che Claude può spendere in tutto il ciclo agenziale, incluso il pensiero, le chiamate agli strumenti, i risultati degli strumenti e l'output.
• remaining (opzionale): il resto del budget trasportato da una richiesta precedente. Predefinito a total quando omesso.

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 agenziale corrente e si aggiorna man mano che il modello genera pensiero, chiamate agli strumenti e output, e mentre elabora i risultati degli strumenti. Claude utilizza questo segnale per regolare il ritmo e terminare elegantemente man mano che il budget viene consumato.

Esempio pratico: conteggio del budget tra i turni

Il budget di attività conta quello che Claude vede (pensiero, chiamate agli strumenti e risultati, e testo), non quello che è nel tuo payload di richiesta. In un ciclo agenziale il tuo client reinvia la conversazione completa su ogni richiesta, quindi il payload cresce turno dopo turno, ma il budget si decrementa solo dai token che Claude vede 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, quindi emette una chiamata agli strumenti 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 agli strumenti) 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, quindi reinvia la cronologia completa con il risultato dello strumento aggiunto:

{
  "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 dell'utente e dell'assistente del turno 1 reinviati non vengono conteggiati di nuovo, ma il risultato dello strumento di 2.800 token è nuovo contenuto che Claude vede questo turno e conta rispetto al budget. Claude spende altri 4.000 token su pensiero e una seconda chiamata agli strumenti (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 grep) aggiunto. Claude scrive un rapporto di risultati finali di 6.000 token e si ferma con stop_reason: "end_turn". remaining ≈ 81.000.

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

Il tuo client ha inviato il messaggio dell'utente del turno 1 tre volte e il messaggio dell'assistente del turno 1 due volte, ma ognuno è stato conteggiato una volta. Il budget ha speso 19.000 di 100.000 token, anche se il payload cumulativo che il tuo client ha trasmesso era più grande e l'input memorizzato nella cache del prompt sui turni 2 e 3 era ancora più grande.

Trasporto di un budget tra la compattazione con remaining

Se il tuo ciclo agenziale 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 sulla richiesta successiva in modo che il conto alla rovescia continui da dove era rimasto piuttosto che ripristinarsi a total:

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

I budget di attività sono consultativi, non applicati

I budget di attività sono un suggerimento soft, non un limite rigido. Claude potrebbe occasionalmente superare il budget se è nel mezzo di un'azione che sarebbe più dirompente interrompere che completare. Il limite applicato sul totale dei token di output è ancora max_tokens, che tronca la risposta con stop_reason: "max_tokens" quando raggiunto.

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

• Usa task_budget per dare a Claude un obiettivo su cui regolare il ritmo.
• Usa max_tokens come il limite assoluto che previene la generazione incontrollata.

Poiché task_budget copre l'intero ciclo agenziale (potenzialmente molte richieste) mentre max_tokens limita ogni singola richiesta, i due valori sono indipendenti; uno non è richiesto di essere a o sotto l'altro.

Scelta di un budget

Il budget giusto dipende da quanto lavoro il tuo ciclo agenziale attualmente fa. Piuttosto che indovinare, misura il tuo utilizzo di token esistente prima e poi sintonizzati 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 agenziale, somma usage.output_tokens più token di pensiero e risultati degli strumenti su ogni richiesta nel ciclo:

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à potrebbe modificare il comportamento del modello, quindi testa su o giù secondo le necessità.

Il task_budget.total minimo accettato è 20.000 token; i valori al di sotto del minimo restituiscono un errore 400.

Interazione con altri parametri

• max_tokens: Ortogonale ai budget di attività. max_tokens è un limite rigido per richiesta sui token generati, mentre task_budget è un limite consigliato su tutto il ciclo agenziale (potenzialmente coprendo molte richieste). A xhigh o max effort, imposta max_tokens ad almeno 64k per dare a Claude spazio per pensare e agire su ogni richiesta.
• Effort: Effort controlla quanto profondamente Claude ragiona per passaggio. I budget di attività controllano quanto lavoro totale Claude fa in un ciclo agenziale. I due sono complementari: effort sintonizza la profondità, i budget di attività sintonizzano l'ampiezza.
• Adaptive thinking: I budget di attività includono i token di pensiero nel conteggio, quindi il pensiero adattivo si ridimensiona naturalmente man mano che il budget si esaurisce.
• Prompt caching: Il marcatore di conto alla rovescia del budget è iniettato lato server per turno, quindi non corrisponde tra le richieste. Se il tuo client decrementa task_budget.remaining su ogni richiesta di follow-up, il valore modificato invalida qualsiasi prefisso della cache che lo contiene. Per preservare la memorizzazione nella cache, imposta il budget una volta sulla richiesta iniziale e lascia che il modello si autoregoli rispetto al conto alla rovescia lato server piuttosto che mutare il budget lato client.

Supporto delle funzionalità

I budget di attività non sono supportati su Claude Code o superfici Cowork al lancio. Usa i budget di attività direttamente tramite l'API Messages su Claude Opus 4.7.