Ragionamento

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

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

{
  "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. 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 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. Per il formato completo della risposta, consulta il riferimento della Messages API.

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 riporta ogni errore e la relativa soluzione.

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

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}")

L'esecuzione dell'esempio stampa il ragionamento riassunto, poi la risposta:

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 nella pagina sulla regolazione e Ragionamento e finestra di contesto.

Disattivare il ragionamento

Su Claude Sonnet 5, dove il ragionamento è attivo per impostazione predefinita, puoi disattivarlo:

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

Anche Claude Opus 5 ha il ragionamento attivo per impostazione predefinita e accetta thinking: {type: "disabled"} con "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 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 high o inferiore. Il modello restituisce comunque i suoi aggiornamenti di avanzamento tra le chiamate agli strumenti. Senza strumenti, la risposta contiene solo testo, come con disabled su Claude Sonnet 5. Vedi Esecuzione senza ragionamento iniziale per indicazioni sui prompt.

Anche Claude Haiku 5.5 ha il ragionamento attivo per impostazione predefinita e accetta thinking: {type: "disabled"} con 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 diverso dal livello in vigore restituisce un errore 400 mentre il ragionamento è disattivato. Consulta Usa l'effort per controllare il ragionamento e Usa il ragionamento adattivo con output JSON e i tuoi strumenti.

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 descrive il campo.

Se il tuo modello supporta solo il ragionamento esteso (vedi la tabella di configurazione per modello), configuralo invece con type: "enabled" e un valore budget_tokens. La pagina Ragionamento esteso tratta questa configurazione. E se una qualsiasi configurazione del ragionamento restituisce un errore 400, Risoluzione dei problemi del ragionamento 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, 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). È 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 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 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:

{
  "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). 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).
• 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 trasmettono eventi thinking_delta che contengono testo. Vedi Streaming del ragionamento per la sequenza degli eventi.

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 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.

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 per il riferimento del campo e Mantieni il ragionamento nei blocchi di ragionamento per sapere cosa chiedere invece.

Streaming del ragionamento

Il ragionamento funziona con lo 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.

Gli esempi seguenti trasmettono in streaming una risposta con ragionamento adattivo, stampando i delta di ragionamento e di testo man mano che arrivano:

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)

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(), invece di concatenare i delta manualmente.

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:

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

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.

Per i meccanismi generali dello streaming, vedi Streaming dei messaggi.

Ragionamento ed effort

Il parametro thinking controlla se Claude riflette in blocchi di ragionamento 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 nella pagina Orientare il ragionamento. La pagina 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.

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 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). 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, 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). 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.

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:

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:

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.

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. Per sovrascrivere il comportamento predefinito, usa la strategia di modifica del contesto clear_thinking_20251015.

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.

Per una guida completa a due turni con codice in ogni SDK, vedi Thinking nei flussi di lavoro con strumenti e multi-turno. 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

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 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.

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.

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

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 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). Senza di esso, il valore viene rifiutato con lo stesso errore 400 invalid_request_error di un valore display sconosciuto.

{
  "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.

{
  "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, aspettati una pausa di diversi secondi prima dell'apertura di un blocco di aggiornamento di avanzamento. Vedi la traccia "updates" in Streaming del ragionamento.
• Questi modelli scrivono meno aggiornamenti di avanzamento con effort più elevato e nelle lunghe catene di strumenti. Se la tua interfaccia dipende da essi, vedi Chiedi aggiornamenti di avanzamento rivolti all'utente oppure, per Claude Opus 5.5, Aggiornamenti sui progressi rivolti all'utente. Per Claude Sonnet 5.5, vedi Aggiornamenti sui progressi per l'utente.

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). 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. Per sovrascrivere l'impostazione predefinita in una delle due direzioni, usa la rimozione dei blocchi di ragionamento.

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. 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). 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, che richiede il corpo invariato.

Ragionamento preservato

Il ragionamento preservato 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.
• 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.

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 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 e come verificare se il tuo codice ne effettua una.
• La funzionalità dell'API che sostituisce ciascuna modifica comune: 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: quali pattern mantengono valido il ragionamento e quali no.
• L'header beta thinking-binding-controls-2026-08-01. 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) 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 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, 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 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.

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

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:

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). Il ragionamento interlacciato amplifica gli effetti di invalidazione della cache, perché i blocchi di ragionamento possono comparire tra più chiamate agli strumenti.

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.

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. Sui modelli che conservano tutti i turni precedenti, 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 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.

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.

Usa l'API di conteggio dei token 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. 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). Usa la modifica del contesto 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, 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 e Google Cloud). 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.

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:

{
  "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.

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. 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). 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 o gli output strutturati. 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.

Limiti di output

Ogni modello accetta max_tokens fino al tetto elencato qui. Sulla Message Batches API, l'header beta output-300k-2026-03-24 alza quel tetto per i modelli con un tetto batch elencato.

Vedi la panoramica dei modelli 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() con .get_final_message() per ottenere l'oggetto Message completo senza doverlo assemblare manualmente dai singoli eventi. Vedi Streaming dei messaggi. 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 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