--- title: Ragionamento url: https://platform.claude.com/docs/it/build-with-claude/thinking description: "Comprendi come funziona il thinking di Claude: attivalo, leggi l'output del thinking, regola la profondità del thinking con effort e usa il thinking con strumenti, cache e streaming." --- Per scoprire come la "zero data retention" (conservazione zero dei dati), o ZDR, si applica a questa funzionalità, consulta [API e conservazione dei dati](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention). Un modello che risponde in un unico passaggio deve fare tutto correttamente al primo tentativo: niente lavoro di bozza, niente verifiche, nessun cambio di rotta a metà strada. Per una dimostrazione, un bug insidioso o un lungo compito agentico, il primo approccio spesso non è il migliore. Il "thinking" (ragionamento) elimina questo vincolo. Quando il ragionamento è attivo, Claude elabora il problema con parole proprie prima di rispondere: riformula ciò che viene chiesto, prova diversi approcci, verifica i risultati intermedi e abbandona i percorsi che non reggono. Questo ragionamento iniziale arriva in blocchi di contenuto `thinking` prima della risposta, e Claude vi attinge per produrre la risposta finale. Ecco perché il ragionamento migliora le prestazioni su compiti complessi come matematica, programmazione, analisi e lavoro agentico di lunga durata, dove la qualità della risposta dipende da un lavoro intermedio che altrimenti verrebbe compresso nella risposta stessa o saltato. Il thinking ha un costo: i token che Claude spende ragionando vengono fatturati come token di output, anche quando il testo del thinking non ti viene restituito, e contano ai fini di `max_tokens` insieme al testo della risposta. Questa pagina descrive come si comporta il thinking nell'intera superficie dell'API: come attivarlo, come leggerne l'output e come gestirne le interazioni con strumenti, streaming, cache e "context window" (finestra di contesto). ## Come funziona il ragionamento ![Diagramma: Claude determina se ragionare in anticipo, può ragionare tra le chiamate agli strumenti e restituisce i blocchi di ragionamento prima del testo](https://platform.claude.com/docs/it/images/how-thinking-works.svg) Se Claude ragiona su una determinata richiesta, e con quale profondità, dipende dalla tua configurazione del ragionamento e dalla complessità della richiesta. Ecco come appare il ragionamento iniziale in una risposta: uno o più blocchi di contenuto `thinking` arrivano prima dei blocchi `text`. Il blocco di ragionamento è comunque contenuto generato, come il blocco `text` che lo segue, ma è separato dalla risposta canonica. Ogni blocco di ragionamento contiene anche un campo `signature`, una copia crittografata del ragionamento completo che devi restituire invariata nelle conversazioni multi-turno e con uso degli strumenti (vedi [Crittografia del ragionamento](https://platform.claude.com/docs/it/build-with-claude/thinking#thinking-encryption)): ```json { "content": [ { "type": "thinking", "thinking": "Let me break this down. The question has two parts, so I'll start with the simpler one and use its result to constrain the second...", "signature": "WaUjzkypQ2mUEVM36O2Txu...." }, { "type": "text", "text": "Based on my analysis..." } ] } ``` Non sempre vedi questo testo, e ciò che vedi non è mai la catena di pensiero grezza: il testo in un blocco di ragionamento è un [riepilogo del ragionamento di Claude](https://platform.claude.com/docs/it/build-with-claude/thinking#summarized-thinking). Il campo `display` nella configurazione del ragionamento controlla se quel riepilogo viene restituito o meno: `"summarized"` lo restituisce, mentre `"omitted"`, il valore predefinito su molti modelli, restituisce blocchi di ragionamento con un campo `thinking` vuoto. In entrambi i casi il blocco viene fatturato allo stesso modo e restituito allo stesso modo nelle conversazioni multi-turno. Vedi [Controllare la visualizzazione del ragionamento](https://platform.claude.com/docs/it/build-with-claude/thinking#controlling-thinking-display) per i valori predefiniti per modello e i dettagli. Se Claude usa strumenti, il ragionamento può comparire anche tra le chiamate agli strumenti. Vedi [Ragionamento con uso degli strumenti](https://platform.claude.com/docs/it/build-with-claude/thinking#thinking-with-tool-use). Per il formato completo della risposta, consulta il [riferimento della Messages API](https://platform.claude.com/docs/it/api/messages/create). ## Configurare il ragionamento Sulla maggior parte dei modelli, il ragionamento è attivo per impostazione predefinita o basta un parametro per attivarlo. La tabella seguente mostra cosa fa ciascun modello con ciascun valore di `thinking` che una richiesta può inviare. Un errore 400 significa che l'API rifiuta la richiesta, e [Risoluzione dei problemi del ragionamento](https://platform.claude.com/docs/it/build-with-claude/thinking-troubleshooting) riporta ogni errore e la relativa soluzione. | Modello | Nessun campo `thinking` | `"adaptive"` | `"enabled"` con `budget_tokens` | `"between_tools"` | `"disabled"` | | --------------------- | ------------------------ | --------------------- | ------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------ | | Claude Opus 5.5 | Ragionamento adattivo | Ragionamento adattivo | Errore 400 | Errore 400 | Errore 400 | | Claude Sonnet 5.5 | Ragionamento adattivo | Ragionamento adattivo | Errore 400 | Ragionamento iniziale disattivato con effort `high` o inferiore | Errore 400 | | Claude Haiku 5.5 | Ragionamento adattivo | Ragionamento adattivo | Errore 400 | Errore 400 | Ragionamento disattivato con effort `high` o inferiore | | Claude Fable 5.1 | Ragionamento adattivo | Ragionamento adattivo | Errore 400 | Errore 400 | Errore 400 | | Claude Mythos 5.1 | Ragionamento adattivo | Ragionamento adattivo | Errore 400 | Errore 400 | Errore 400 | | Claude Fable 5 | Ragionamento adattivo | Ragionamento adattivo | Errore 400 | Errore 400 | Errore 400 | | Claude Mythos 5 | Ragionamento adattivo | Ragionamento adattivo | Errore 400 | Errore 400 | Errore 400 | | Claude Opus 5 | Ragionamento adattivo | Ragionamento adattivo | Errore 400 | Errore 400 | Ragionamento disattivato con effort `high` o inferiore | | Claude Sonnet 5 | Ragionamento adattivo | Ragionamento adattivo | Errore 400 | Errore 400 | Ragionamento disattivato | | Claude Opus 4.8 | Ragionamento disattivato | Ragionamento adattivo | Errore 400 | Errore 400 | Ragionamento disattivato | | Claude Opus 4.7 | Ragionamento disattivato | Ragionamento adattivo | Errore 400 | Errore 400 | Ragionamento disattivato | | Claude Mythos Preview | Ragionamento adattivo | Ragionamento adattivo | Ragionamento esteso | Errore 400 | Errore 400 | | Claude Opus 4.6 | Ragionamento disattivato | Ragionamento adattivo | Ragionamento esteso (deprecato) | Errore 400 | Ragionamento disattivato | | Claude Sonnet 4.6 | Ragionamento disattivato | Ragionamento adattivo | Ragionamento esteso (deprecato) | Errore 400 | Ragionamento disattivato | | Claude Opus 4.5 | Ragionamento disattivato | Errore 400 | Ragionamento esteso | Errore 400 | Ragionamento disattivato | | Claude Sonnet 4.5 | Ragionamento disattivato | Errore 400 | Ragionamento esteso | Errore 400 | Ragionamento disattivato | | Claude Haiku 4.5 | Ragionamento disattivato | Errore 400 | Ragionamento esteso | Errore 400 | Ragionamento disattivato | Nella tabella, "con effort `high` o inferiore" significa che la richiesta funziona con effort `low`, `medium` e `high` e restituisce un errore 400 con `xhigh` o `max`. Su Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Sonnet 5, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview e Claude Haiku 5.5, il ragionamento è già attivo e non richiede alcuna configurazione. Su questi modelli `display` ha come valore predefinito `"omitted"`, quindi il testo del ragionamento resta nascosto finché non scegli di mostrarlo. Per farlo, usa `thinking: {"type": "adaptive", "display": "summarized"}`, come negli esempi seguenti. Su Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 e Claude Sonnet 4.6, il ragionamento è disattivato finché non imposti `thinking: {type: "adaptive"}`, che consente a Claude di determinare quando e con quale profondità ragionare in base alla richiesta. La stessa richiesta, con la [stringa del modello](https://platform.claude.com/docs/it/models/overview) sostituita, lo attiva su quei modelli. Gli esempi seguenti impostano `display: "summarized"` in modo che il testo del ragionamento sia visibile e usano un `max_tokens` ampio: ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 16000, "thinking": { "type": "adaptive", "display": "summarized" }, "messages": [ { "role": "user", "content": "What is the greatest common divisor of 1071 and 462?" } ] }' ``` ```bash CLI ant messages create \ --model claude-opus-5-5 \ --max-tokens 16000 \ --thinking '{type: adaptive, display: summarized}' \ --message '{role: user, content: "What is the greatest common divisor of 1071 and 462?"}' \ --transform content \ --format yaml ``` ```python Python client = anthropic.Anthropic() response = client.messages.create( model="claude-opus-5-5", max_tokens=16000, thinking={"type": "adaptive", "display": "summarized"}, messages=[ { "role": "user", "content": "What is the greatest common divisor of 1071 and 462?", } ], ) for block in response.content: match block.type: case "thinking": print(f"\nThinking: {block.thinking}") case "text": print(f"\nResponse: {block.text}") ``` ```typescript TypeScript const client = new Anthropic(); const response = await client.messages.create({ model: "claude-opus-5-5", max_tokens: 16000, thinking: { type: "adaptive", display: "summarized" }, messages: [ { role: "user", content: "What is the greatest common divisor of 1071 and 462?" } ] }); for (const block of response.content) { switch (block.type) { case "thinking": console.log(`\nThinking: ${block.thinking}`); break; case "text": console.log(`\nResponse: ${block.text}`); break; } } ``` ```csharp C# AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus5_5, MaxTokens = 16000, Thinking = new ThinkingConfigAdaptive { Display = Display.Summarized }, Messages = [ new() { Role = Role.User, Content = "What is the greatest common divisor of 1071 and 462?" } ] }; var message = await client.Messages.Create(parameters); foreach (var block in message.Content) { if (block.TryPickThinking(out ThinkingBlock? thinking)) { Console.WriteLine($"\nThinking: {thinking.Thinking}"); } else if (block.TryPickText(out TextBlock? text)) { Console.WriteLine($"\nResponse: {text.Text}"); } } ``` ```go Go client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 16000, Thinking: anthropic.ThinkingConfigParamUnion{ OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{ Display: anthropic.ThinkingConfigAdaptiveDisplaySummarized, }, }, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("What is the greatest common divisor of 1071 and 462?")), }, }) if err != nil { log.Fatal(err) } for _, block := range response.Content { switch v := block.AsAny().(type) { case anthropic.ThinkingBlock: fmt.Printf("\nThinking: %s", v.Thinking) case anthropic.TextBlock: fmt.Printf("\nResponse: %s", v.Text) } } ``` ```java Java import com.anthropic.models.messages.ThinkingConfigAdaptive; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(16000L) .thinking(ThinkingConfigAdaptive.builder() .display(ThinkingConfigAdaptive.Display.SUMMARIZED) .build()) .addUserMessage("What is the greatest common divisor of 1071 and 462?") .build(); Message response = client.messages().create(params); response.content().forEach(block -> { block.thinking().ifPresent(thinkingBlock -> IO.println("\nThinking: " + thinkingBlock.thinking()) ); block.text().ifPresent(textBlock -> IO.println("\nResponse: " + textBlock.text()) ); }); } ``` ```php PHP use Anthropic\Messages\TextBlock; use Anthropic\Messages\ThinkingBlock; $client = new Client(); $message = $client->messages->create( maxTokens: 16000, messages: [ [ 'role' => 'user', 'content' => 'What is the greatest common divisor of 1071 and 462?' ] ], model: 'claude-opus-5-5', thinking: ['type' => 'adaptive', 'display' => 'summarized'], ); foreach ($message->content as $block) { switch (true) { case $block instanceof ThinkingBlock: echo "\nThinking: " . $block->thinking; break; case $block instanceof TextBlock: echo "\nResponse: " . $block->text; break; } } ``` ```ruby Ruby client = Anthropic::Client.new message = client.messages.create( model: "claude-opus-5-5", max_tokens: 16000, thinking: { type: "adaptive", # Un hash semplice come questo accetta display:. La classe tipizzata ThinkingConfigAdaptive # lo scrive display_ (con underscore finale) per non oscurare Kernel#display di Ruby. # La richiesta invia comunque display. display: "summarized" }, messages: [ { role: "user", content: "What is the greatest common divisor of 1071 and 462?" } ] ) message.content.each do |block| case block when Anthropic::Models::ThinkingBlock puts "\nThinking: #{block.thinking}" when Anthropic::Models::TextBlock puts "\nResponse: #{block.text}" end end ``` L'esecuzione dell'esempio stampa il ragionamento riassunto, poi la risposta: ```text Output wrap Thinking: Use Euclidean algorithm. 1071 = 2*462 + 147 462 = 3*147 + 21 147 = 7*21 + 0 GCD = 21 Response: ## Finding GCD of 1071 and 462 I'll use the **Euclidean algorithm**, repeatedly dividing and taking remainders... ``` I token di ragionamento contano ai fini di `max_tokens`, quindi impostalo abbastanza alto da lasciare spazio sia al ragionamento sia al testo della risposta. Vedi [Controllo dei costi](https://platform.claude.com/docs/it/build-with-claude/thinking-steering-and-cost#cost-control) nella pagina sulla regolazione e [Ragionamento e finestra di contesto](https://platform.claude.com/docs/it/build-with-claude/thinking#thinking-and-the-context-window). ### Disattivare il ragionamento Su Claude Sonnet 5, dove il ragionamento è attivo per impostazione predefinita, puoi disattivarlo: ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-5", "max_tokens": 4096, "thinking": {"type": "disabled"}, "messages": [ { "role": "user", "content": "Summarize this article in one sentence." } ] }' ``` ```bash CLI ant messages create \ --model claude-sonnet-5 \ --max-tokens 4096 \ --thinking '{type: disabled}' \ --message '{role: user, content: "Summarize this article in one sentence."}' ``` ```python Python client = anthropic.Anthropic() response = client.messages.create( model="claude-sonnet-5", max_tokens=4096, thinking={"type": "disabled"}, messages=[{"role": "user", "content": "Summarize this article in one sentence."}], ) ``` ```typescript TypeScript const client = new Anthropic(); const response = await client.messages.create({ model: "claude-sonnet-5", max_tokens: 4096, thinking: { type: "disabled" }, messages: [{ role: "user", content: "Summarize this article in one sentence." }] }); ``` ```csharp C# AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeSonnet5, MaxTokens = 4096, Thinking = new ThinkingConfigDisabled(), Messages = [ new() { Role = Role.User, Content = "Summarize this article in one sentence." } ] }; var message = await client.Messages.Create(parameters); ``` ```go Go client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeSonnet5, MaxTokens: 4096, Thinking: anthropic.ThinkingConfigParamUnion{ OfDisabled: &anthropic.ThinkingConfigDisabledParam{}, }, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Summarize this article in one sentence.")), }, }) if err != nil { log.Fatal(err) } ``` ```java Java import com.anthropic.models.messages.ThinkingConfigDisabled; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_SONNET_5) .maxTokens(4096L) .thinking(ThinkingConfigDisabled.builder().build()) .addUserMessage("Summarize this article in one sentence.") .build(); Message response = client.messages().create(params); } ``` ```php PHP $client = new Client(); $message = $client->messages->create( maxTokens: 4096, messages: [ [ 'role' => 'user', 'content' => 'Summarize this article in one sentence.' ] ], model: 'claude-sonnet-5', thinking: ['type' => 'disabled'], ); ``` ```ruby Ruby client = Anthropic::Client.new message = client.messages.create( model: "claude-sonnet-5", max_tokens: 4096, thinking: { type: "disabled" }, messages: [ { role: "user", content: "Summarize this article in one sentence." } ] ) ``` Anche Claude Opus 5 ha il ragionamento attivo per impostazione predefinita e accetta `thinking: {type: "disabled"}` con "[effort](https://platform.claude.com/docs/it/build-with-claude/effort)" (livello di impegno) `high` o inferiore. Con effort `xhigh` o `max`, il ragionamento non può essere disattivato: le richieste che combinano `thinking: {type: "disabled"}` con questi livelli di effort restituiscono un errore 400. Questa restrizione viene applicata a ogni richiesta. Con il ragionamento disattivato, Claude Opus 5 può occasionalmente emettere chiamate agli strumenti come testo semplice o includere tag XML interni nel suo output visibile. Vedi [Esecuzione con il ragionamento disabilitato](https://platform.claude.com/docs/it/build-with-claude/prompt-engineering/prompting-claude-opus-5#running-with-thinking-disabled) per le mitigazioni tramite prompt. Anche Claude Sonnet 5.5 ha il ragionamento attivo per impostazione predefinita, e rifiuta `thinking: {type: "disabled"}` con un errore 400. Per disattivare il ragionamento iniziale, invia invece `thinking: {type: "between_tools"}`. È l'impostazione di ragionamento più bassa su Claude Sonnet 5.5 ed è accettata con [effort](https://platform.claude.com/docs/it/build-with-claude/effort) `high` o inferiore. Il modello restituisce comunque i suoi [aggiornamenti di avanzamento tra le chiamate agli strumenti](https://platform.claude.com/docs/it/build-with-claude/thinking#progress-updates). Senza strumenti, la risposta contiene solo testo, come con `disabled` su Claude Sonnet 5. Vedi [Esecuzione senza ragionamento iniziale](https://platform.claude.com/docs/it/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#running-without-up-front-thinking) per indicazioni sui prompt. Anche Claude Haiku 5.5 ha il ragionamento attivo per impostazione predefinita e accetta `thinking: {type: "disabled"}` con [effort](https://platform.claude.com/docs/it/build-with-claude/effort) `high` o inferiore. Con effort `xhigh` o `max`, questa combinazione restituisce un errore 400. Per ottenere meno ragionamento, abbassa prima il livello di effort. Con il ragionamento disattivato, il modello può saltare una chiamata a uno strumento di cui ha bisogno quando richiedi anche un output JSON. Anche un [`output_config.effort` per messaggio](https://platform.claude.com/docs/it/build-with-claude/effort#change-effort-mid-conversation-beta) diverso dal livello in vigore restituisce un errore 400 mentre il ragionamento è disattivato. Consulta [Usa l'effort per controllare il ragionamento](https://platform.claude.com/docs/it/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#use-effort-to-control-thinking) e [Usa il ragionamento adattivo con output JSON e i tuoi strumenti](https://platform.claude.com/docs/it/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#json-output-with-your-own-tools). Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5 e Claude Mythos Preview rifiutano `thinking: {type: "disabled"}`. Su questi modelli il ragionamento non può essere disattivato. Per verificare se un modello accetta `"disabled"` prima di inviare una richiesta, leggi il suo valore `capabilities.thinking.types.disabled.supported` dalla Models API. [Utilizzo della Models API](https://platform.claude.com/docs/it/models/overview#using-the-models-api) descrive il campo. Se il tuo modello supporta solo il ragionamento esteso (vedi la [tabella di configurazione per modello](https://platform.claude.com/docs/it/build-with-claude/thinking-troubleshooting#supported-models)), configuralo invece con `type: "enabled"` e un valore `budget_tokens`. La pagina [Ragionamento esteso](https://platform.claude.com/docs/it/build-with-claude/extended-thinking) tratta questa configurazione. E se una qualsiasi configurazione del ragionamento restituisce un errore 400, [Risoluzione dei problemi del ragionamento](https://platform.claude.com/docs/it/build-with-claude/thinking-troubleshooting) associa ogni messaggio di errore alla relativa soluzione. ## Leggere l'output del thinking ### Controllare la visualizzazione del ragionamento Il campo `display` nella configurazione del ragionamento controlla come il contenuto del ragionamento viene restituito nelle risposte dell'API. `display` funziona in entrambe le modalità: impostalo insieme a `type: "adaptive"` o `type: "enabled"`. Accetta questi valori: * `"summarized"`: i blocchi di ragionamento contengono testo di [ragionamento riassunto](https://platform.claude.com/docs/it/build-with-claude/thinking#summarized-thinking), un riepilogo leggibile del ragionamento di Claude. È il valore predefinito su Claude Opus 4.6, Claude Sonnet 4.6 e modelli precedenti. * `"omitted"`: i blocchi di ragionamento vengono restituiti con un campo `thinking` vuoto. Il campo `signature` contiene comunque il ragionamento completo crittografato per la continuità multi-turno (vedi [Crittografia del ragionamento](https://platform.claude.com/docs/it/build-with-claude/thinking#thinking-encryption)). È il valore predefinito su Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7, [Claude Mythos Preview](https://anthropic.com/glasswing) e Claude Haiku 5.5. * `"updates"` (beta): i blocchi di ragionamento vengono restituiti con un campo `thinking` vuoto, come con `"omitted"`, e i brevi [aggiornamenti di avanzamento](https://platform.claude.com/docs/it/build-with-claude/thinking#progress-updates) che alcuni modelli scrivono tra le chiamate agli strumenti vengono restituiti come testo leggibile. Richiede l'header beta `thinking-display-updates-2026-08-18`. Imposta `display: "omitted"` quando la tua applicazione non mostra il contenuto del ragionamento agli utenti. Il vantaggio principale è un tempo più rapido per il primo token di testo durante lo streaming: il server salta completamente lo streaming dei token di ragionamento e consegna solo la firma, quindi lo streaming della risposta testuale finale inizia prima. Con `display: "omitted"`, la risposta contiene blocchi `thinking` con un campo `thinking` vuoto: ```json Output { "content": [ { "type": "thinking", "thinking": "", "signature": "EosnCkYICxIMMb3LzNrMu..." }, { "type": "text", "text": "The answer is 12,231." } ] } ``` Tieni presente quanto segue quando lavori con il ragionamento omesso: * Ti vengono comunque addebitati tutti i token di ragionamento. L'omissione riduce la latenza, non il costo. * Se restituisci i blocchi di ragionamento nelle conversazioni multi-turno, restituiscili invariati. Il server decrittografa la `signature` per ricostruire il ragionamento originale per la costruzione del prompt (vedi [Preservare i blocchi di ragionamento](https://platform.claude.com/docs/it/build-with-claude/thinking#preserving-thinking-blocks)). Qualsiasi testo inserito nel campo `thinking` di un blocco omesso restituito viene ignorato. * `display` non è valido con `thinking.type: "disabled"` (non c'è nulla da visualizzare) e con `thinking.type: "between_tools"` (solo Claude Sonnet 5.5), che non accetta altri campi. Con `between_tools`, gli aggiornamenti di avanzamento vengono comunque restituiti con il testo di riepilogo, come avviene con `display: "updates"` (vedi [Aggiornamenti di avanzamento](https://platform.claude.com/docs/it/build-with-claude/thinking#progress-updates)). * Quando usi `thinking.type: "adaptive"` e il modello salta il ragionamento per una richiesta semplice, non viene prodotto alcun blocco di ragionamento indipendentemente da `display`. * Durante lo streaming con `display: "omitted"`, non viene trasmesso alcun testo di ragionamento. Ogni blocco di ragionamento trasmette un `thinking_delta` con una stringa `thinking` vuota, poi il suo `signature_delta`. Con `display: "updates"`, solo i [blocchi di aggiornamento di avanzamento](https://platform.claude.com/docs/it/build-with-claude/thinking#progress-updates) trasmettono eventi `thinking_delta` che contengono testo. Vedi [Streaming del ragionamento](https://platform.claude.com/docs/it/build-with-claude/thinking#streaming-thinking) per la sequenza degli eventi. Il campo `signature` è identico qualunque sia il valore di `display` impostato. È supportato cambiare il valore di `display` tra un turno e l'altro di una conversazione. ### Ragionamento riassunto Quando `display` è `"summarized"`, il testo di ragionamento che ricevi è un riepilogo dell'intero processo di ragionamento di Claude anziché la catena di pensiero grezza. Il ragionamento riassunto offre tutti i vantaggi in termini di intelligenza del ragionamento, prevenendo al contempo gli abusi. Nessuna impostazione di `display` restituisce la catena di pensiero grezza. Tieni presente quanto segue quando lavori con il ragionamento riassunto: * Ti vengono addebitati tutti i token di ragionamento generati dalla richiesta originale, non i token del riepilogo. Il numero di token di output fatturati non corrisponde al numero di token che vedi nella risposta. * Su Claude Opus 4.6, Claude Sonnet 4.6 e modelli precedenti, le prime righe dell'output di ragionamento sono più dettagliate e forniscono un ragionamento approfondito particolarmente utile ai fini del prompt engineering. [Claude Mythos Preview](https://anthropic.com/glasswing) riepiloga fin dal primo token, quindi i suoi blocchi di ragionamento non mostrano questo preambolo dettagliato. * Il riepilogo preserva le idee chiave del processo di ragionamento di Claude con una latenza aggiuntiva minima, quindi i riepiloghi possono essere trasmessi in streaming man mano che arrivano. * Il riepilogo viene elaborato da un modello diverso da quello a cui indirizzi le tue richieste. Il modello che ragiona non vede l'output riepilogato. * Poiché Anthropic cerca di migliorare la funzionalità di ragionamento, il comportamento del riepilogo è soggetto a modifiche. Nei rari casi in cui hai bisogno di accedere all'output completo del ragionamento, [contatta il team vendite di Anthropic](mailto:sales@anthropic.com). Per vedere il ragionamento del modello, leggi i blocchi `thinking` anziché chiedere tramite prompt il ragionamento nel testo della risposta. Su Claude Fable 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5 e Claude Fable 5, una richiesta che tenta di ottenere il ragionamento interno del modello come parte del testo della risposta può essere rifiutata con `stop_details.category: "reasoning_extraction"`. Vedi [Categorie di rifiuto](https://platform.claude.com/docs/it/build-with-claude/refusals-and-fallback#refusal-response) per il riferimento del campo e [Mantieni il ragionamento nei blocchi di ragionamento](https://platform.claude.com/docs/it/build-with-claude/refusals-and-fallback#keep-reasoning-in-thinking-blocks) per sapere cosa chiedere invece. ### Streaming del ragionamento Il ragionamento funziona con lo [streaming](https://platform.claude.com/docs/it/build-with-claude/streaming). I blocchi di ragionamento vengono trasmessi come eventi `thinking_delta` all'interno di eventi `content_block_delta`, seguiti da un singolo evento `signature_delta` subito prima del `content_block_stop` del blocco. I blocchi di testo vengono poi trasmessi come di consueto. ![Diagramma della sequenza di eventi di streaming con il ragionamento: il blocco di ragionamento si apre, i delta di ragionamento contengono testo solo quando l'impostazione di visualizzazione restituisce testo (summarized, oppure updates per i blocchi di aggiornamento di avanzamento), un singolo delta di firma chiude il blocco, poi vengono trasmessi i delta di testo](https://platform.claude.com/docs/it/images/how-thinking-streams.svg) Gli esempi seguenti trasmettono in streaming una risposta con ragionamento adattivo, stampando i delta di ragionamento e di testo man mano che arrivano: ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 16000, "stream": true, "thinking": { "type": "adaptive", "display": "summarized" }, "messages": [ { "role": "user", "content": "What is the greatest common divisor of 1071 and 462?" } ] }' ``` ```bash CLI ant messages create \ --model claude-opus-5-5 \ --max-tokens 16000 \ --thinking '{type: adaptive, display: summarized}' \ --message '{role: user, content: "What is the greatest common divisor of 1071 and 462?"}' \ --stream \ --format jsonl ``` ```python Python client = anthropic.Anthropic() with client.messages.stream( model="claude-opus-5-5", max_tokens=16000, thinking={"type": "adaptive", "display": "summarized"}, messages=[ { "role": "user", "content": "What is the greatest common divisor of 1071 and 462?", } ], ) as stream: for event in stream: match event.type: case "content_block_start": print(f"\nStarting {event.content_block.type} block...") case "content_block_delta": delta = event.delta match delta.type: case "thinking_delta": print(delta.thinking, end="", flush=True) case "text_delta": print(delta.text, end="", flush=True) ``` ```typescript TypeScript const client = new Anthropic(); const stream = client.messages.stream({ model: "claude-opus-5-5", max_tokens: 16000, thinking: { type: "adaptive", display: "summarized" }, messages: [{ role: "user", content: "What is the greatest common divisor of 1071 and 462?" }] }); for await (const event of stream) { switch (event.type) { case "content_block_start": console.log(`\nStarting ${event.content_block.type} block...`); break; case "content_block_delta": switch (event.delta.type) { case "thinking_delta": process.stdout.write(event.delta.thinking); break; case "text_delta": process.stdout.write(event.delta.text); break; } break; } } ``` ```csharp C# AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus5_5, MaxTokens = 16000, Thinking = new ThinkingConfigAdaptive { Display = Display.Summarized }, Messages = [new() { Role = Role.User, Content = "What is the greatest common divisor of 1071 and 462?" }] }; await foreach (var rawEvent in client.Messages.CreateStreaming(parameters)) { if (rawEvent.TryPickContentBlockStart(out var start)) { Console.WriteLine($"\nStarting {start.ContentBlock.Type} block..."); } else if (rawEvent.TryPickContentBlockDelta(out var delta)) { if (delta.Delta.TryPickThinking(out var thinkingDelta)) { Console.Write(thinkingDelta.Thinking); } else if (delta.Delta.TryPickText(out var textDelta)) { Console.Write(textDelta.Text); } } } ``` ```go Go client := anthropic.NewClient() stream := client.Messages.NewStreaming(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 16000, Thinking: anthropic.ThinkingConfigParamUnion{ OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{ Display: anthropic.ThinkingConfigAdaptiveDisplaySummarized, }, }, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("What is the greatest common divisor of 1071 and 462?")), }, }) for stream.Next() { event := stream.Current() switch eventVariant := event.AsAny().(type) { case anthropic.ContentBlockStartEvent: fmt.Printf("\nStarting %s block...\n", eventVariant.ContentBlock.Type) case anthropic.ContentBlockDeltaEvent: switch deltaVariant := eventVariant.Delta.AsAny().(type) { case anthropic.ThinkingDelta: fmt.Print(deltaVariant.Thinking) case anthropic.TextDelta: fmt.Print(deltaVariant.Text) } } } if err := stream.Err(); err != nil { log.Fatal(err) } ``` ```java Java import com.anthropic.models.messages.ThinkingConfigAdaptive; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(16000L) .thinking(ThinkingConfigAdaptive.builder() .display(ThinkingConfigAdaptive.Display.SUMMARIZED) .build()) .addUserMessage("What is the greatest common divisor of 1071 and 462?") .build(); try (var streamResponse = client.messages().createStreaming(params)) { streamResponse.stream().forEach(event -> { switch (event.type().value()) { case CONTENT_BLOCK_START -> { var startEvent = event.asContentBlockStart(); var block = startEvent.contentBlock(); switch (block.type().value()) { case THINKING -> IO.println("\nStarting thinking block..."); case TEXT -> IO.println("\nStarting text block..."); } } case CONTENT_BLOCK_DELTA -> { var deltaEvent = event.asContentBlockDelta(); deltaEvent.delta().thinking().ifPresent(td -> IO.print(td.thinking()) ); deltaEvent.delta().text().ifPresent(td -> IO.print(td.text()) ); } } }); } } ``` ```php PHP use Anthropic\Messages\RawContentBlockDeltaEvent; use Anthropic\Messages\RawContentBlockStartEvent; use Anthropic\Messages\TextDelta; use Anthropic\Messages\ThinkingDelta; $client = new Client(); $stream = $client->messages->createStream( maxTokens: 16000, messages: [ ['role' => 'user', 'content' => 'What is the greatest common divisor of 1071 and 462?'] ], model: 'claude-opus-5-5', thinking: ['type' => 'adaptive', 'display' => 'summarized'], ); foreach ($stream as $event) { switch (true) { case $event instanceof RawContentBlockStartEvent: echo "\nStarting {$event->contentBlock->type} block...\n"; break; case $event instanceof RawContentBlockDeltaEvent: switch (true) { case $event->delta instanceof ThinkingDelta: echo $event->delta->thinking; break; case $event->delta instanceof TextDelta: echo $event->delta->text; break; } break; } } ``` ```ruby Ruby client = Anthropic::Client.new stream = client.messages.stream( model: "claude-opus-5-5", max_tokens: 16000, # Un hash semplice come questo accetta display:. La classe tipizzata ThinkingConfigAdaptive # lo scrive display_ (con underscore finale) per non oscurare Kernel#display di Ruby. # La richiesta invia comunque display. thinking: { type: "adaptive", display: "summarized" }, messages: [ { role: "user", content: "What is the greatest common divisor of 1071 and 462?" } ] ) stream.each do |event| case event when Anthropic::Streaming::ThinkingEvent print event.thinking when Anthropic::Streaming::TextEvent print event.text end end ``` Per ricomporre i blocchi di ragionamento completi con le relative firme dopo lo streaming, usa l'helper di accumulo dei messaggi del tuo SDK, `stream.get_final_message()` (typescript: `stream.finalMessage()`; ruby: `stream.accumulated_message`; csharp: `.Aggregate()`; go: `message.Accumulate(event)`; java, php: `MessageAccumulator`), invece di concatenare i delta manualmente. ```sse Output event: message_start data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-5-5", "stop_reason": null, "stop_sequence": null}} event: content_block_start data: {"type": "content_block_start", "index": 0, "content_block": {"type": "thinking", "thinking": "", "signature": ""}} event: content_block_delta data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "I need to find the GCD of 1071 and 462 using the Euclidean algorithm.\n\n1071 = 2 × 462 + 147"}} event: content_block_delta data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n462 = 3 × 147 + 21\n147 = 7 × 21 + 0\n\nSo GCD(1071, 462) = 21"}} // Additional thinking deltas... event: content_block_delta data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b..."}} event: content_block_stop data: {"type": "content_block_stop", "index": 0} event: content_block_start data: {"type": "content_block_start", "index": 1, "content_block": {"type": "text", "text": ""}} event: content_block_delta data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "The greatest common divisor of 1071 and 462 is **21**."}} // Additional text deltas... event: content_block_stop data: {"type": "content_block_stop", "index": 1} event: message_delta data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null}} event: message_stop data: {"type": "message_stop"} ``` Quando è impostato `display: "omitted"`, il blocco di ragionamento si apre, arriva un `thinking_delta` con una stringa `thinking` vuota, segue un singolo `signature_delta` e il blocco si chiude. Lo streaming del testo inizia subito dopo: ```sse Output event: content_block_start data: {"type":"content_block_start","index":0,"content_block":{"type":"thinking","thinking":"","signature":""}} event: content_block_delta data: {"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":""}} event: content_block_delta data: {"type":"content_block_delta","index":0,"delta":{"type":"signature_delta","signature":"EosnCkYICxIMMb3LzNrMu..."}} event: content_block_stop data: {"type":"content_block_stop","index":0} event: content_block_start data: {"type":"content_block_start","index":1,"content_block":{"type":"text","text":""}} ``` Con `display: "updates"` (beta), i blocchi di ragionamento vengono trasmessi come con `"omitted"`. Ogni [blocco di aggiornamento di avanzamento](https://platform.claude.com/docs/it/build-with-claude/thinking#progress-updates) trasmette il suo testo come eventi `thinking_delta` prima del blocco `tool_use` che introduce. Una pausa di diversi secondi prima dell'apertura del blocco di aggiornamento di avanzamento è normale: ```sse Output event: content_block_start data: {"type":"content_block_start","index":1,"content_block":{"type":"thinking","thinking":"","signature":""}} event: content_block_delta data: {"type":"content_block_delta","index":1,"delta":{"type":"thinking_delta","thinking":"Confirmed the retry path never refreshes the expired token. Editing auth.py to add the refresh call."}} event: content_block_delta data: {"type":"content_block_delta","index":1,"delta":{"type":"signature_delta","signature":"Es8CCkYICxIM..."}} event: content_block_stop data: {"type":"content_block_stop","index":1} event: content_block_start data: {"type":"content_block_start","index":2,"content_block":{"type":"tool_use","id":"toolu_01D7FLrfh4GYq7yT1ULFeyMV","name":"edit_file","input":{}}} ``` Con `"updates"`, considera un blocco come aggiornamento di avanzamento non appena uno dei suoi eventi `thinking_delta` contiene testo non vuoto. Quando usi lo streaming con il ragionamento attivo, potresti notare che il testo a volte arriva in blocchi più grandi alternati a una consegna più piccola, token per token. Questo è un comportamento previsto, soprattutto per il contenuto del ragionamento. Il sistema di streaming elabora il contenuto in lotti, il che può ritardare e raggruppare gli eventi di streaming in questo schema di consegna "a blocchi". Per i meccanismi generali dello streaming, vedi [Streaming dei messaggi](https://platform.claude.com/docs/it/build-with-claude/streaming). ## Ragionamento ed effort Il parametro `thinking` controlla se Claude riflette in [blocchi di ragionamento](https://platform.claude.com/docs/it/build-with-claude/thinking) prima di rispondere; il parametro `effort` controlla quanto lavoro Claude dedica all'intera risposta, il che in modalità adattiva include quanto spesso e quanto profondamente riflette. Non passare `adaptive` come valore di `effort`: `adaptive` è una modalità di ragionamento, non un livello di effort. Per sapere cosa fa ciascun livello di effort al comportamento del ragionamento, consulta la [tabella del comportamento del ragionamento per livello](https://platform.claude.com/docs/it/build-with-claude/thinking-steering-and-cost#effort-levels) nella pagina [Orientare il ragionamento](https://platform.claude.com/docs/it/build-with-claude/thinking-steering-and-cost). La pagina [Effort](https://platform.claude.com/docs/it/build-with-claude/effort) documenta il parametro stesso, inclusi i livelli supportati da ciascun modello. Su Claude Opus 4.5, l'unico modello con solo ragionamento esteso che supporta l'effort, l'effort si combina con `budget_tokens`. Vedi [Regole del budget e regolazione](https://platform.claude.com/docs/it/build-with-claude/extended-thinking#budget-rules-and-tuning). Con i due controlli separati in questo modo, scegli quello che corrisponde al tuo obiettivo: * **Ridurre costi o latenza su un carico di lavoro con ragionamento attivo:** abbassa prima `effort`. Ridimensiona l'intera risposta, ragionamento incluso. * **Claude ragiona troppo raramente o in modo troppo superficiale:** alza `effort`, oppure vedi [Orientare la frequenza con cui Claude pensa](https://platform.claude.com/docs/it/build-with-claude/thinking-steering-and-cost#tuning-thinking-behavior) nella pagina sulla regolazione. * **Hai bisogno del ragionamento completamente disattivato:** usa `thinking: {type: "disabled"}` sui modelli che lo consentono (vedi la [tabella di configurazione per modello](https://platform.claude.com/docs/it/build-with-claude/thinking-troubleshooting#supported-models)). Claude Sonnet 5.5 rifiuta `"disabled"`. La sua impostazione più bassa è `thinking: {type: "between_tools"}`, che disattiva il ragionamento iniziale. * **Hai bisogno di un tetto rigido alla spesa:** usa `max_tokens`. L'effort è un'indicazione flessibile. `max_tokens` è un limite rigoroso. ## Ragionamento con uso degli strumenti Il ragionamento funziona insieme all'[uso degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/overview), consentendo a Claude di ragionare sulla scelta degli strumenti e di elaborarne i risultati. Si applicano due vincoli: 1. **Limitazione della scelta dello strumento (modalità manuale):** l'uso degli strumenti con ragionamento esteso manuale (`thinking: {type: "enabled"}`) supporta solo `tool_choice: {"type": "auto"}` (il valore predefinito) o `tool_choice: {"type": "none"}`. L'uso di `tool_choice: {"type": "any"}` o `tool_choice: {"type": "tool", "name": "..."}` genera un errore perché queste opzioni forzano l'uso degli strumenti, il che è incompatibile con il ragionamento esteso manuale. Il ragionamento adattivo, anche sui modelli in cui il ragionamento è attivo per impostazione predefinita, supporta l'uso forzato degli strumenti, tranne su Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 e Claude Mythos 5.1 (vedi [Prefill della risposta e uso forzato degli strumenti](https://platform.claude.com/docs/it/build-with-claude/thinking#limits-and-feature-compatibility)). Dove l'uso forzato degli strumenti è accettato, la risposta inizia con la chiamata allo strumento e non contiene alcun blocco `thinking`. 2. **Preservare i blocchi di ragionamento:** quando restituisci i risultati degli strumenti, devi passare all'API i blocchi di ragionamento del messaggio dell'assistente, completi e non modificati. Vedi [Preservare i blocchi di ragionamento](https://platform.claude.com/docs/it/build-with-claude/thinking#preserving-thinking-blocks). **Un ciclo di uso degli strumenti è un unico turno dell'assistente.** Dal punto di vista del modello, un turno dell'assistente non si completa finché Claude non termina la sua risposta completa, che può includere più chiamate agli strumenti e relativi risultati. L'intera sequenza seguente è un unico turno dell'assistente: ```text wrap User: "What's the weather in Paris?" Assistant: [thinking] + [tool_use: get_weather] User: [tool_result: "20°C, sunny"] Assistant: [text: "The weather in Paris is 20°C and sunny"] ``` L'intero turno viene eseguito in un'unica modalità di ragionamento: non puoi attivare o disattivare il ragionamento a metà di un turno, nemmeno durante il ciclo di uso degli strumenti. In modalità estesa (manuale), l'API impone inoltre che il turno finale dell'assistente di una richiesta con ragionamento attivo inizi con un blocco di ragionamento. La modalità adattiva allenta questo vincolo: nessun turno dell'assistente deve iniziare con uno di essi. **I conflitti a metà turno vengono gestiti senza errori.** Se attivi o disattivi il ragionamento a metà turno (ad esempio, tra l'invio di una chiamata a uno strumento e la restituzione del suo risultato), l'API non restituisce un errore. Disattiva invece silenziosamente il ragionamento per quella richiesta. Per preservare la qualità del modello, l'API può rimuovere i blocchi di ragionamento che creerebbero una struttura di turno non valida, oppure disattivare il ragionamento quando la cronologia della conversazione è incompatibile con il ragionamento attivo. Per verificare se il ragionamento era attivo, controlla la presenza di blocchi `thinking` nella risposta. **Cambia impostazione tra i turni, non al loro interno.** Pianifica la tua strategia di ragionamento all'inizio di ogni turno. Completa il turno dell'assistente, poi modifica la configurazione del ragionamento per il turno successivo: ```text wrap User: "What's the weather?" Assistant: [tool_use] (thinking disabled) User: [tool_result] Assistant: [text: "It's sunny"] User: "What about tomorrow?" Assistant: [thinking] + [text: "..."] (thinking enabled - new turn) ``` Cambiare la modalità di ragionamento invalida anche la cache dei prompt. Vedi [Ragionamento e cache dei prompt](https://platform.claude.com/docs/it/build-with-claude/thinking#thinking-and-prompt-caching). ### Preservare i blocchi di ragionamento Quando Claude invoca uno strumento, mette in pausa la costruzione della sua risposta in attesa di informazioni esterne. Quando restituisci il risultato dello strumento, Claude continua a costruire quella stessa risposta, quindi il suo ragionamento precedente deve essere ancora presente. Ripassa all'API ogni blocco `thinking` completo e non modificato, insieme al blocco `tool_use` che accompagnava. Questo è importante per due motivi: 1. **Continuità del ragionamento:** i blocchi thinking catturano il ragionamento passo dopo passo che ha portato alle richieste degli strumenti. Includerli permette a Claude di continuare a ragionare da dove si era fermato. 2. **Mantenimento del contesto:** i risultati degli strumenti appaiono come messaggi utente nella struttura dell'API, ma fanno parte di un unico flusso di ragionamento continuo. Preservare i blocchi thinking mantiene quel flusso attraverso le chiamate API. In breve: * **Obbligatorio:** all'interno di un turno di uso degli strumenti, ripassa i blocchi thinking. * **Consigliato:** tra i turni, ripassa tutto. * **Consentito:** al di fuori dell'uso degli strumenti, ometti il thinking dei turni precedenti. Non devi eliminare tu stesso il vecchio thinking. Ripassa tutti i blocchi thinking nelle conversazioni multi-turno, e l'API li filtra automaticamente, mantiene i blocchi necessari per preservare il ragionamento del modello e fattura i token di input solo per i blocchi effettivamente mostrati a Claude. Quali blocchi dei turni precedenti vengono mantenuti dipende dal modello. Vedi [Preservazione dei blocchi di ragionamento per modello](https://platform.claude.com/docs/it/build-with-claude/thinking#thinking-block-preservation-by-model). Per sovrascrivere il comportamento predefinito, usa la [strategia di modifica del contesto `clear_thinking_20251015`](https://platform.claude.com/docs/it/build-with-claude/context-editing#thinking-block-clearing). All'interno dell'ultimo messaggio dell'assistente, la sequenza di blocchi `thinking` consecutivi deve corrispondere a ciò che il modello ha generato nella richiesta originale: non puoi riordinarli, modificarli o eliminarli parzialmente. Questo include i [blocchi `redacted_thinking`](https://platform.claude.com/docs/it/build-with-claude/thinking#redacted-thinking-blocks). I blocchi thinking modificati vengono rifiutati con un errore 400. Vedi [Un errore 400 indica che i blocchi di ragionamento non possono essere modificati](https://platform.claude.com/docs/it/build-with-claude/thinking-troubleshooting#error-thinking-blocks-modified) per il messaggio esatto, le cause comuni e la soluzione. L'unica eccezione: il testo inserito nel campo `thinking` vuoto di un blocco [omesso](https://platform.claude.com/docs/it/build-with-claude/thinking#controlling-thinking-display) viene ignorato anziché rifiutato. Per una guida completa a due turni con codice in ogni SDK, vedi [Thinking nei flussi di lavoro con strumenti e multi-turno](https://platform.claude.com/docs/it/build-with-claude/thinking-tool-workflows#two-turn-tool-use-round-trip). Definisce uno strumento, riceve una risposta con thinking più uso degli strumenti e rimanda indietro il turno dell'assistente con il risultato dello strumento. ### Ragionamento interlacciato L'"interleaved thinking" (ragionamento interlacciato) consente a Claude di ragionare tra le chiamate agli strumenti, riflettendo su ciascun risultato prima di agire. Con il ragionamento interlacciato, Claude può: * Ragionare sui risultati di una chiamata a uno strumento prima di determinare cosa fare dopo * Concatenare più chiamate agli strumenti con passaggi di ragionamento intermedi * Prendere decisioni più sfumate in base ai risultati intermedi Le chiamate consecutive agli strumenti non richiedono il ragionamento interlacciato. Claude può concatenare chiamate agli strumenti con o senza ragionamento interlacciato. L'interlacciamento cambia il punto in cui compaiono i blocchi di ragionamento tra le chiamate agli strumenti, non la possibilità di concatenare le chiamate. Con il ragionamento adattivo, il ragionamento interlacciato è automatico su ogni modello che supporta il ragionamento adattivo. Non è necessario alcun header beta. Su Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Opus 4.8 e Claude Opus 4.7, il ragionamento tra le chiamate agli strumenti compare sempre nei blocchi di ragionamento. Claude Haiku 4.5 non supporta il ragionamento interlacciato. Sui modelli che usano il ragionamento esteso manuale, l'interlacciamento richiede un header beta e cambia il modo in cui viene conteggiato il budget di ragionamento. [Ragionamento interlacciato in modalità manuale](https://platform.claude.com/docs/it/build-with-claude/extended-thinking#interleaved-thinking) tratta le regole per modello e il comportamento dell'header specifico per piattaforma. Con il ragionamento interlacciato, l'allocazione del ragionamento può estendersi all'intero turno dell'assistente anziché a una singola risposta. Il ragionamento interlacciato è supportato solo per gli [strumenti usati tramite la Messages API](https://platform.claude.com/docs/it/agents-and-tools/tool-use/overview). Per un confronto pratico che mostra cosa cambia il ragionamento interlacciato in un flusso di lavoro con due strumenti, vedi [Come il ragionamento interlacciato modifica il flusso](https://platform.claude.com/docs/it/build-with-claude/thinking-tool-workflows#how-interleaved-thinking-changes-the-flow). ### Aggiornamenti di avanzamento tra le chiamate agli strumenti Su Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5 e Claude Fable 5, il modello può scrivere un aggiornamento di avanzamento tra le chiamate agli strumenti. Un aggiornamento di avanzamento è una nota su ciò che il modello ha appena trovato e su ciò che sta per fare, scritta per la persona che osserva l'agente anziché come ragionamento. Ciascuno viene restituito come un proprio blocco `thinking` con la propria `signature`, separato da qualsiasi blocco di ragionamento nello stesso punto. Si trova immediatamente prima del blocco `tool_use` o `server_tool_use` che introduce. Al massimo un aggiornamento di avanzamento precede ogni chiamata a uno strumento, e il modello può saltarne qualsiasi. Gli aggiornamenti di avanzamento non sono [ragionamento interlacciato](https://platform.claude.com/docs/it/build-with-claude/thinking#interleaved-thinking): compaiono indipendentemente dal fatto che compaiano blocchi di ragionamento tra le chiamate agli strumenti, e una risposta può contenere entrambi. Il contenuto di un blocco di aggiornamento di avanzamento dipende da [`display`](https://platform.claude.com/docs/it/build-with-claude/thinking#controlling-thinking-display): | `display` | Blocchi di ragionamento | Blocchi di aggiornamento di avanzamento | | ----------------------------------------------------- | ----------------------- | ------------------------------------------------------------------ | | `"omitted"` (il valore predefinito su questi modelli) | Campo `thinking` vuoto | Campo `thinking` vuoto | | `"updates"` (beta) | Campo `thinking` vuoto | Testo di riepilogo | | `"summarized"` | Testo di riepilogo | Testo di riepilogo, non distinguibile da un blocco di ragionamento | Su Claude Sonnet 5.5, l'impostazione di ragionamento più bassa è `thinking: {type: "between_tools"}`. Disattiva il ragionamento iniziale, e ogni aggiornamento di avanzamento viene restituito con il suo testo di riepilogo, come avverrebbe con `display: "updates"`. `between_tools` è accettato solo con [effort](https://platform.claude.com/docs/it/build-with-claude/effort) `high` o inferiore. Con `xhigh` o `max`, una richiesta che lo contiene restituisce un errore 400. `between_tools` non accetta altri campi: `display`, `budget_tokens` o `block_binding` inviati insieme a esso restituiscono un errore 400. L'impostazione non richiede alcun header beta e funziona su ogni piattaforma che offre Claude Sonnet 5.5. Restituisci i blocchi invariati: un blocco di aggiornamento di avanzamento che restituisci fornisce al modello la nota completa che ha scritto, non il riepilogo. Usa `display: "updates"` per un'interfaccia di agente che mantiene nascosto il ragionamento e mostra all'utente una riga di stato a ogni passaggio. Con questa impostazione, qualsiasi blocco `thinking` con testo non vuoto è un aggiornamento di avanzamento, quindi visualizza quelli e nient'altro. È in beta e richiede l'header beta `thinking-display-updates-2026-08-18` (per inviarlo su Amazon Bedrock, Google Cloud o Microsoft Foundry, vedi [Funzionalità beta su altre piattaforme](https://platform.claude.com/docs/it/api/beta-headers#beta-features-on-other-platforms)). Senza di esso, il valore viene rifiutato con lo stesso errore 400 `invalid_request_error` di un valore `display` sconosciuto. ```json { "model": "claude-fable-5-1", "max_tokens": 16000, "thinking": { "type": "adaptive", "display": "updates" }, "tools": [ { "name": "edit_file", "description": "Replace the contents of a file in the repository.", "input_schema": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" } }, "required": ["path", "content"] } } ], "messages": [ { "role": "user", "content": "The login test fails after an hour of uptime. Find out why and fix it." } ] } ``` Con `"updates"`, l'inizio della risposta che segue un `tool_result` appare così. Il primo blocco è ragionamento e resta vuoto, come avverrebbe con `"omitted"`. Il secondo contiene testo, quindi è un aggiornamento di avanzamento. Con `"summarized"` entrambi i blocchi contengono testo, e con `"omitted"` entrambi sono vuoti. ```json Output { "content": [ { "type": "thinking", "thinking": "", "signature": "EqMBCkYICxIM..." }, { "type": "thinking", "thinking": "Confirmed the retry path never refreshes the expired token. Editing auth.py to add the refresh call.", "signature": "Es8CCkYICxIM..." }, { "type": "tool_use", "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "name": "edit_file", "input": { "path": "auth.py", "content": "..." } } ] } ``` Tieni presente quanto segue quando lavori con gli aggiornamenti di avanzamento: * Restituisci i blocchi di aggiornamento di avanzamento invariati insieme al resto del turno dell'assistente, come qualsiasi altro blocco `thinking`. * Il testo che ricevi è un riepilogo dell'aggiornamento di avanzamento, normalmente una o due frasi. Non fare affidamento sulla sua lunghezza. L'aggiornamento di avanzamento conta ai fini di `usage.output_tokens` per la sua lunghezza completa, non per quella del riepilogo. * Un blocco di aggiornamento di avanzamento può essere restituito con un campo `thinking` vuoto con qualsiasi valore di `display`. Non visualizzare nulla per un blocco vuoto. Con `"updates"` appare identico a un blocco di ragionamento vuoto e non richiede una gestione separata. * Quando una risposta si interrompe per `max_tokens`, `model_context_window_exceeded` o `stop_sequence` poco dopo una chiamata a uno strumento o un risultato di uno strumento, il suo ultimo blocco può essere un blocco di aggiornamento di avanzamento che sostituisce il lavoro che il modello non aveva terminato. Con `"updates"` e `"summarized"` il suo testo è esattamente `This part of the response was interrupted before it finished.` e puoi mostrarlo come qualsiasi altro aggiornamento. Con `"omitted"` è vuoto. Per continuare, restituisci il turno dell'assistente invariato e aggiungi un nuovo messaggio `user` (con un `tool_result` per ogni blocco `tool_use` in quel turno). * Durante lo [streaming](https://platform.claude.com/docs/it/build-with-claude/thinking#streaming-thinking), aspettati una pausa di diversi secondi prima dell'apertura di un blocco di aggiornamento di avanzamento. Vedi la traccia `"updates"` in [Streaming del ragionamento](https://platform.claude.com/docs/it/build-with-claude/thinking#streaming-thinking). * Questi modelli scrivono meno aggiornamenti di avanzamento con [effort](https://platform.claude.com/docs/it/build-with-claude/effort) più elevato e nelle lunghe catene di strumenti. Se la tua interfaccia dipende da essi, vedi [Chiedi aggiornamenti di avanzamento rivolti all'utente](https://platform.claude.com/docs/it/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#ask-for-user-facing-progress-updates) oppure, per Claude Opus 5.5, [Aggiornamenti sui progressi rivolti all'utente](https://platform.claude.com/docs/it/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#user-facing-progress-updates). Per Claude Sonnet 5.5, vedi [Aggiornamenti sui progressi per l'utente](https://platform.claude.com/docs/it/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#user-facing-progress-updates). ### Preservazione dei blocchi di ragionamento per modello Il fatto che i blocchi di ragionamento dei turni precedenti dell'assistente restino nel contesto per impostazione predefinita dipende dal modello: * **Conservano tutti i turni precedenti:** Claude Opus 4.5 e i modelli Opus successivi, Claude Sonnet 4.6 e i modelli Sonnet successivi, Claude Haiku 5.5, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5 e Claude Mythos Preview. * **Conservano solo l'ultimo turno:** i modelli Opus e Sonnet precedenti e tutti i modelli Haiku fino a Claude Haiku 4.5. Quando restituisci blocchi di ragionamento più vecchi, l'API li rimuove automaticamente. Non è necessario rimuoverli manualmente. La conservazione offre due vantaggi: * **Ottimizzazione della cache:** i blocchi di ragionamento conservati consentono cache hit durante l'uso degli strumenti, poiché vengono restituiti insieme ai risultati degli strumenti e memorizzati nella cache in modo incrementale nel corso del turno dell'assistente, con conseguente risparmio di token nei flussi di lavoro in più passaggi. * **Nessun impatto sull'intelligenza:** conservare i blocchi di ragionamento non ha alcun effetto negativo sulle prestazioni del modello. Il compromesso riguarda l'uso del contesto: le conversazioni lunghe consumano più spazio di contesto sui modelli che conservano tutto, perché i blocchi di ragionamento mantenuti contano come input come qualsiasi altra parte della cronologia della conversazione (vedi [Ragionamento e finestra di contesto](https://platform.claude.com/docs/it/build-with-claude/thinking#thinking-and-the-context-window)). Il comportamento è automatico in entrambi i regimi. Non sono necessarie modifiche al codice né header beta, e dovresti continuare a restituire blocchi di ragionamento completi e non modificati come descritto in [Preservare i blocchi di ragionamento](https://platform.claude.com/docs/it/build-with-claude/thinking#preserving-thinking-blocks). Per sovrascrivere l'impostazione predefinita in una delle due direzioni, usa la [rimozione dei blocchi di ragionamento](https://platform.claude.com/docs/it/build-with-claude/context-editing#thinking-block-clearing). **Cambiare modello a metà conversazione.** Continua a restituire i blocchi di ragionamento invariati quando cambi modello, ad esempio dopo un [fallback per rifiuto del classificatore](https://platform.claude.com/docs/it/build-with-claude/refusals-and-fallback). Un blocco di ragionamento è leggibile solo dal modello che lo ha prodotto e da alcuni altri modelli, e l'API ignora o scarta i blocchi che il modello di destinazione non può leggere. Su Claude Fable 5.1 e Claude Mythos 5.1 la direzione conta: leggono i blocchi di ragionamento dei modelli precedenti, e solo loro due leggono i blocchi l'uno dell'altro, quindi passare a questi modelli mantiene il ragionamento della conversazione, mentre passare da essi a qualsiasi altro modello lo scarta (vedi [come vengono fatturati e segnalati i blocchi scartati](https://platform.claude.com/docs/it/build-with-claude/preserved-thinking#switching-models)). Claude Opus 5.5 legge i blocchi di ragionamento di Claude Opus 5 e quelli dei modelli Opus, Sonnet e Haiku precedenti e, sulla Claude API e su Google Cloud, di Claude Haiku 5.5, ma non quelli dei modelli Claude Fable e Claude Mythos; sulla Claude API, Claude Fable 5.1 e Claude Mythos 5.1 leggono i blocchi di Claude Opus 5.5. Un passaggio da Claude Opus 5.5 a Claude Fable 5.1 sulla Claude API mantiene il ragionamento dei turni precedenti; un passaggio da Claude Fable 5.1 a Claude Opus 5.5 lo scarta. Claude Sonnet 5.5 legge i blocchi di ragionamento di Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5 e dei modelli precedenti e, sulla Claude API e su Google Cloud, di Claude Haiku 5.5, ma non quelli di Claude Opus 5, Claude Opus 5.5 o di qualsiasi modello Claude Fable o Claude Mythos. Sulla Claude API e su Google Cloud, Claude Opus 5.5 legge i blocchi di Claude Sonnet 5.5 e nessun altro modello lo fa: un passaggio da Claude Sonnet 5.5 a Claude Opus 5.5 sulla Claude API e su Google Cloud mantiene il ragionamento dei turni precedenti, e qualsiasi altro passaggio da Claude Sonnet 5.5 lo scarta. Claude Haiku 5.5 legge i blocchi di ragionamento di Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5 e dei modelli precedenti, ma non quelli di Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5 o di qualsiasi modello Claude Fable o Claude Mythos. Sulla Claude API e su Google Cloud, Claude Opus 5.5 e Claude Sonnet 5.5 leggono i blocchi di Claude Haiku 5.5 e nessun altro modello lo fa. Rimuovi manualmente i blocchi `thinking` e `redacted_thinking` precedenti solo per risparmiare token di input sui modelli che li ignorano anziché scartarli, e mai quando riscatti un [credito di fallback](https://platform.claude.com/docs/it/build-with-claude/fallback-credit), che richiede il corpo invariato. ## Ragionamento preservato Il [ragionamento preservato](https://platform.claude.com/docs/it/build-with-claude/preserved-thinking) determina se il modello può usare un blocco di ragionamento che restituisci da un turno precedente. A partire da Claude Fable 5.1, l'API verifica la `signature` di ogni blocco `thinking` o `redacted_thinking` in una richiesta per due aspetti: * **Il modello che lo ha prodotto.** Ogni modello legge i propri blocchi di ragionamento e quelli di un insieme fisso di altri modelli. Claude Fable 5.1 legge i blocchi di Claude Opus 5 e, sulla Claude API, di Claude Opus 5.5; né Claude Opus 5 né Claude Opus 5.5 leggono i blocchi di Claude Fable 5.1. L'API scarta un blocco che il modello corrente non può leggere, senza errori e senza fatturarlo. Vedi [Cambiare modello a metà conversazione](https://platform.claude.com/docs/it/build-with-claude/preserved-thinking#switching-models). * **Tutto ciò che è stato inviato prima.** Un blocco resta valido solo finché il prompt `system` di primo livello, i `tools` e i messaggi che lo precedono restano invariati. Se uno qualsiasi di questi cambia, quel blocco e tutti i blocchi di ragionamento successivi diventano non validi, e l'API rifiuta la richiesta con un errore 400 oppure scarta i blocchi non validi, a tua scelta. Vedi [Mantenere invariato il prefisso](https://platform.claude.com/docs/it/build-with-claude/preserved-thinking#prefix-check). I blocchi di ragionamento di Claude Sonnet 5.5 e Claude Haiku 5.5 sono inoltre legati all'account che li ha prodotti. Vedi [I blocchi di ragionamento restano con l'account che li ha prodotti](https://platform.claude.com/docs/it/build-with-claude/preserved-thinking#account-bound-thinking) per sapere dove l'API applica questa regola. Il controllo del modello si applica a ogni account. L'API applica il controllo del prefisso per impostazione predefinita agli account creati a partire dal 31 agosto 2026, 00:00 UTC. Sugli account più vecchi applica il controllo solo alle richieste che impostano `thinking.block_binding.prefix_mismatch_behavior`. Rendi la tua integrazione "append-only" (in sola aggiunta) indipendentemente dall'età del tuo account, in modo che lo stesso codice funzioni su ogni account, inclusi gli account più recenti in cui il controllo è applicato per impostazione predefinita. Per mantenere valido il ragionamento, restituisci ogni turno dell'assistente esattamente come lo hai ricevuto e aggiungi nuovi messaggi solo alla fine di `messages`. Se il tuo codice costruisce autonomamente l'array `messages`, la pagina Ragionamento preservato tratta: * [Cosa conta come modifica](https://platform.claude.com/docs/it/build-with-claude/preserved-thinking#what-counts-as-an-edit) e [come verificare se il tuo codice ne effettua una](https://platform.claude.com/docs/it/build-with-claude/preserved-thinking#how-to-tell-whether-your-integration-is-impacted). * [La funzionalità dell'API che sostituisce ciascuna modifica comune](https://platform.claude.com/docs/it/build-with-claude/preserved-thinking#replace-prefix-edits): messaggi di sistema a metà conversazione per nuove istruzioni e promemoria per turno, blocchi `tool_addition` e `tool_removal` per le modifiche agli strumenti, `output_config` per messaggio per le modifiche dell'effort, e compattazione lato server e modifica del contesto per ridurre la cronologia. * [Compattazione lato client](https://platform.claude.com/docs/it/build-with-claude/preserved-thinking#custom-compaction-on-the-client): quali pattern mantengono valido il ragionamento e quali no. * [L'header beta `thinking-binding-controls-2026-08-01`](https://platform.claude.com/docs/it/build-with-claude/preserved-thinking#preserved-thinking-controls). Aggiunge un campo `block_binding.prefix_mismatch_behavior` (`"error"` o `"drop_block"`) alla configurazione del ragionamento e un array `input_transformations` a ogni risposta. L'array elenca ogni blocco di ragionamento che l'API ha scartato, o che non ha superato il controllo del prefisso ed è stato lasciato passare. ## Ragionamento e cache dei prompt La ["prompt caching" (cache dei prompt)](https://platform.claude.com/docs/it/build-with-claude/prompt-caching) interagisce con il ragionamento in alcuni modi specifici. Le seguenti regole si applicano in entrambe le modalità di ragionamento. **Le modifiche alla configurazione invalidano la cache.** La configurazione del ragionamento e il livello di [`effort`](https://platform.claude.com/docs/it/build-with-claude/effort) risolto vengono inseriti nel prompt stesso, quindi modificarne uno qualsiasi avvia un nuovo prefisso di cache. Passare tra `adaptive`, `enabled` e `disabled`, modificare `budget_tokens` e modificare il valore di effort invalidano tutti i breakpoint della cache: i breakpoint a livello di messaggio falliscono sempre, e anche i breakpoint degli strumenti e del prompt di sistema possono fallire, a seconda di dove il modello inserisce la configurazione. Considera qualsiasi modifica del ragionamento o dell'effort di primo livello come un nuovo inizio della cache. Sui modelli che supportano l'[effort per messaggio](https://platform.claude.com/docs/it/build-with-claude/effort#change-effort-mid-conversation-beta), una modifica dell'effort trasmessa in un messaggio `role: "system"` all'interno di `messages` lascia intatto il prefisso in cache. Le richieste consecutive che mantengono la stessa configurazione preservano la cache, e impostare esplicitamente un parametro al suo valore predefinito equivale a ometterlo. Un blocco di ragionamento che l'API scarta in base a una qualsiasi [condizione del ragionamento preservato](https://platform.claude.com/docs/it/build-with-claude/thinking#preserved-thinking) modifica il prefisso in cache dalla posizione di quel blocco in poi. I blocchi restituiti invariati mantengono intatta la cache. Una dimostrazione pratica con l'output di utilizzo si trova nella pagina [Orientare il ragionamento](https://platform.claude.com/docs/it/build-with-claude/thinking-steering-and-cost#prompt-caching). **I blocchi di ragionamento vengono memorizzati nella cache insieme ai risultati degli strumenti.** Durante un ciclo di uso degli strumenti, la memorizzazione nella cache avviene quando effettui una richiesta successiva che include i risultati degli strumenti. A quel punto la cronologia precedente della conversazione, inclusi i suoi blocchi di ragionamento, può essere memorizzata nella cache, e quei blocchi di ragionamento in cache contano come token di input nelle tue metriche di utilizzo quando vengono letti dalla cache. Ciò avviene automaticamente, anche senza marcatori `cache_control` espliciti, e si comporta allo stesso modo per il ragionamento normale e per quello interlacciato. Il compromesso: i blocchi di ragionamento che non vedi più nelle risposte contribuiscono comunque all'utilizzo dei token di input quando vengono letti dalla cache. **Il fatto che i blocchi precedenti siano o meno nel contesto dipende dal modello.** Questo è regolato dall'[impostazione predefinita di conservazione](https://platform.claude.com/docs/it/build-with-claude/thinking#thinking-block-preservation-by-model). Sui modelli che conservano tutto, i blocchi di ragionamento dei turni precedenti restano in cache e nel contesto. Sui modelli che conservano solo l'ultimo turno, una volta inviato un messaggio utente che non è un risultato di uno strumento, tutti i blocchi di ragionamento precedenti vengono rimossi dal contesto. Su questi modelli, una conversazione come questa: ```text wrap User: ["What's the weather in Paris?"], Assistant: [thinking_block_1] + [tool_use block 1], User: [tool_result_1, cache=True], Assistant: [thinking_block_2] + [text block 2], User: [Text response, cache=True] ``` viene elaborata come se i blocchi di ragionamento non ci fossero mai stati: ```text wrap User: ["What's the weather in Paris?"], Assistant: [tool_use block 1], User: [tool_result_1, cache=True], Assistant: [text block 2], User: [Text response, cache=True] ``` Sui modelli che conservano tutto, la stessa richiesta mantiene `thinking_block_1` e `thinking_block_2` nel contesto e nella cache. **Il degrado rimuove il ragionamento dalla cronologia memorizzabile nella cache.** Se il ragionamento viene disabilitato a metà turno e passi contenuto di ragionamento nel turno corrente di uso degli strumenti, il contenuto di ragionamento viene rimosso e il ragionamento resta disabilitato per quella richiesta (vedi [degrado controllato](https://platform.claude.com/docs/it/build-with-claude/thinking#thinking-with-tool-use)). Il [ragionamento interlacciato](https://platform.claude.com/docs/it/build-with-claude/thinking#interleaved-thinking) amplifica gli effetti di invalidazione della cache, perché i blocchi di ragionamento possono comparire tra più chiamate agli strumenti. Le attività con molto ragionamento richiedono spesso più tempo per essere completate rispetto alla durata predefinita della cache di 5 minuti. Valuta la [durata della cache di 1 ora](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#1-hour-cache-duration) per mantenere i cache hit in sessioni di ragionamento più lunghe e in flussi di lavoro in più passaggi. ## Ragionamento e finestra di contesto `max_tokens`, che include tutto il ragionamento generato da Claude nel turno corrente, viene applicato come limite rigoroso. Sui modelli Claude 4.5 e più recenti, se i token di input più `max_tokens` superano la dimensione della "context window" (finestra di contesto), l'API accetta la richiesta. Se poi la generazione raggiunge il limite della finestra di contesto, si interrompe con `stop_reason: "model_context_window_exceeded"` invece di restituire un errore. Sui modelli precedenti, l'API restituisce invece un errore di validazione. Vedi [Gestione dei motivi di arresto](https://platform.claude.com/docs/it/build-with-claude/handling-stop-reasons). Il modo in cui il ragionamento viene conteggiato nella finestra dipende da quando è stato generato: * **Il ragionamento del turno corrente** conta sempre ai fini di `max_tokens`, viene fatturato come token di output e occupa spazio nella finestra di contesto per il turno che lo ha generato. * **Il ragionamento dei turni precedenti** dipende dall'[impostazione predefinita di conservazione](https://platform.claude.com/docs/it/build-with-claude/thinking#thinking-block-preservation-by-model). Sui [modelli che conservano tutti i turni precedenti](https://platform.claude.com/docs/it/build-with-claude/thinking#thinking-block-preservation-by-model), i blocchi di ragionamento precedenti restano nel contesto, contano ai fini della finestra e vengono fatturati come token di input come il resto della cronologia della conversazione. Sui modelli che conservano solo l'ultimo turno, l'API rimuove automaticamente i blocchi di ragionamento più vecchi quando li restituisci, quindi non consumano spazio nella finestra né token di input. In pratica: * Sui modelli che conservano tutto, pianifica la tua finestra di contesto come se il ragionamento fosse normale cronologia della conversazione, perché lo è. Le sessioni agentiche lunghe accumulano ragionamento nel contesto. Usa la [rimozione dei blocchi di ragionamento](https://platform.claude.com/docs/it/build-with-claude/context-editing#thinking-block-clearing) se hai bisogno di recuperare spazio. * Sui modelli che conservano solo l'ultimo turno, il ragionamento è solo un costo per turno: il ragionamento di ogni turno conta ai fini del `max_tokens` di quel turno e poi esce dalla finestra. I seguenti diagrammi illustrano il regime che conserva solo l'ultimo turno (con rimozione). Il primo mostra una conversazione a più turni: il "thinking block" (blocco di ragionamento) di ogni turno viene generato nell'output ma non viene riportato nell'input dei turni successivi. ![Diagramma del ragionamento su un modello che rimuove i blocchi di ragionamento precedenti: il blocco di ragionamento di ogni turno viene generato nell'output e non viene riportato nell'input dei turni successivi](https://platform.claude.com/docs/it/images/context-window-thinking.svg) Il secondo mostra lo stesso regime con l'uso degli strumenti: il "thinking" (ragionamento) resta nel contesto insieme al relativo risultato dello strumento per tutta la durata del turno dell'assistente, poi esce al turno utente successivo. ![Diagramma del ragionamento con uso degli strumenti su un modello che rimuove i blocchi di ragionamento precedenti: il ragionamento viene mantenuto con il relativo risultato dello strumento, poi scartato al turno utente successivo](https://platform.claude.com/docs/it/images/context-window-thinking-tools.svg) Usa l'[API di conteggio dei token](https://platform.claude.com/docs/it/build-with-claude/token-counting) per ottenere conteggi accurati per il tuo caso d'uso specifico, in particolare per le conversazioni a più turni che includono ragionamento. ## Crittografia del ragionamento Il contenuto completo del ragionamento viene crittografato e restituito nel campo `signature` di ogni blocco di ragionamento. L'API usa la signature per verificare che i blocchi di ragionamento siano stati generati da Claude quando li ripassi. Tieni presente quanto segue quando lavori con le signature: * È strettamente necessario rimandare i blocchi di ragionamento solo quando [usi gli strumenti con il ragionamento](https://platform.claude.com/docs/it/build-with-claude/thinking#thinking-with-tool-use). Altrimenti puoi omettere i blocchi di ragionamento dei turni precedenti. Se li ripassi, il fatto che l'API li mantenga o li rimuova dipende dal modello (vedi [Preservazione dei blocchi di ragionamento per modello](https://platform.claude.com/docs/it/build-with-claude/thinking#thinking-block-preservation-by-model)). Usa la [modifica del contesto](https://platform.claude.com/docs/it/build-with-claude/context-editing) per configurare questo comportamento. * Quando rimandi i blocchi di ragionamento, ripassa tutto esattamente come l'hai ricevuto, per coerenza e per evitare potenziali problemi. * Durante lo [streaming delle risposte](https://platform.claude.com/docs/it/build-with-claude/thinking#streaming-thinking), la signature arriva come `signature_delta` all'interno di un evento `content_block_delta` subito prima dell'evento `content_block_stop`. * I valori di `signature` sono significativamente più lunghi nei modelli Claude 4 e successivi rispetto ai modelli precedenti. * Il campo `signature` è opaco: non interpretarlo né analizzarlo. * I valori di `signature` sono compatibili tra le piattaforme (la Claude API, [Amazon Bedrock](https://platform.claude.com/docs/it/build-with-claude/claude-in-amazon-bedrock) e [Google Cloud](https://platform.claude.com/docs/it/build-with-claude/claude-on-vertex-ai)). I valori generati su una piattaforma funzionano su un'altra, tranne per il fatto che i blocchi di ragionamento di Claude Sonnet 5.5 e Claude Haiku 5.5 funzionano solo nell'account che li ha prodotti o in un account collegato a esso. Vedi [I blocchi di ragionamento restano con l'account che li ha prodotti](https://platform.claude.com/docs/it/build-with-claude/preserved-thinking#account-bound-thinking). ## Blocchi di ragionamento redatti Oltre ai normali blocchi `thinking`, l'API può restituire blocchi `redacted_thinking` quando porzioni del ragionamento di Claude vengono redatte per motivi di sicurezza. Un blocco `redacted_thinking` contiene contenuto di ragionamento crittografato in un campo `data`, senza testo leggibile: ```json { "type": "redacted_thinking", "data": "..." } ``` Il campo `data` è opaco e crittografato. Come il campo `signature` sui normali blocchi di ragionamento, ripassa i blocchi `redacted_thinking` all'API invariati quando continui una conversazione multi-turno con [strumenti](https://platform.claude.com/docs/it/build-with-claude/thinking#thinking-with-tool-use). Se il tuo codice filtra i blocchi di contenuto per tipo (ad esempio, `block.type == "thinking"`) quando fa il round-trip delle risposte con l'uso degli strumenti, includi anche i blocchi `redacted_thinking`. Filtrare solo su `block.type == "thinking"` scarta silenziosamente i blocchi `redacted_thinking` e rompe il protocollo multi-turno descritto in [Preservare i blocchi di ragionamento](https://platform.claude.com/docs/it/build-with-claude/thinking#preserving-thinking-blocks). I blocchi `redacted_thinking` sono un tipo di blocco di contenuto distinto restituito quando il ragionamento viene redatto per motivi di sicurezza. Questo è separato dall'opzione [`display: "omitted"`](https://platform.claude.com/docs/it/build-with-claude/thinking#controlling-thinking-display), che restituisce normali blocchi `thinking` con un campo `thinking` vuoto. ## Limiti e compatibilità delle funzionalità ### Parametri di campionamento Su Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5.5, Claude Sonnet 5 e Claude Haiku 5.5, valori non predefiniti di `temperature`, `top_p` o `top_k` restituiscono un errore 400 su ogni richiesta, indipendentemente dall'uso del ragionamento. Su questi modelli, il valore predefinito di `top_p` è `0.99`, quindi un `top_p` pari a `1` restituisce un errore 400, così come una richiesta che include sia `temperature` sia `top_p`, anche ai loro valori predefiniti. Vedi [Rimuovi i parametri di campionamento](https://platform.claude.com/docs/it/models/haiku-5-5/migration-guide#remove-sampling-parameters). Sui modelli più vecchi, la restrizione si applica solo quando il ragionamento è attivo: `temperature` e `top_k` sono incompatibili con il ragionamento, e `top_p` è consentito con valori compresi tra 0,95 e 1. ### Precompilazione della risposta e uso forzato degli strumenti I modelli Claude 4.6 e successivi e Claude Mythos Preview rifiutano un turno finale dell'assistente precompilato con un errore 400, indipendentemente dal fatto che il ragionamento sia attivo (vedi [Prefill non supportato](https://platform.claude.com/docs/it/api/errors#prefill-not-supported)). Sui modelli precedenti, non puoi precompilare la risposta dell'assistente mentre il ragionamento è attivo. L'uso forzato degli strumenti (`tool_choice: {"type": "any"}` o `{"type": "tool", ...}`) è incompatibile con il ragionamento esteso manuale ma funziona con il ragionamento adattivo. Le eccezioni sono Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 e Claude Mythos 5.1, che rifiutano l'uso forzato degli strumenti su ogni richiesta con un errore 400. Su questi modelli, usa invece `tool_choice: {"type": "auto"}` con l'[uso rigoroso degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/strict-tool-use) o gli [output strutturati](https://platform.claude.com/docs/it/build-with-claude/structured-outputs). Dove l'uso forzato degli strumenti è accettato, la risposta inizia con la chiamata allo strumento e non contiene alcun blocco `thinking`. Per consentire al modello di ragionare prima di chiamare uno strumento, usa `tool_choice: {"type": "auto"}` e indica nel prompt quando usare lo strumento. Vedi [Ragionamento con uso degli strumenti](https://platform.claude.com/docs/it/build-with-claude/thinking#thinking-with-tool-use). ### Limiti di output Ogni modello accetta `max_tokens` fino al tetto elencato qui. Sulla [Message Batches API](https://platform.claude.com/docs/it/build-with-claude/batch-processing#extended-output-beta), l'[header beta](https://platform.claude.com/docs/it/api/beta-headers) `output-300k-2026-03-24` alza quel tetto per i modelli con un tetto batch elencato. | Model | Max output tokens | Batches beta ceiling | | :-------------------- | :---------------- | :------------------- | | Claude Fable 5.1 | 128K | — | | Claude Mythos 5.1 | 128K | — | | Claude Fable 5 | 128K | — | | Claude Mythos 5 | 128K | — | | Claude Mythos Preview | 128K | Not available | | Claude Opus 5.5 | 128K | 300K | | Claude Opus 5 | 128K | 300K | | Claude Opus 4.8 | 128K | 300K | | Claude Opus 4.7 | 128K | 300K | | Claude Opus 4.6 | 128K | 300K | | Claude Opus 4.5 | 64K | Not available | | Claude Sonnet 5.5 | 128K | 300K | | Claude Sonnet 5 | 128K | 300K | | Claude Sonnet 4.6 | 128K | 300K | | Claude Sonnet 4.5 | 64K | Not available | | Claude Haiku 5.5 | 128K | 300K | | Claude Haiku 4.5 | 64K | Not available | Vedi la [panoramica dei modelli](https://platform.claude.com/docs/it/models/overview) per i limiti sui modelli legacy. ### Richieste lunghe L'SDK richiede lo streaming quando `max_tokens` è maggiore di 21.333, per evitare timeout HTTP nelle richieste di lunga durata. Si tratta di una validazione lato client, non di una restrizione dell'API. Se non hai bisogno di elaborare gli eventi in modo incrementale, usa `.stream()` (java: `.createStreaming()`; csharp: `.CreateStreaming()`; go: `.NewStreaming()`; php: `->createStream()`) con `.get_final_message()` (typescript: `.finalMessage()`; ruby: `.accumulated_message`; csharp: `.Aggregate()`; go: `message.Accumulate(event)`; java, php: `MessageAccumulator`) per ottenere l'oggetto `Message` completo senza doverlo assemblare manualmente dai singoli eventi. Vedi [Streaming dei messaggi](https://platform.claude.com/docs/it/build-with-claude/streaming#get-the-final-message-without-handling-events). Aspettati tempi di risposta più lunghi quando il ragionamento è attivo, perché la generazione dei blocchi di ragionamento aggiunge tempo di elaborazione. Per i carichi di lavoro che spingono il ragionamento oltre circa 32k token per richiesta, usa l'[elaborazione in batch](https://platform.claude.com/docs/it/build-with-claude/batch-processing) per evitare problemi di rete: tali richieste possono durare abbastanza a lungo da raggiungere i timeout di sistema e i limiti di connessioni aperte. ## Prossimi passi Guida quanto spesso e quanto a fondo Claude pensa con i livelli di effort, le indicazioni nel prompt di sistema e la guida per messaggio, e comprendi il costo e i prezzi del ragionamento. Segui un round-trip completo di uso degli strumenti in due turni che preserva correttamente i blocchi di ragionamento, e scopri come il ragionamento interlacciato cambia il flusso. Scopri se la tua integrazione con la Messages API modifica la cronologia della conversazione, e sostituisci ogni modifica con la funzionalità API che mantiene validi i blocchi di ragionamento precedenti. Diagnostica e risolvi i problemi più comuni del ragionamento: errori 400 di configurazione, blocchi di ragionamento vuoti o mancanti, arresti per max\_tokens e cache miss. Controlla quanti token Claude usa quando risponde con il parametro effort, bilanciando tra completezza della risposta ed efficienza dei token.