Risoluzione dei problemi del pensiero

Questa pagina copre i problemi più comuni durante la configurazione del pensiero o il round-trip dei blocchi di pensiero (rinviare i blocchi di pensiero restituiti nelle richieste successive). La prima sezione mappa ogni modello alle configurazioni di pensiero supportate e a quelle che rifiuta; le sezioni successive partono ciascuna da un sintomo che osservi, così puoi associare un messaggio di errore o una risposta inattesa direttamente alla sua causa e alla soluzione. Per come funziona il pensiero, consulta la panoramica sul Pensiero.



Configurazioni che ogni modello rifiuta

La maggior parte degli errori di configurazione del pensiero è 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 usano invece l'"extended thinking" (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 ciò che ogni modello supporta, 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 come impostazione predefinita ma accettano thinking: {type: "disabled"}.

I modelli Claude 4 precedenti (Claude Sonnet 4 e Claude Opus 4) supportano solo il pensiero esteso; consulta le 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 dice 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 che hai richiesto ha rimosso il pensiero esteso (vedi Configurazioni che ogni modello rifiuta).

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



Un errore 400 dice 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, il suggerimento di "thinking.type.enabled" nel testo dell'errore non si applica nemmeno: anche quei modelli lo rifiutano.

Ometti il parametro thinking; questi modelli pensano senza alcuna configurazione. Se il tuo obiettivo era tenere il testo del pensiero fuori 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 dice 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 che ogni modello rifiuta).

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



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

Una richiesta che restituisce risultati di strumenti fallisce con un errore 400 invalid_request_error 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 invii i messaggi precedenti dell'assistente, inclusi i loro blocchi thinking e redacted_thinking, di nuovo all'API, e l'API verifica che arrivino non modificati. Questo errore si verifica quando il messaggio dell'assistente che rinvii differisce da quello che l'API ha restituito, il più delle volte perché il tuo codice filtra i blocchi di contenuto per tipo ed elimina i blocchi redacted_thinking, oppure ricostruisce il messaggio dell'assistente invece di riproporlo.

Rinvia il turno dell'assistente alla lettera, blocchi di pensiero inclusi. Consulta Preservare i blocchi di pensiero per le regole, e il round trip svolto in Il 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 ha come valore predefinito "omitted" sui 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 del pensiero riassunto; vedi 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 con il prompting; vedi Regolare quanto spesso 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 suo testo visibile. Una chiamata a uno strumento trapelata non viene mai eseguita, e nei loop agentici il testo trapelato rimane nella cronologia della conversazione, quindi anche i turni successivi ne risentono.

Questo accade su Claude Opus 5 quando il pensiero è disabilitato, più comunemente su carichi di lavoro intensivi 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.

Riabilita il pensiero (l'impostazione predefinita) e usa livelli di effort più bassi per controllare il costo dei token. Se la tua integrazione deve mantenere il pensiero disabilitato, applica le mitigazioni di prompting 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 di pensiero contano ai fini di max_tokens, quindi un passaggio di pensiero lungo 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 Il pensiero e la finestra di contesto.



I cache hit calano dopo aver modificato le impostazioni del pensiero

cache_read_input_tokens scende a zero su richieste che in precedenza colpivano la 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 rende la configurazione.

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



Impostare effort non cambia il pensiero

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

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à viene eseguito 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 e regolazione del budget.



Prossimi passi