Pensiero

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

Il pensiero rimuove questo vincolo. Quando il pensiero è attivo, Claude elabora il problema con parole proprie prima di rispondere: riformula ciò che viene chiesto, prova approcci, verifica i risultati intermedi e abbandona i percorsi che non reggono. Quel ragionamento arriva nei blocchi di contenuto thinking prima della risposta, e Claude vi attinge per produrre la risposta finale. Questo è il motivo per cui il pensiero 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 pensiero ha un costo: i token che Claude spende ragionando vengono fatturati come token di output, anche quando il testo del pensiero non ti viene restituito, e contano ai fini di max_tokens insieme al testo della risposta. Questa pagina copre come si comporta il pensiero attraverso la superficie dell'API: attivarlo, leggere il suo output e gestire le sue interazioni con strumenti, streaming, cache e la finestra di contesto.



Come funziona il pensiero

Se Claude pensa su una determinata richiesta, e quanto in profondità, dipende dalla tua configurazione del pensiero e dalla complessità della richiesta.

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

{
  "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 di pensiero è un riassunto del ragionamento di Claude. Il campo display nella configurazione del pensiero controlla se quel riassunto viene restituito o meno: "summarized" lo restituisce, mentre "omitted", il valore predefinito sui modelli più recenti, restituisce blocchi di pensiero 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 pensiero per i valori predefiniti per modello e i dettagli.

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



Configurare il pensiero

Sui modelli attuali, il pensiero è 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 di risoluzione dei problemi.

Su Claude Opus 5, Claude Sonnet 5, Claude Fable 5, Claude Mythos 5 e Claude Mythos Preview, il pensiero è già attivo: nessuna configurazione necessaria. La prima cosa di cui la maggior parte degli sviluppatori ha bisogno su questi modelli è vedere il testo del pensiero, poiché display ha come valore predefinito "omitted" su di essi. Attivalo con thinking: {"type": "adaptive", "display": "summarized"}, che è esattamente la richiesta seguente 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 pensiero è disattivato finché non imposti thinking: {type: "adaptive"} nella tua richiesta. Gli esempi seguenti fanno questo, impostano display: "summarized" in modo che il testo del pensiero sia visibile, e usano un max_tokens generoso:

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 pensiero 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 pensiero contano ai fini di max_tokens, quindi impostalo abbastanza alto da lasciare spazio sia per il pensiero che per il testo della risposta. Vedi Controllo dei costi nella pagina sulla regolazione e Il pensiero e la finestra di contesto.



Disattivare il pensiero

Su Claude Sonnet 5, dove il pensiero è 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 pensiero attivo per impostazione predefinita e accetta thinking: {type: "disabled"} a livello di effort high o inferiore. A livello di effort xhigh o max, il pensiero 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 pensiero 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 il pensiero disabilitato per le mitigazioni tramite prompting.

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

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



Leggere l'output del pensiero



Controllare la visualizzazione del pensiero

Il campo display nella configurazione del pensiero controlla come il contenuto del pensiero 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 di pensiero contengono testo di pensiero riassunto, un riassunto leggibile del ragionamento di Claude. Questo è il valore predefinito su Claude Opus 4.6, Claude Sonnet 4.6 e modelli precedenti.
• "omitted": i blocchi di pensiero vengono restituiti con un campo thinking vuoto. Il campo signature contiene comunque il pensiero completo crittografato per la continuità multi-turno (vedi Crittografia del pensiero). 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 pensiero 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 di pensiero e consegna solo la signature, quindi la risposta di testo 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 pensiero omesso:

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

Nell'SDK Ruby, imposta questo campo come display_: (con un underscore finale) per evitare di oscurare Kernel#display di Ruby; il campo sul wire è comunque display.



Pensiero riassunto

Quando display è "summarized", il testo del pensiero che ricevi è un riassunto del processo di pensiero completo di Claude piuttosto che la catena di pensiero grezza. Il pensiero riassunto fornisce tutti i benefici di intelligenza del pensiero prevenendo al contempo gli abusi. Nessuna impostazione di display restituisce la catena di pensiero grezza.

Tieni presente quanto segue quando lavori con il pensiero riassunto:

• Ti vengono addebitati i token di pensiero completi generati dalla richiesta originale, non i token del riassunto. 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 pensiero sono più dettagliate, fornendo un ragionamento dettagliato particolarmente utile per scopi di prompt engineering. Claude Mythos Preview riassume dal primo token, quindi i suoi blocchi di pensiero non mostrano questo preambolo dettagliato.
• Il riassunto preserva le idee chiave del processo di pensiero di Claude con una latenza aggiuntiva minima, consentendo un'esperienza utente in streaming.
• Il riassunto è elaborato da un modello diverso da quello a cui ti rivolgi nelle tue richieste. Il modello di pensiero non vede l'output riassunto.
• Poiché Anthropic cerca di migliorare la funzionalità di pensiero, il comportamento del riassunto è soggetto a modifiche.



Streaming del pensiero

Il pensiero funziona con lo streaming. I blocchi di pensiero vengono trasmessi in streaming 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 in streaming successivamente come di consueto.

Gli esempi seguenti trasmettono in streaming una risposta con pensiero adattivo, stampando i delta di pensiero e di 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)

Quando è impostato display: "omitted", il blocco di pensiero 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 i meccanismi generali dello streaming, vedi Streaming dei messaggi.



Pensiero 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 pensiero, vedi la tabella del comportamento del pensiero per livello nella pagina Regolare il pensiero; la pagina Effort documenta il parametro stesso, inclusi i livelli supportati da ciascun modello. Su Claude Opus 4.5, l'unico modello solo a pensiero esteso 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:

• Costo o latenza inferiori su un carico di lavoro con pensiero abilitato: abbassa prima effort. Riduce l'intera risposta, pensiero incluso.
• Claude pensa troppo raramente o troppo superficialmente: aumenta effort, oppure vedi Regolare la frequenza con cui Claude pensa nella pagina sulla regolazione.
• Hai bisogno che il pensiero sia completamente disattivato: 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 flessibile; max_tokens è un limite rigoroso.



Pensiero con uso degli strumenti

Il pensiero 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 degli strumenti (modalità manuale): l'uso degli strumenti con il pensiero 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, che è incompatibile con il pensiero esteso manuale. Il pensiero adattivo, inclusi i modelli in cui il pensiero è attivo per impostazione predefinita, supporta l'uso forzato degli strumenti.
2. Preservare i blocchi di pensiero: quando restituisci i risultati degli strumenti, devi restituire all'API i blocchi di pensiero del messaggio dell'assistente, completi e non modificati. Vedi Preservare i blocchi di pensiero.

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 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 un'unica modalità di pensiero: non puoi attivare o disattivare il pensiero a metà di un turno, incluso 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 pensiero abilitato inizi con un blocco di pensiero. La modalità adattiva allenta questo vincolo: nessun turno dell'assistente deve iniziare con uno.

I conflitti a metà turno degradano in modo controllato. Se attivi o disattivi il pensiero 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 pensiero per quella richiesta. Per preservare la qualità del modello, l'API può rimuovere i blocchi di pensiero che creerebbero una struttura di turno non valida, o disabilitare il pensiero quando la cronologia della conversazione è incompatibile con il pensiero abilitato. Per confermare se il pensiero era attivo, verifica la presenza di blocchi thinking nella risposta.

Cambia tra i turni, non al loro interno. Pianifica la tua strategia di pensiero all'inizio di ogni turno. Completa il turno dell'assistente, poi cambia la configurazione del pensiero per quello 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)

Nota che il cambio delle modalità di pensiero invalida anche la cache dei prompt; vedi Pensiero e cache dei prompt.



Preservare i blocchi di pensiero

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. Restituisci all'API ogni blocco thinking completo e non modificato, insieme al blocco tool_use che lo accompagnava. Questo è importante per due motivi:

1. Continuità del ragionamento: i blocchi di pensiero catturano il ragionamento passo dopo passo che ha portato alle richieste di strumenti. Includerli consente a Claude di continuare a ragionare da dove si era interrotto.
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 di pensiero mantiene quel flusso attraverso le chiamate API.

In breve:

• Obbligatorio: all'interno di un turno di uso degli strumenti, restituisci i blocchi di pensiero.
• Consigliato: tra i turni, restituisci tutto.
• Consentito: al di fuori dell'uso degli strumenti, ometti il pensiero dei turni precedenti.

Non devi eliminare tu stesso il vecchio pensiero. Restituisci tutti i blocchi di pensiero 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 pensiero per modello. Per sovrascrivere il valore 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 Il pensiero nei flussi di lavoro con strumenti e multi-turno. Definisce uno strumento, riceve una risposta con pensiero più uso degli strumenti e restituisce il turno dell'assistente con il risultato dello strumento.



Pensiero intercalato

Il pensiero intercalato consente a Claude di pensare tra le chiamate agli strumenti, ragionando su ciascun risultato dello strumento prima di agire su di esso. Con il pensiero 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 pensiero adattivo, il pensiero intercalato è automatico su ogni modello che supporta il pensiero 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 di pensiero. Claude Haiku 4.5 non supporta il pensiero intercalato. Sui modelli che usano il pensiero esteso manuale, l'intercalazione richiede un header beta e cambia il modo in cui viene conteggiato il budget di pensiero; Pensiero intercalato in modalità manuale copre le regole per modello e il comportamento dell'header specifico per piattaforma.

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

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



Preservazione dei blocchi di pensiero per modello

Se i blocchi di pensiero 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 restituisci blocchi di pensiero più vecchi, l'API li rimuove automaticamente; non devi rimuoverli tu stesso.

La preservazione porta due vantaggi:

• Ottimizzazione della cache: i blocchi di pensiero preservati consentono cache hit durante l'uso degli strumenti, poiché vengono restituiti 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 a più passaggi.
• Nessun impatto sull'intelligenza: preservare i blocchi di pensiero 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, poiché i blocchi di pensiero conservati contano come input come qualsiasi altra cronologia di conversazione (vedi Il pensiero 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 restituire blocchi di pensiero completi e non modificati come descritto in Preservare i blocchi di pensiero. Per sovrascrivere il valore predefinito in entrambe le direzioni, usa la cancellazione dei blocchi di pensiero.

Cambiare modello a metà conversazione. Quando passi da un modello all'altro, ad esempio dopo un fallback per rifiuto del classificatore, rimuovi i blocchi thinking e redacted_thinking dai turni precedenti dell'assistente. I blocchi di pensiero 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.



Pensiero e cache dei prompt

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

Le modifiche alla configurazione invalidano la cache. La configurazione del pensiero e il livello di effort risolto vengono resi nel prompt stesso, quindi cambiare uno qualsiasi di essi avvia un nuovo prefisso di cache. Il passaggio tra adaptive, enabled e disabled, la modifica di budget_tokens e la modifica del 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 rende la configurazione. Considera qualsiasi modifica al pensiero o all'effort come un riavvio della cache. Le richieste consecutive che mantengono la stessa configurazione preservano la cache, e impostare esplicitamente un parametro al suo valore predefinito equivale a ometterlo. Una dimostrazione pratica con output di utilizzo si trova nella pagina Regolare il pensiero.

I blocchi di pensiero 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 di pensiero, può essere memorizzata nella cache, e quei blocchi di pensiero memorizzati nella cache 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 pensiero regolare e intercalato. Il compromesso: i blocchi di pensiero che non vedi mai più nelle risposte contribuiscono comunque all'utilizzo 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 di pensiero 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 uno strumento, tutti i blocchi di pensiero 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 di pensiero non fossero mai esistiti:

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 pensiero dalla cronologia memorizzabile nella cache. Se il pensiero viene disabilitato a metà turno e passi contenuto di pensiero nel turno di uso degli strumenti corrente, il contenuto di pensiero viene rimosso e il pensiero rimane disabilitato per quella richiesta (vedi degradazione controllata). Il pensiero intercalato amplifica gli effetti di invalidazione della cache, poiché i blocchi di pensiero possono verificarsi tra più chiamate agli strumenti.



Il pensiero e la finestra di contesto

max_tokens, che include tutto il pensiero che Claude genera nel turno corrente, è applicato come limite rigoroso. Sui modelli Claude 4.5 e più recenti, 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 dei motivi di arresto.

Come il pensiero conta rispetto alla finestra dipende da quando è stato generato:

• Il pensiero 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 pensiero dei turni precedenti dipende dal valore predefinito di preservazione. Sui modelli che mantengono tutti i turni precedenti, i blocchi di pensiero 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 di pensiero più vecchi quando li restituisci, quindi non consumano spazio nella finestra né token di input.

In pratica:

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

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

Il secondo mostra lo stesso regime con l'uso degli strumenti: il pensiero 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 le conversazioni multi-turno che includono il pensiero.



Crittografia del pensiero

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

Tieni presente quanto segue quando lavori con le signature:

• È strettamente necessario restituire i blocchi di pensiero solo quando usi strumenti con il pensiero. Altrimenti puoi omettere i blocchi di pensiero dei turni precedenti. Se li restituisci, se l'API li mantiene o li rimuove dipende dal modello (vedi Preservazione dei blocchi di pensiero per modello); usa la modifica del contesto per configurarlo.
• Quando restituisci i blocchi di pensiero, restituisci 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 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 (API Claude, Amazon Bedrock e Google Cloud). I valori generati su una piattaforma funzionano su un'altra.



Blocchi di pensiero oscurati

Oltre ai normali blocchi thinking, 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 di pensiero 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 pensiero, restituisci i blocchi redacted_thinking all'API invariati quando continui una conversazione multi-turno con strumenti.



Output del pensiero 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 normali blocchi thinking, non redacted_thinking, e l'impostazione display funziona allo stesso modo degli altri modelli (testo riassunto, o un campo thinking vuoto quando omesso, il valore predefinito qui). Per la forma della risposta dei blocchi di pensiero, vedi il riferimento dell'API Messages.

Quando continui una conversazione sullo stesso modello, restituisci ogni blocco di pensiero all'API esattamente come ricevuto, inclusi i blocchi il cui campo thinking è vuoto. Non modificarli né ricostruirli. Leggere il testo del riassunto 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 sapere cosa succede ai blocchi di pensiero quando cambi modello a metà conversazione, vedi Preservazione dei blocchi di pensiero per modello.

Due eccezioni, trattate in Credito di fallback:

• I nuovi tentativi con credito di fallback devono riprodurre 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 tramite prompt. 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 ai campi e le indicazioni sulla 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 mentre il pensiero è attivo: temperature e top_k sono incompatibili con il pensiero, e top_p è consentito con valori compresi tra 0.95 e 1.

Prefill della risposta e uso forzato degli strumenti. Non puoi 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, l'header beta 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. Questa è una validazione lato client, non 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 dei messaggi. Aspettati tempi di risposta più lunghi quando il pensiero è attivo, poiché la generazione dei blocchi di pensiero aggiunge tempo di elaborazione. Per i 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.



Prossimi passi