---
title: Budget delle attività
url: https://platform.claude.com/docs/it/build-with-claude/task-budgets
description: Fornisci a Claude un budget di token indicativo per l'intero ciclo agentico, per aiutare il modello ad autoregolarsi nelle attività agentiche lunghe.
featureMetadata:
  status: beta
  betaHeader: task-budgets-2026-03-13
  supportedModels:
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-opus-5-5
    - claude-opus-5
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-sonnet-5-5
    - claude-haiku-5-5
---

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](https://platform.claude.com/docs/it/build-with-claude/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:

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -N \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: task-budgets-2026-03-13" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 128000,
      "stream": true,
      "messages": [{
        "role": "user",
        "content": "Review the codebase and propose a refactor plan."
      }],
      "output_config": {
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 64000}
      }
    }'
  ```

  ```bash CLI
  ant beta:messages create --beta task-budgets-2026-03-13 \
    --stream --format jsonl <<'YAML' | jq 'select(.type == "message_delta").usage'
  model: claude-opus-5-5
  max_tokens: 128000
  messages:
    - role: user
      content: Review the codebase and propose a refactor plan.
  output_config:
    effort: high
    task_budget:
      type: tokens
      total: 64000
  YAML
  ```

  ```python Python
  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)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const stream = 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"]
  });

  const response = await stream.finalMessage();
  console.log(response.usage);
  ```

  ```csharp C#

  var client = new AnthropicClient();

  var responseUpdates = client.Beta.Messages.CreateStreaming(new MessageCreateParams
  {
      Model = Messages::Model.ClaudeOpus5_5,
      MaxTokens = 128000,
      Messages = [new() { Role = Role.User, Content = "Review the codebase and propose a refactor plan." }],
      OutputConfig = new BetaOutputConfig
      {
          Effort = Effort.High,
          TaskBudget = new BetaTokenTaskBudget { Total = 64000 },
      },
      Betas = ["task-budgets-2026-03-13"],
  });

  var response = await responseUpdates.Aggregate();
  Console.WriteLine(response.Usage);
  ```

  ```go Go
  client := anthropic.NewClient()

  stream := client.Beta.Messages.NewStreaming(context.TODO(), anthropic.BetaMessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 128000,
  	Betas:     []anthropic.AnthropicBeta{"task-budgets-2026-03-13"},
  	Messages: []anthropic.BetaMessageParam{{
  		Role: anthropic.BetaMessageParamRoleUser,
  		Content: []anthropic.BetaContentBlockParamUnion{{
  			OfText: &anthropic.BetaTextBlockParam{Text: "Review the codebase and propose a refactor plan."},
  		}},
  	}},
  	OutputConfig: anthropic.BetaOutputConfigParam{
  		Effort: anthropic.BetaOutputConfigEffortHigh,
  		TaskBudget: anthropic.BetaTokenTaskBudgetParam{
  			Total: 64000,
  		},
  	},
  })

  message := anthropic.BetaMessage{}
  for stream.Next() {
  	event := stream.Current()
  	if err := message.Accumulate(event); err != nil {
  		panic(err)
  	}
  }
  if stream.Err() != nil {
  	panic(stream.Err())
  }

  fmt.Printf("Usage: input_tokens=%d, output_tokens=%d\n", message.Usage.InputTokens, message.Usage.OutputTokens)
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_OPUS_5_5)
      .maxTokens(128000L)
      .addUserMessage("Review the codebase and propose a refactor plan.")
      .outputConfig(BetaOutputConfig.builder()
          .effort(BetaOutputConfig.Effort.HIGH)
          .taskBudget(BetaTokenTaskBudget.builder().total(64000L).build())
          .build())
      .addBeta("task-budgets-2026-03-13")
      .build();

  BetaMessageAccumulator accumulator = BetaMessageAccumulator.create();
  try (StreamResponse<BetaRawMessageStreamEvent> stream =
          client.beta().messages().createStreaming(params)) {
      stream.stream().forEach(accumulator::accumulate);
  }

  BetaMessage response = accumulator.message();
  IO.println(response.usage());
  ```

  ```php PHP
  use Anthropic\Beta\Messages\BetaRawMessageDeltaEvent;

  $client = new Client();

  $stream = $client->beta->messages->createStream(
      model: 'claude-opus-5-5',
      maxTokens: 128000,
      messages: [
          ['role' => 'user', 'content' => 'Review the codebase and propose a refactor plan.'],
      ],
      outputConfig: [
          'effort' => 'high',
          'taskBudget' => ['type' => 'tokens', 'total' => 64000],
      ],
      betas: ['task-budgets-2026-03-13'],
  );

  // L'evento message_delta finale contiene l'utilizzo cumulativo dei token per la richiesta.
  $usage = null;
  foreach ($stream as $event) {
      if ($event instanceof BetaRawMessageDeltaEvent) {
          $usage = $event->usage;
      }
  }

  echo $usage;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  stream = client.beta.messages.stream(
    model: "claude-opus-5-5",
    max_tokens: 128_000,
    messages: [
      { role: "user", content: "Review the codebase and propose a refactor plan." }
    ],
    output_config: {
      effort: :high,
      task_budget: { type: :tokens, total: 64_000 }
    },
    betas: ["task-budgets-2026-03-13"]
  )

  response = stream.accumulated_message

  puts response.usage
  ```
</CodeGroup>

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.

<Note>
  **Il conto alla rovescia è visibile solo al modello.** Le risposte dell'API non includono un campo con il budget residuo: non ci sono informazioni su `task_budget` nell'oggetto `usage` della risposta e l'SDK non dispone di un metodo di accesso per esso. Per monitorare la spesa lato client, somma l'utilizzo dei token tra le richieste del tuo ciclo come mostrato in [Misura il tuo utilizzo attuale](https://platform.claude.com/docs/it/build-with-claude/task-budgets#measure-your-current-usage), oppure passa il tuo valore con `remaining` quando [riporti un budget attraverso la compattazione](https://platform.claude.com/docs/it/build-with-claude/task-budgets#carrying-a-budget-across-compaction-with-remaining).
</Note>

<Warning>
  **Il conto alla rovescia riflette i token che Claude ha elaborato nel ciclo agentico corrente, non i token che reinvii tra una richiesta e l'altra.** Se il tuo client invia l'intera cronologia della conversazione a ogni richiesta successiva, il conteggio dei token lato client potrebbe differire dal budget che Claude sta monitorando. Se decrementi anche `remaining` mentre reinvii l'intera cronologia, il modello vede un budget sottostimato e il conto alla rovescia scende più velocemente del dovuto, facendo sì che Claude concluda prima di quanto il budget consenta effettivamente. Imposta un budget generoso e lascia che il modello si autoregoli in base al conto alla rovescia, anziché cercare di replicarlo lato client.
</Warning>

### 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:

```json
{ "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:

```json
{
  "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:

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

La [compattazione](https://platform.claude.com/docs/it/build-with-claude/compaction-threshold) 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](https://platform.claude.com/docs/it/build-with-claude/task-budgets#what-counts-as-a-turn) 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:

```json
{
  "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"`:

```json
{
  "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:

```json
{
  "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:

| Richiesta  | Payload della richiesta (token di input inviati, approssimativi)   | Token conteggiati nel budget in questa richiesta                          | `remaining` del budget dopo la richiesta |
| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------- | ---------------------------------------- |
| 1          | \~20                                                               | 5.000 (ragionamento + `tool_use`)                                         | \~95.000                                 |
| 2          | \~7.800 (messaggi della richiesta 1 + risultato dello strumento)   | 6.800 (2.800 risultato dello strumento + 4.000 ragionamento e `tool_use`) | \~88.200                                 |
| 3          | \~13.000 (cronologia completa + secondo risultato dello strumento) | 7.200 (1.200 risultato dello strumento + 6.000 `text`)                    | \~81.000                                 |
| **Totale** | **\~20.820 inviati nel complesso delle richieste**                 | **19.000 conteggiati nel budget**                                         | N/D                                      |

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`:

<CodeGroup exclude="shell">
  ```python Python
  # 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,
      },
  }
  ```

  ```typescript TypeScript
  // Token spesi prima della compattazione, tracciati lato client
  const tokensSpentSoFar = 45000;

  const outputConfig = {
    effort: "high",
    task_budget: {
      type: "tokens",
      total: 128000,
      remaining: 128000 - tokensSpentSoFar
    }
  };
  ```

  ```csharp C#
  // Token consumati prima della compattazione, tracciati lato client
  var tokensSpentSoFar = 45000;

  var outputConfig = new BetaOutputConfig
  {
      Effort = Effort.High,
      TaskBudget = new BetaTokenTaskBudget
      {
          Total = 128000,
          Remaining = 128000 - tokensSpentSoFar,
      },
  };
  ```

  ```go Go
  // Token spesi prima della compattazione, tracciati lato client
  tokensSpentSoFar := int64(45000)

  outputConfig := anthropic.BetaOutputConfigParam{
  	Effort: anthropic.BetaOutputConfigEffortHigh,
  	TaskBudget: anthropic.BetaTokenTaskBudgetParam{
  		Total:     128000,
  		Remaining: anthropic.Int(128000 - tokensSpentSoFar),
  	},
  }
  ```

  ```java Java
  // Token spesi prima della compattazione, tracciati lato client
  long tokensSpentSoFar = 45000;

  BetaOutputConfig outputConfig = BetaOutputConfig.builder()
      .effort(BetaOutputConfig.Effort.HIGH)
      .taskBudget(BetaTokenTaskBudget.builder()
          .total(128000L)
          .remaining(128000L - tokensSpentSoFar)
          .build())
      .build();
  ```

  ```php PHP
  // Token spesi prima della compattazione, tracciati lato client
  $tokensSpentSoFar = 45000;

  $outputConfig = [
      'effort' => 'high',
      'taskBudget' => [
          'type' => 'tokens',
          'total' => 128000,
          'remaining' => 128000 - $tokensSpentSoFar,
      ],
  ];
  ```

  ```ruby Ruby
  # Token spesi prima della compattazione, tracciati lato client
  tokens_spent_so_far = 45_000

  output_config = {
    effort: :high,
    task_budget: {
      type: :tokens,
      total: 128_000,
      remaining: 128_000 - tokens_spent_so_far
    }
  }
  ```
</CodeGroup>

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](https://platform.claude.com/docs/it/build-with-claude/task-budgets#measure-your-current-usage). 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à](https://platform.claude.com/docs/it/build-with-claude/task-budgets#feature-support) 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.

<Warning>
  **Un budget troppo piccolo per l'attività può causare comportamenti simili a un rifiuto.** Quando Claude vede un budget chiaramente insufficiente per il lavoro richiesto (ad esempio, un budget di 20.000 token per un'attività di coding agentico di più ore), potrebbe rifiutarsi del tutto di tentare l'attività, ridurne drasticamente l'ambito, oppure fermarsi in anticipo con un risultato parziale invece di iniziare un lavoro che non può completare. Se osservi rifiuti inattesi o interruzioni premature dopo aver impostato un budget, aumenta il budget prima di fare debug di altri parametri. Dimensiona i budget in base alla distribuzione effettiva della lunghezza delle tue attività invece che su un valore predefinito fisso; vedi [Scegliere un budget](https://platform.claude.com/docs/it/build-with-claude/task-budgets#choosing-a-budget).
</Warning>

## 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:

<CodeGroup exclude="shell:cURL">
  ```bash CLI
  ant messages create --transform 'usage.output_tokens' <<'YAML'
  model: claude-opus-5-5
  max_tokens: 4096
  messages:
    - role: user
      content: Review the codebase and propose a refactor plan.
  YAML
  ```

  ```python Python
  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)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const response = await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 4096,
    messages: [{ role: "user", content: "Review the codebase and propose a refactor plan." }]
  });

  // Somma gli output_tokens (testo + thinking + chiamate agli strumenti) di tutte le richieste del tuo ciclo.
  console.log(response.usage.output_tokens);
  ```

  ```csharp C#

  var client = new AnthropicClient();

  var response = await client.Messages.Create(new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 4096,
      Messages = [new() { Role = Role.User, Content = "Review the codebase and propose a refactor plan." }],
  });

  // Somma OutputTokens (testo + thinking + chiamate agli strumenti) su tutte le richieste del tuo ciclo.
  Console.WriteLine(response.Usage.OutputTokens);
  ```

  ```go Go
  client := anthropic.NewClient()

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 4096,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Review the codebase and propose a refactor plan.")),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }

  // Somma OutputTokens (testo + thinking + chiamate agli strumenti) su tutte le richieste del tuo ciclo.
  fmt.Println(response.Usage.OutputTokens)
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_OPUS_5_5)
      .maxTokens(4096L)
      .addUserMessage("Review the codebase and propose a refactor plan.")
      .build();

  Message response = client.messages().create(params);
  // Somma outputTokens (testo + thinking + chiamate agli strumenti) su tutte le richieste del tuo ciclo.
  IO.println(response.usage().outputTokens());
  ```

  ```php PHP
  $client = new Client();

  $response = $client->messages->create(
      model: 'claude-opus-5-5',
      maxTokens: 4096,
      messages: [
          ['role' => 'user', 'content' => 'Review the codebase and propose a refactor plan.'],
      ],
  );

  // Somma outputTokens (testo + thinking + chiamate agli strumenti) su tutte le richieste del tuo ciclo.
  echo $response->usage->outputTokens . "\n";
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  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 gli output_tokens (testo + ragionamento + chiamate agli strumenti) di ogni richiesta nel tuo ciclo.
  puts response.usage.output_tokens
  ```
</CodeGroup>

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à](https://platform.claude.com/docs/it/build-with-claude/task-budgets#feature-support)). 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](https://platform.claude.com/docs/it/build-with-claude/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](https://platform.claude.com/docs/it/build-with-claude/thinking):** 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](https://platform.claude.com/docs/it/build-with-claude/prompt-caching):** 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à

| Modello           | Supporto                                          |
| ----------------- | ------------------------------------------------- |
| Claude Fable 5.1  | Beta (imposta l'header `task-budgets-2026-03-13`) |
| Claude Mythos 5.1 | Beta (imposta l'header `task-budgets-2026-03-13`) |
| Claude Opus 5.5   | Beta (imposta l'header `task-budgets-2026-03-13`) |
| Claude Opus 5     | Beta (imposta l'header `task-budgets-2026-03-13`) |
| Claude Fable 5    | Beta (imposta l'header `task-budgets-2026-03-13`) |
| Claude Mythos 5   | Beta (imposta l'header `task-budgets-2026-03-13`) |
| Claude Sonnet 5.5 | Beta (imposta l'header `task-budgets-2026-03-13`) |
| Claude Sonnet 5   | Non supportato                                    |
| Claude Haiku 5.5  | Beta (imposta l'header `task-budgets-2026-03-13`) |
| Claude Opus 4.8   | Beta (imposta l'header `task-budgets-2026-03-13`) |
| Claude Opus 4.7   | Beta (imposta l'header `task-budgets-2026-03-13`) |
| Claude Opus 4.6   | Non supportato                                    |
| Claude Sonnet 4.6 | Non supportato                                    |
| Claude Haiku 4.5  | Non supportato                                    |

I budget di attività non sono supportati su [Claude Code](https://code.claude.com/docs/it/overview) o sulle superfici Cowork. Usa i budget di attività direttamente tramite la Messages API su un [modello supportato](https://platform.claude.com/docs/it/build-with-claude/task-budgets#feature-support).

## Passaggi successivi

<CardGroup>
  <Card title="Effort" icon="gauge" href="https://platform.claude.com/docs/it/build-with-claude/effort">
    Controlla quanto approfonditamente Claude ragiona su ogni passaggio di un ciclo agentico.
  </Card>

  <Card title="Ragionamento adattivo" icon="brain" href="https://platform.claude.com/docs/it/build-with-claude/thinking">
    Lascia che Claude determini quando e quanto usare il ragionamento esteso.
  </Card>

  <Card title="Compattazione" icon="arrows-clockwise" href="https://platform.claude.com/docs/it/build-with-claude/compaction">
    Gestisci il contesto nelle conversazioni di lunga durata con la compattazione lato server.
  </Card>

  <Card title="Cache dei prompt" icon="database" href="https://platform.claude.com/docs/it/build-with-claude/prompt-caching">
    Riduci costi e latenza sui prompt ripetuti memorizzando nella cache i prefissi dei prompt.
  </Card>
</CardGroup>