Risoluzione dei problemi del pensiero

Questa pagina tratta i problemi più comuni che si verificano durante la configurazione del pensiero o il "round-tripping" (invio e ritorno) dei blocchi di pensiero (ovvero il reinvio dei blocchi di pensiero restituiti nelle richieste successive). La prima sezione associa ogni modello alle configurazioni di pensiero supportate e a quelle che rifiuta; le sezioni successive partono ciascuna da un sintomo osservabile, così puoi abbinare direttamente un messaggio di errore o una risposta inattesa alla sua causa e alla relativa soluzione. Per capire come funziona il pensiero, consulta la panoramica Pensiero.



Configurazioni rifiutate da ciascun modello

La maggior parte degli errori di configurazione del pensiero deriva da una discrepanza tra il valore thinking.type nella richiesta e ciò che il modello supporta. Sui modelli attuali, il pensiero viene eseguito come thinking: {type: "adaptive"} e, sui più recenti, è attivo per impostazione predefinita. Alcuni modelli precedenti utilizzano invece il pensiero esteso, una modalità manuale legacy configurata come thinking: {type: "enabled", budget_tokens: N}.

Il pensiero esteso (thinking.type: "enabled" con budget_tokens) è deprecato sui modelli Claude 4.6 (le richieste che lo utilizzano continuano a funzionare). Claude 4.7 e i modelli successivi non lo supportano e rifiutano le richieste che lo utilizzano, restituendo un errore 400. Sui modelli Claude 4.5 e precedenti che supportano il pensiero, il pensiero esteso è l'unica modalità di pensiero disponibile. Claude Mythos Preview supporta entrambe le modalità. Dove entrambe le modalità sono disponibili, usa invece il pensiero adattivo.

La tabella elenca cosa supporta ciascun modello, qual è il suo valore predefinito e quali valori di thinking.type rifiuta con un errore 400; qualsiasi valore non elencato come rifiutato è accettato.

¹ enabled e budget_tokens funzionano ancora su questi modelli ma sono deprecati; usa invece il pensiero adattivo.
² Claude Opus 5 accetta "disabled" con effort high o inferiore; combinarlo con effort xhigh o max restituisce un errore 400. Questa restrizione si applica a Claude Opus 5 e ai modelli successivi ed è applicata a ogni richiesta.

I modelli contrassegnati come Sempre attivo non possono disattivare il pensiero. I modelli contrassegnati come Attivo hanno il pensiero attivo per impostazione predefinita ma accettano thinking: {type: "disabled"}.

I modelli Claude 4 precedenti (Claude Opus 4.1, Claude Sonnet 4 e Claude Opus 4) supportano solo il pensiero esteso; consulta Deprecazioni dei modelli per la loro disponibilità. Claude Fable 5 e Claude Mythos 5 non sono disponibili con la zero data retention.



Un errore 400 indica che "thinking.type.enabled" non è supportato

La richiesta fallisce con un errore 400 il cui messaggio recita:

"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

Questo accade perché il modello richiesto ha rimosso il pensiero esteso (vedi Configurazioni rifiutate da ciascun modello).

Modifica la richiesta in thinking: {type: "adaptive"} e regola la profondità del pensiero con effort invece di budget_tokens. Migrazione al pensiero adattivo illustra passo passo la conversione.



Un errore 400 indica che "thinking.type.disabled" non è supportato

La richiesta fallisce con un errore 400 il cui messaggio recita:

"thinking.type.disabled" is not supported for this model. Thinking defaults to adaptive mode when not specified; use "thinking.type.enabled" with "budget_tokens" for extended thinking.

Questo accade sui modelli in cui il pensiero è sempre attivo: Claude Fable 5, Claude Mythos 5 e Claude Mythos Preview rifiutano "disabled". Su Claude Fable 5 e Claude Mythos 5, nemmeno il suggerimento "thinking.type.enabled" presente nel testo dell'errore è applicabile: anche quei modelli lo rifiutano.

Ometti il parametro thinking; questi modelli pensano senza alcuna configurazione. Se il tuo obiettivo era escludere il testo del pensiero dalle risposte, usa display: "omitted" invece di disabilitare il pensiero; vedi Controllare la visualizzazione del pensiero.

Un errore 400 su "disabled" può verificarsi anche su Claude Opus 5, che accetta thinking: {type: "disabled"} solo con effort high o inferiore: combinarlo con effort xhigh o max viene rifiutato. Abbassa il livello di effort oppure lascia il pensiero attivo.



Un errore 400 indica che il pensiero adattivo non è supportato

La richiesta fallisce con un errore 400 il cui messaggio recita:

adaptive thinking is not supported on this model

Questo accade perché il modello supporta solo il pensiero esteso (vedi Configurazioni rifiutate da ciascun modello).

Usa invece thinking: {type: "enabled", budget_tokens: N}; consulta Pensiero esteso per la configurazione.



Un errore 400 indica che i blocchi di pensiero non possono essere modificati

Una richiesta che restituisce risultati di strumenti fallisce con un invalid_request_error 400 il cui messaggio contiene:

`thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified

Nelle conversazioni multi-turno e con uso degli strumenti, reinvii all'API i messaggi precedenti dell'assistente, inclusi i loro blocchi thinking e redacted_thinking, e l'API verifica che arrivino non modificati. Questo errore si verifica quando il messaggio dell'assistente che reinvii differisce da quello restituito dall'API, il più delle volte perché il tuo codice filtra i blocchi di contenuto per tipo e scarta i blocchi redacted_thinking, oppure ricostruisce il messaggio dell'assistente invece di riprodurlo fedelmente.

Reinvia il turno dell'assistente esattamente com'è, blocchi di pensiero inclusi. Consulta Preservare i blocchi di pensiero per le regole, e l'esempio completo di round trip in Pensiero nei flussi di lavoro con strumenti e multi-turno per il codice corretto in ogni SDK.



Il campo thinking è vuoto nella risposta

La risposta contiene blocchi thinking, ma il loro campo thinking è una stringa vuota e solo il campo signature è popolato.

Questo accade perché display è impostato per default su "omitted" nei modelli più recenti, il che restituisce i blocchi di pensiero senza il loro testo.

Imposta display: "summarized" nella tua configurazione del pensiero per ricevere il testo riassunto del pensiero; consulta Controllare la visualizzazione del pensiero per i valori predefiniti per modello.



Nessun blocco di pensiero appare in alcuni turni

Alcune risposte non contengono alcun blocco thinking, anche se il pensiero è configurato.

Questo è normale in modalità adattiva: Claude salta il pensiero sulle richieste che giudica abbastanza semplici da rispondere direttamente.

Se vuoi che il pensiero avvenga più spesso o più in profondità, aumenta effort o guida il comportamento tramite il prompt; vedi Regolare la frequenza con cui Claude pensa.



Chiamate a strumenti o tag XML appaiono nell'output di testo

Una risposta occasionalmente scrive una chiamata a uno strumento nel suo testo invece di emettere un blocco tool_use, oppure include <thinking> o altri tag XML interni nel testo visibile. Una chiamata a uno strumento trapelata nel testo non viene mai eseguita e, nei cicli agentici, il testo trapelato rimane nella cronologia della conversazione, influenzando anche i turni successivi.

Questo accade su Claude Opus 5 quando il pensiero è disabilitato, più comunemente su carichi di lavoro con uso intensivo di strumenti come la ricerca. Le regole nel prompt di sistema che istruiscono il modello a non pensare o a non ragionare aumentano la fuoriuscita di tag.

Riattiva il pensiero (impostazione predefinita) e usa livelli di effort più bassi per controllare il costo in token. Se la tua integrazione deve mantenere il pensiero disabilitato, applica le mitigazioni di prompting descritte in Esecuzione con il pensiero disabilitato.



La risposta si interrompe con stop_reason: "max_tokens"

La risposta termina con stop_reason: "max_tokens", spesso con un blocco di testo troncato o mancante.

Questo accade perché i token del pensiero vengono conteggiati in max_tokens, quindi una lunga fase di pensiero può consumare il budget prima che la risposta testuale sia completata.

Aumenta max_tokens per lasciare spazio sia al pensiero che al testo, oppure abbassa effort in modo che Claude spenda meno per il pensiero; vedi Controllo dei costi e Pensiero e finestra di contesto.



I riscontri nella cache diminuiscono dopo aver modificato le impostazioni del pensiero

cache_read_input_tokens scende a zero su richieste che in precedenza trovavano riscontro nella cache.

Questo accade perché la configurazione del pensiero e il livello di effort (o il suo valore predefinito) fanno parte del prefisso del prompt memorizzato nella cache, quindi modificare uno qualsiasi di essi avvia un nuovo prefisso: cambiare modalità di pensiero, cambiare il valore di effort e cambiare budget_tokens invalidano tutti i breakpoint della cache dei messaggi, e possono invalidare anche i breakpoint degli strumenti e del prompt di sistema, a seconda di dove il modello renderizza la configurazione.

Mantieni costanti la configurazione del pensiero e il livello di effort tra le richieste che condividono una conversazione; impostare esplicitamente un parametro al suo valore predefinito equivale a ometterlo e non causa invalidazione. Vedi Pensiero e cache dei prompt.



Impostare effort non modifica il pensiero

Modifichi effort ma la frequenza o la profondità del pensiero rimane invariata.

Questo accade perché effort è la leva principale del pensiero solo in modalità adattiva. Sui modelli che supportano solo il pensiero esteso, la profondità del pensiero è invece impostata da budget_tokens.

Regola budget_tokens su quei modelli, oppure verifica in quale modalità opera il tuo modello; vedi Pensiero ed effort. Su Claude Opus 4.5, l'unico modello con solo pensiero esteso che supporta effort, effort si compone con il budget; vedi Regole del budget e ottimizzazione.



Passaggi successivi