Thinking

Un modello che risponde in un unico passaggio deve fare tutto correttamente al primo tentativo: nessun lavoro preparatorio, nessuna verifica, nessun cambio di rotta a metà strada. Per una dimostrazione matematica, un bug complicato o un lungo compito agentico, il primo approccio spesso non è il migliore.

Il "thinking" (ragionamento) rimuove questo vincolo. Quando il thinking è 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. Quel ragionamento arriva in blocchi di contenuto thinking prima della risposta, e Claude vi attinge per produrre la risposta finale. Ecco perché il thinking 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 illustra come il thinking si comporta attraverso la superficie dell'API: come attivarlo, leggerne l'output e gestirne le interazioni con strumenti, streaming, caching e la finestra di contesto.



Come funziona il thinking

Se Claude ragiona su una determinata richiesta, e con quale profondità, dipende dalla tua configurazione del thinking e dalla complessità della richiesta.

Ecco come appare il thinking in una risposta: uno o più blocchi di contenuto thinking arrivano prima dei blocchi text. Il blocco thinking è comunque contenuto generato, come il blocco text che lo segue, ma è separato dalla risposta canonica. Ogni blocco thinking contiene anche un campo signature, una copia crittografata del ragionamento completo che devi ripassare invariata nelle conversazioni multi-turno e con uso degli strumenti (vedi Crittografia del thinking):

{
  "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 vedi sempre questo testo, e ciò che vedi non è mai la catena di pensiero grezza: il testo in un blocco thinking è un riepilogo del ragionamento di Claude. Il campo display nella configurazione del thinking controlla se quel riepilogo viene restituito: "summarized" lo restituisce, mentre "omitted", il valore predefinito sui modelli più recenti, restituisce blocchi thinking con un campo thinking vuoto. In entrambi i casi il blocco viene fatturato allo stesso modo e ripassato allo stesso modo nelle conversazioni multi-turno. Vedi Controllare la visualizzazione del thinking per i valori predefiniti e i dettagli per modello.

Se Claude usa strumenti, il thinking può apparire anche tra le chiamate agli strumenti. Vedi Thinking con l'uso degli strumenti. Per il formato completo della risposta, vedi il riferimento dell'API Messages.



Configurare il thinking

Sui modelli attuali, il thinking è attivo per impostazione predefinita o a un solo parametro di distanza. Quale configurazione accetta ciascun modello, e qual è il suo valore predefinito, è elencato nella tabella di configurazione per modello nella pagina Risoluzione dei problemi.

Su Claude Opus 5, Claude Sonnet 5, Claude Fable 5, Claude Mythos 5 e Claude Mythos Preview, il thinking è già attivo: nessuna configurazione necessaria. La prima cosa di cui la maggior parte degli sviluppatori ha bisogno su questi modelli è vedere il testo del thinking, perché display ha come valore predefinito "omitted". Attivalo con thinking: {"type": "adaptive", "display": "summarized"}, che è esattamente la seguente richiesta con la stringa del modello sostituita.

Su Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 e Claude Sonnet 4.6, il thinking è disattivato finché non imposti thinking: {type: "adaptive"}, che consente a Claude di decidere quando e con quale profondità ragionare in base alla richiesta. Gli esempi seguenti fanno questo, impostano display: "summarized" in modo che il testo del thinking sia visibile e usano un max_tokens ampio:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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:
    if block.type == "thinking":
        print(f"\nThinking: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")

L'esecuzione dell'esempio stampa il thinking riepilogato, 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 del thinking contano ai fini di max_tokens, quindi impostalo abbastanza alto da lasciare spazio sia per il thinking che per il testo della risposta. Vedi Controllo dei costi nella pagina sulla regolazione e Thinking e la finestra di contesto.



Disattivare il thinking

Su Claude Sonnet 5, dove il thinking è 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 thinking attivo per impostazione predefinita e accetta thinking: {type: "disabled"} a effort high o inferiore. A effort xhigh o max, il thinking non può essere disattivato: le richieste che combinano thinking: {type: "disabled"} con quei livelli di effort restituiscono un errore 400. Questa restrizione si applica a Claude Opus 5 e ai modelli successivi ed è applicata a ogni richiesta. Con il thinking disabilitato, Claude Opus 5 può occasionalmente emettere chiamate agli strumenti come testo semplice o includere tag XML interni nel suo output visibile. Vedi Esecuzione con thinking disabilitato per le mitigazioni tramite prompt.

Claude Fable 5, Claude Mythos 5 e Claude Mythos Preview rifiutano thinking: {type: "disabled"}: il thinking non può essere disattivato su questi modelli.

Se il tuo modello supporta solo l'extended thinking (vedi la tabella di configurazione per modello), configuralo invece con type: "enabled" e un valore budget_tokens. La pagina Extended thinking copre quella configurazione. E se una qualsiasi configurazione del thinking restituisce un errore 400, Risoluzione dei problemi del thinking associa ogni messaggio di errore alla sua soluzione.



Leggere l'output del thinking



Controllare la visualizzazione del thinking

Il campo display nella configurazione del thinking controlla come il contenuto del thinking viene restituito nelle risposte dell'API. display funziona in entrambe le modalità: impostalo insieme a type: "adaptive" o type: "enabled". Accetta due valori:

• "summarized": i blocchi thinking contengono testo di thinking riepilogato, un riepilogo leggibile del ragionamento di Claude. Questo è il valore predefinito su Claude Opus 4.6, Claude Sonnet 4.6 e modelli precedenti.
• "omitted": i blocchi thinking vengono restituiti con un campo thinking vuoto. Il campo signature contiene comunque il thinking completo crittografato per la continuità multi-turno (vedi Crittografia del thinking). Questo è il valore predefinito su Claude Fable 5, Claude Mythos 5, Claude Opus 5, Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7 e Claude Mythos Preview.

Imposta display: "omitted" quando la tua applicazione non mostra il contenuto del thinking agli utenti. Il vantaggio principale è un tempo più rapido al primo token di testo durante lo streaming: il server salta completamente lo streaming dei token del thinking e consegna solo la signature, quindi la risposta testuale finale inizia lo streaming 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 thinking omesso:

• Ti vengono comunque addebitati i token completi del thinking. L'omissione riduce la latenza, non il costo.
• Se ripassi i blocchi thinking nelle conversazioni multi-turno, passali invariati. Il server decrittografa la signature per ricostruire il thinking originale per la costruzione del prompt (vedi Preservare i blocchi thinking). Qualsiasi testo che inserisci nel campo thinking di un blocco omesso ripassato viene ignorato.
• display non è valido con thinking.type: "disabled" (non c'è nulla da visualizzare).
• Quando usi thinking.type: "adaptive" e il modello salta il thinking per una richiesta semplice, non viene prodotto alcun blocco thinking indipendentemente da display.
• Durante lo streaming con display: "omitted", non vengono emessi eventi thinking_delta. Vedi Streaming del thinking per la sequenza degli eventi.

Nell'SDK Ruby, gli hash semplici accettano display: come mostrano gli esempi. La classe tipizzata ThinkingConfigAdaptive nomina il parametro display_ (con underscore finale, per evitare di oscurare Kernel#display di Ruby). In entrambi i casi, il campo trasmesso è comunque display.



Thinking riepilogato

Quando display è "summarized", il testo del thinking che ricevi è un riepilogo del processo di ragionamento completo di Claude anziché la catena di pensiero grezza. Il thinking riepilogato fornisce tutti i benefici di intelligenza del thinking prevenendo al contempo usi impropri. Nessuna impostazione di display restituisce la catena di pensiero grezza.

Tieni presente quanto segue quando lavori con il thinking riepilogato:

• Ti vengono addebitati i token completi del thinking generati dalla richiesta originale, non i token del riepilogo. Il conteggio dei token di output fatturati non corrisponde al conteggio dei token che vedi nella risposta.
• Su Claude Opus 4.6, Claude Sonnet 4.6 e modelli precedenti, le prime righe dell'output del thinking sono più dettagliate, fornendo un ragionamento approfondito particolarmente utile per scopi di prompt engineering. Claude Mythos Preview riepiloga dal primo token, quindi i suoi blocchi thinking 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 che specifichi nelle tue richieste. Il modello di thinking non vede l'output riepilogato.
• Poiché Anthropic cerca di migliorare la funzionalità di thinking, il comportamento del riepilogo è soggetto a modifiche.



Streaming del thinking

Il thinking funziona con lo streaming. I blocchi thinking vengono trasmessi come eventi thinking_delta all'interno di eventi content_block_delta, seguiti da un singolo evento signature_delta appena prima del content_block_stop del blocco. I blocchi di testo vengono trasmessi successivamente come di consueto.

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

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-8",
    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:
        if event.type == "content_block_start":
            print(f"\nStarting {event.content_block.type} block...")
        elif event.type == "content_block_delta":
            if event.delta.type == "thinking_delta":
                print(event.delta.thinking, end="", flush=True)
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)

Per riassemblare blocchi thinking completi con le loro signature dopo lo streaming, usa l'helper di accumulazione dei messaggi del tuo SDK dove ne esiste uno (ad esempio, stream.get_final_message() in Python o stream.finalMessage() in TypeScript) invece di concatenare i delta manualmente.

Quando display: "omitted" è impostato, il blocco thinking si apre, arriva un singolo signature_delta e il blocco si chiude senza alcun evento thinking_delta. Lo streaming del testo inizia immediatamente 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":"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":""}}

Per la meccanica generale dello streaming, vedi Streaming dei messaggi.



Thinking ed effort

Il parametro thinking controlla se Claude pensa in blocchi di pensiero prima di rispondere; il parametro effort controlla quanto lavoro Claude dedica all'intera risposta, il che in modalità adattiva include quanto spesso e quanto in profondità pensa. Non passare adaptive come valore di effort: adaptive è una modalità di pensiero, non un livello di effort.

Per sapere cosa fa ciascun livello di effort al comportamento del thinking, vedi la tabella del comportamento del thinking per livello nella pagina Regolare il thinking. La pagina Effort documenta il parametro stesso, inclusi i livelli supportati da ciascun modello. Su Claude Opus 4.5, l'unico modello solo-extended-thinking che supporta effort, effort si compone con budget_tokens. Vedi Regole e ottimizzazione del budget.

Con i due controlli separati in questo modo, scegli quello che corrisponde al tuo obiettivo:

• Ridurre costo o latenza su un carico di lavoro con thinking abilitato: abbassa prima effort. Ridimensiona l'intera risposta, thinking incluso.
• Claude ragiona troppo raramente o troppo superficialmente: aumenta effort, oppure vedi Regolare la frequenza con cui Claude ragiona nella pagina sulla regolazione.
• Hai bisogno di disattivare completamente il thinking: usa thinking: {type: "disabled"} sui modelli che lo consentono (vedi la tabella di configurazione per modello).
• Hai bisogno di un tetto rigido sulla spesa: usa max_tokens. Effort è una guida morbida. max_tokens è un limite rigoroso.



Thinking con l'uso degli strumenti

Il thinking funziona insieme all'uso degli strumenti, consentendo a Claude di ragionare sulla selezione degli strumenti ed elaborare i risultati degli strumenti. Si applicano due vincoli:

1. Limitazione della scelta dello strumento (modalità manuale): l'uso degli strumenti con extended thinking manuale (thinking: {type: "enabled"}) supporta solo tool_choice: {"type": "auto"} (il valore predefinito) o tool_choice: {"type": "none"}. Usare 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 l'extended thinking manuale. Il thinking adattivo, inclusi i modelli in cui il thinking è attivo per impostazione predefinita, supporta l'uso forzato degli strumenti.
2. Preservare i blocchi thinking: quando restituisci i risultati degli strumenti, devi ripassare all'API i blocchi thinking dal messaggio dell'assistente, completi e non modificati. Vedi Preservare i blocchi thinking.

Un ciclo di uso degli strumenti è un singolo 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 risultati. Questa intera sequenza è un singolo 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 una singola modalità di thinking: non puoi attivare o disattivare il thinking nel mezzo di un turno, incluso durante il ciclo di uso degli strumenti. In modalità extended (manuale), l'API impone inoltre che il turno finale dell'assistente di una richiesta con thinking abilitato inizi con un blocco thinking. La modalità adattiva rilassa questo vincolo: nessun turno dell'assistente deve iniziare con uno.

I conflitti a metà turno degradano in modo controllato. Se attivi o disattivi il thinking a metà turno (ad esempio, tra l'invio di una chiamata a uno strumento e la restituzione del suo risultato), l'API non genera un errore. Invece, disabilita silenziosamente il thinking per quella richiesta. Per preservare la qualità del modello, l'API può rimuovere i blocchi thinking che creerebbero una struttura di turno non valida, o disabilitare il thinking quando la cronologia della conversazione è incompatibile con il thinking abilitato. Per confermare se il thinking era attivo, verifica la presenza di blocchi thinking nella risposta.

Cambia tra i turni, non all'interno di essi. Pianifica la tua strategia di thinking all'inizio di ogni turno. Completa il turno dell'assistente, poi cambia la configurazione del thinking per il 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 le modalità di thinking invalida anche la cache dei prompt. Vedi Thinking e cache dei prompt.



Preservare i blocchi thinking

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 ogni blocco thinking all'API completo e non modificato, insieme al blocco tool_use che lo 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 consente 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 thinking vecchio. 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 thinking per modello. Per sovrascrivere il valore predefinito, usa la strategia di context-editing 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 su due turni con codice in ogni SDK, vedi Thinking nei flussi di lavoro con strumenti e multi-turno. Definisce uno strumento, riceve una risposta thinking-più-tool-use e ripassa il turno dell'assistente con il risultato dello strumento.



Thinking intercalato

Il thinking intercalato consente a Claude di ragionare tra le chiamate agli strumenti, ragionando su ciascun risultato dello strumento prima di agire su di esso. Con il thinking intercalato, Claude può:

• Ragionare sui risultati di una chiamata a uno strumento prima di decidere cosa fare dopo
• Concatenare più chiamate agli strumenti con passaggi di ragionamento intermedi
• Prendere decisioni più sfumate basate sui risultati intermedi

Con il thinking adattivo, il thinking intercalato è automatico su ogni modello che supporta il thinking adattivo. Non è necessario alcun header beta. Su Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5, Claude Opus 4.8 e Claude Opus 4.7, il ragionamento tra le chiamate agli strumenti appare sempre nei blocchi thinking. Claude Haiku 4.5 non supporta il thinking intercalato. Sui modelli che usano l'extended thinking manuale, l'intercalazione richiede un header beta e cambia il modo in cui viene conteggiato il budget del thinking. Thinking intercalato in modalità manuale copre le regole per modello e il comportamento degli header specifico per piattaforma.

Con il thinking intercalato, l'allocazione del thinking può estendersi sull'intero turno dell'assistente anziché su una singola risposta. Il thinking intercalato è supportato solo per strumenti usati tramite l'API Messages.

Per un confronto pratico che mostra cosa cambia il thinking intercalato in un flusso di lavoro con due strumenti, vedi Come il thinking intercalato cambia il flusso.



Preservazione dei blocchi thinking per modello

Se i blocchi thinking dei turni precedenti dell'assistente rimangono nel contesto per impostazione predefinita dipende dal modello:

• Mantieni tutti i turni precedenti: Claude Opus 4.5 e modelli Opus successivi, Claude Sonnet 4.6 e modelli Sonnet successivi, Claude Fable 5, Claude Mythos 5 e Claude Mythos Preview.
• Mantieni solo l'ultimo turno: modelli Opus e Sonnet precedenti, e tutti i modelli Haiku fino a Claude Haiku 4.5. Quando ripassi blocchi thinking più vecchi, l'API li rimuove automaticamente. Non devi rimuoverli tu stesso.

La preservazione porta due vantaggi:

• Ottimizzazione della cache: i blocchi thinking preservati abilitano i cache hit durante l'uso degli strumenti, poiché vengono ripassati con i risultati degli strumenti e memorizzati nella cache in modo incrementale attraverso il turno dell'assistente, con conseguente risparmio di token nei flussi di lavoro multi-step.
• Nessun impatto sull'intelligenza: preservare i blocchi thinking non ha alcun effetto negativo sulle prestazioni del modello.

Il compromesso è l'uso del contesto: le conversazioni lunghe consumano più spazio di contesto sui modelli che mantengono tutto, perché i blocchi thinking conservati contano come input come qualsiasi altra cronologia della conversazione (vedi Thinking e la finestra di contesto). Il comportamento è automatico in entrambi i regimi. Non sono richieste modifiche al codice o header beta, e dovresti continuare a ripassare blocchi thinking completi e non modificati come descritto in Preservare i blocchi thinking. Per sovrascrivere il valore predefinito in entrambe le direzioni, usa la cancellazione dei blocchi thinking.

Cambiare modello a metà conversazione. Quando passi da un modello a un altro, ad esempio dopo un fallback per rifiuto del classificatore, rimuovi i blocchi thinking e redacted_thinking dai turni precedenti dell'assistente. I blocchi thinking sono legati al modello che li ha prodotti. Gli altri modelli li ignorano silenziosamente anziché rifiutare la richiesta, ma i blocchi ignorati aggiungono comunque token di input.



Thinking e cache dei prompt

La cache dei prompt interagisce con il thinking in alcuni modi specifici. Le seguenti regole si applicano in entrambe le modalità di thinking.

Le modifiche alla configurazione invalidano la cache. La configurazione del thinking e il livello di effort risolto vengono renderizzati nel prompt stesso, quindi cambiare uno qualsiasi di essi avvia un nuovo prefisso di cache. Passare tra adaptive, enabled e disabled, cambiare budget_tokens e cambiare il valore di effort invalidano tutti i breakpoint della cache: i breakpoint a livello di messaggio mancano sempre, e anche i breakpoint di strumenti e prompt di sistema possono mancare, a seconda di dove il modello renderizza la configurazione. Considera qualsiasi modifica al thinking o all'effort come un riavvio della cache. Le richieste consecutive che mantengono la stessa configurazione preservano la cache, e impostare un parametro esplicitamente al suo valore predefinito equivale a ometterlo. Una dimostrazione pratica con output di utilizzo è nella pagina Regolare il thinking.

I blocchi thinking vengono memorizzati nella cache con i risultati degli strumenti. Durante un ciclo di uso degli strumenti, la memorizzazione nella cache avviene quando effettui una richiesta di follow-up che include i risultati degli strumenti. A quel punto la cronologia della conversazione precedente, inclusi i suoi blocchi thinking, può essere memorizzata nella cache, e quei blocchi thinking memorizzati contano come token di input nelle tue metriche di utilizzo quando vengono letti dalla cache. Questo avviene automaticamente, anche senza marcatori cache_control espliciti, e si comporta allo stesso modo per il thinking regolare e intercalato. Il compromesso: i blocchi thinking che non vedi mai più nelle risposte contribuiscono comunque all'uso dei token di input quando vengono letti dalla cache.

Se i blocchi precedenti sono nel contesto dipende dal modello. Il valore predefinito di preservazione governa questo. Sui modelli che mantengono tutto, i blocchi thinking dei turni precedenti rimangono nella cache e nel contesto. Sui modelli che mantengono solo l'ultimo turno, una volta che invii un messaggio utente che non è un risultato di strumento, tutti i blocchi thinking precedenti vengono rimossi dal contesto. Su quei 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 thinking non fossero mai stati presenti:

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 mantengono tutto, la stessa richiesta mantiene thinking_block_1 e thinking_block_2 nel contesto e nella cache.

La degradazione rimuove il thinking dalla cronologia memorizzabile nella cache. Se il thinking viene disabilitato a metà turno e passi contenuto thinking nel turno corrente di uso degli strumenti, il contenuto thinking viene rimosso e il thinking rimane disabilitato per quella richiesta (vedi degradazione controllata). Il thinking intercalato amplifica gli effetti di invalidazione della cache, perché i blocchi thinking possono verificarsi tra più chiamate agli strumenti.



Thinking e la finestra di contesto

max_tokens, che include tutto il thinking che Claude genera nel turno corrente, viene applicato come limite rigoroso. Sui modelli Claude 4.5 e successivi, se i token di input più max_tokens superano la dimensione della finestra di contesto, l'API accetta la richiesta. Se la generazione raggiunge poi il limite della finestra di contesto, si ferma 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 degli stop reason.

Come il thinking conta ai fini della finestra dipende da quando è stato generato:

• Il thinking 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 thinking dei turni precedenti dipende dal valore predefinito di preservazione. Sui modelli che mantengono tutti i turni precedenti, i blocchi thinking precedenti rimangono nel contesto, contano ai fini della finestra e vengono fatturati come token di input come il resto della cronologia della conversazione. Sui modelli che mantengono solo l'ultimo turno, l'API rimuove automaticamente i blocchi thinking più vecchi quando li ripassi, quindi non consumano spazio nella finestra o token di input.

In pratica:

• Sui modelli che mantengono tutto, pianifica la tua finestra di contesto come se il thinking fosse cronologia ordinaria della conversazione, perché lo è. Le sessioni agentiche lunghe accumulano thinking nel contesto. Usa la cancellazione dei blocchi thinking se hai bisogno di recuperare spazio.
• Sui modelli che mantengono solo l'ultimo turno, il thinking è solo un costo per turno: il thinking di ogni turno conta ai fini del max_tokens di quel turno e poi esce dalla finestra.

I seguenti diagrammi illustrano il regime solo-ultimo-turno (rimozione). Il primo mostra una conversazione multi-turno: il blocco thinking di ogni turno viene generato nell'output ma non trasportato nell'input dei turni successivi.

Il secondo mostra lo stesso regime con l'uso degli strumenti: il thinking rimane nel contesto insieme al suo risultato dello strumento per 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, specialmente per conversazioni multi-turno che includono thinking.



Crittografia del thinking

Il contenuto completo del thinking è crittografato e restituito nel campo signature su ogni blocco thinking. L'API usa la signature per verificare che i blocchi thinking siano stati generati da Claude quando li ripassi.

Tieni presente quanto segue quando lavori con le signature:

• È strettamente necessario ripassare i blocchi thinking solo quando usi strumenti con il thinking. Altrimenti puoi omettere i blocchi thinking dai turni precedenti. Se li ripassi, se l'API li mantiene o li rimuove dipende dal modello (vedi Preservazione dei blocchi thinking per modello). Usa il context editing per configurare questo.
• Quando ripassi i blocchi thinking, passa tutto esattamente come lo 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 appena prima dell'evento content_block_stop.
• I valori signature sono significativamente più lunghi nei modelli Claude 4 e successivi rispetto ai modelli precedenti.
• Il campo signature è opaco: non interpretarlo o analizzarlo.
• I valori signature sono compatibili tra piattaforme (l'API Claude, Amazon Bedrock e Google Cloud). I valori generati su una piattaforma funzionano su un'altra.



Blocchi redacted thinking

Oltre ai blocchi thinking regolari, l'API può restituire blocchi redacted_thinking quando porzioni del ragionamento di Claude vengono oscurate per motivi di sicurezza. Un blocco redacted_thinking contiene contenuto thinking crittografato in un campo data, senza testo leggibile:

{
  "type": "redacted_thinking",
  "data": "..."
}

Il campo data è opaco e crittografato. Come il campo signature sui blocchi thinking regolari, ripassa i blocchi redacted_thinking all'API invariati quando continui una conversazione multi-turno con strumenti.



Output del thinking su Claude Fable 5 e Claude Mythos 5

Su Claude Fable 5 e Claude Mythos 5, la catena di pensiero grezza non viene mai restituita. I blocchi che ricevi sono blocchi thinking regolari, non redacted_thinking, e l'impostazione display funziona allo stesso modo degli altri modelli (testo riepilogato, o un campo thinking vuoto quando omesso, il valore predefinito qui). Per la forma della risposta dei blocchi thinking, vedi il riferimento dell'API Messages.

Quando continui una conversazione sullo stesso modello, ripassa ogni blocco thinking all'API esattamente come ricevuto, inclusi i blocchi il cui campo thinking è vuoto. Non modificarli o ricostruirli. Leggere il testo del riepilogo per la visualizzazione va bene: l'API rifiuta i blocchi il cui contenuto restituito è stato modificato, non i blocchi che hai letto. Il testo inserito in un campo thinking omesso vuoto viene ignorato anziché rifiutato.

Per come vengono gestiti i blocchi thinking quando cambi modello a metà conversazione, vedi Preservazione dei blocchi thinking per modello.

Due eccezioni, trattate in Credito di fallback:

• I retry con credito di fallback devono ripassare il corpo della richiesta rifiutata invariato.
• I blocchi fallback da un fallback a metà output rimangono dove sono apparsi.

Per ottenere visibilità sul ragionamento del modello, leggi i blocchi thinking descritti in questa pagina anziché richiedere il ragionamento nel testo della risposta. Su Claude Fable 5, una richiesta che tenta di estrarre 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 le indicazioni di gestione.



Limiti e compatibilità delle funzionalità

Parametri di campionamento. Su Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7 e Claude Sonnet 5, valori non predefiniti di temperature, top_p o top_k restituiscono un errore 400 su ogni richiesta, indipendentemente dal fatto che il pensiero sia utilizzato o meno. Sui modelli più vecchi, la restrizione si applica solo quando il pensiero è attivo: temperature e top_k sono incompatibili con il pensiero, mentre top_p è consentito con valori compresi tra 0,95 e 1.

Precompilazione della risposta e uso forzato degli strumenti. Non è possibile precompilare la risposta dell'assistente mentre il pensiero è attivo. L'uso forzato degli strumenti (tool_choice: {"type": "any"} o {"type": "tool", ...}) è incompatibile con il pensiero esteso manuale ma funziona con il pensiero adattivo. Consulta Pensiero con uso degli strumenti.

Limiti di output. Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5, Claude Opus 4.6 e Claude Sonnet 4.6 supportano fino a 128k token di output per richiesta. Claude Haiku 4.5, Claude Sonnet 4.5 e Claude Opus 4.5 supportano fino a 64k. Sulla Message Batches API, il beta header output-300k-2026-03-24 aumenta il limite a 300k per Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5, Claude Opus 4.6 e Claude Sonnet 4.6. Consulta la panoramica dei modelli per i limiti sui modelli legacy.

Richieste lunghe. Gli SDK richiedono lo streaming quando max_tokens è maggiore di 21.333, per evitare timeout HTTP su 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() (Python) o .finalMessage() (TypeScript) per ottenere l'oggetto Message completo senza gestire i singoli eventi. Consulta Streaming Messages. Aspettati tempi di risposta più lunghi quando il pensiero è attivo, perché la generazione dei blocchi di pensiero aggiunge tempo di elaborazione. Per carichi di lavoro che spingono il pensiero oltre circa 32k token per richiesta, usa l'elaborazione 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.



Passaggi successivi