Thinking

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" (pensiero) rimuove questo vincolo. Quando il thinking è attivo, Claude elabora il problema con le proprie parole prima di rispondere: riformula ciò che viene chiesto, prova approcci, verifica i risultati intermedi e abbandona i percorsi che non reggono. Questo ragionamento arriva in blocchi di contenuto thinking prima della risposta, e Claude vi attinge per produrre la risposta finale. È per questo che 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 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 thinking

Se Claude pensa su una determinata richiesta, e quanto in 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 porta 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 sempre vedi 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 o meno: "summarized" lo restituisce, mentre "omitted", il valore predefinito su molti modelli, 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 per modello e i dettagli.

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

Sulla maggior parte dei modelli, il thinking è attivo per impostazione predefinita o a un parametro di distanza. Quale configurazione accetta ciascun modello, e quale è 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.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5 e Claude Mythos Preview, il thinking è già attivo e non richiede configurazione. display ha come valore predefinito "omitted" su questi modelli, quindi il testo del thinking è nascosto finché non scegli di attivarlo. Attivalo con thinking: {"type": "adaptive", "display": "summarized"}, che corrisponde esattamente alla 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 thinking è disattivato finché non imposti thinking: {type: "adaptive"}, che lascia a Claude decidere quando e quanto in profondità pensare in base alla richiesta. Gli esempi seguenti fanno proprio 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}")

Eseguendo l'esempio viene stampato 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 di thinking contano ai fini di max_tokens, quindi impostalo abbastanza alto da lasciare spazio sia al thinking sia al 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"} con effort high o inferiore. Con 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 e viene applicata a ogni richiesta. Con il thinking 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 thinking disattivato per le mitigazioni tramite prompt.

Claude Fable 5.1, Claude Mythos 5.1, 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" (pensiero esteso) (vedi la tabella di configurazione per modello), configuralo invece con type: "enabled" e un valore budget_tokens. La pagina Pensiero esteso descrive 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 questi valori:

• "summarized": i blocchi thinking contengono testo di thinking riepilogato, 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 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). È il valore predefinito su Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5, Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7 e Claude Mythos Preview.
• "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 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 di 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 tutti i token di thinking. L'omissione riduce la latenza, non il costo.
• Se ripassi i blocchi thinking nelle conversazioni multi-turno, ripassali invariati. Il server decrittografa la signature per ricostruire il thinking originale per la costruzione del prompt (vedi Preservare i blocchi thinking). Qualsiasi testo inserito 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. Con display: "updates", solo i blocchi di aggiornamento di avanzamento trasmettono 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 chiama 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 pensiero completo di Claude anziché la catena di pensiero grezza. Il thinking riepilogato fornisce tutti i benefici di intelligenza del thinking prevenendone l'uso improprio. Nessuna impostazione di display restituisce la catena di pensiero grezza.

Tieni presente quanto segue quando lavori con il thinking riepilogato:

• Ti vengono addebitati tutti i token di 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 pensiero 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 pensa non vede l'output riepilogato.
• Poiché Anthropic cerca di migliorare la funzionalità di thinking, il comportamento del riepilogo è soggetto a modifiche.

Per vedere il ragionamento del modello, leggi i blocchi thinking anziché richiedere il ragionamento nel testo della risposta tramite prompt. Su Claude Fable 5.1 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 le indicazioni di gestione.

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 subito 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 di thinking 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)

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

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-4-8", "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 thinking si apre, arriva un singolo signature_delta e il blocco si chiude senza alcun evento thinking_delta. 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":"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 proprio testo come eventi thinking_delta prima del blocco tool_use che introduce. Una pausa di diversi secondi prima che il blocco di aggiornamento di avanzamento si apra è 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", tratta un blocco come aggiornamento di avanzamento non appena uno dei suoi eventi thinking_delta contiene testo non vuoto.

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

Thinking ed effort

Il parametro thinking controlla se Claude riflette 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 profondamente riflette. 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 con solo pensiero esteso che supporta effort, effort si combina 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 thinking attivo: abbassa prima effort. Riduce l'intera risposta, thinking incluso.
• Claude pensa troppo raramente o troppo superficialmente: alza effort, oppure vedi Regolare la frequenza con cui Claude pensa nella pagina sulla regolazione.
• Hai bisogno del thinking completamente disattivato: usa thinking: {type: "disabled"} sui modelli che lo consentono (vedi la tabella di configurazione per modello).
• Hai bisogno di un tetto rigido alla spesa: usa max_tokens. Effort è un'indicazione flessibile. max_tokens è un limite rigoroso.

Thinking con l'uso degli strumenti

Il thinking funziona insieme al tool use (uso degli strumenti), permettendo a Claude di ragionare sulla selezione degli strumenti e di elaborare i risultati degli strumenti. Si applicano due vincoli:

1. Limitazione di tool choice (modalità manuale): l'uso degli strumenti con pensiero esteso 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": "..."} produce un errore perché queste opzioni forzano l'uso degli strumenti, il che è incompatibile con il pensiero esteso manuale. Il thinking adattivo, anche sui modelli in cui il thinking è attivo per impostazione predefinita, supporta l'uso forzato degli strumenti, tranne su Claude Fable 5.1 e Claude Mythos 5.1 (vedi Prefill della risposta e uso forzato degli strumenti).
2. Preservare i blocchi thinking: quando restituisci i risultati degli strumenti, devi ripassare all'API i blocchi thinking del 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. L'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 thinking: non puoi attivare o disattivare il thinking 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 thinking attivo inizi con un blocco thinking. 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 thinking 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. Invece, disattiva 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 disattivare il thinking quando la cronologia della conversazione è incompatibile con il thinking attivo. Per confermare se il thinking era attivo, verifica la presenza di blocchi thinking nella risposta.

Cambia tra i turni, non al loro interno. 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 modalità di thinking invalida anche la "prompt caching" (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 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 thinking 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.

Thinking interleaved

L'"interleaved thinking" (thinking intercalato) permette a Claude di pensare tra le chiamate agli strumenti, ragionando su ogni risultato di uno strumento prima di agire su di esso. Con il thinking interleaved, 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 interleaved è automatico su ogni modello che supporta il thinking 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, Claude Opus 4.8 e Claude Opus 4.7, il ragionamento tra le chiamate agli strumenti appare sempre in blocchi thinking. Claude Haiku 4.5 non supporta il thinking interleaved. Sui modelli che usano il pensiero esteso manuale, l'interleaving richiede un header beta e cambia il modo in cui viene conteggiato il budget di thinking. Thinking interleaved in modalità manuale descrive le regole per modello e il comportamento degli header specifico per piattaforma.

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

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

Aggiornamenti di avanzamento tra le chiamate agli strumenti

Su Claude Fable 5.1, Claude Mythos 5.1 e Claude Fable 5, il modello può scrivere un "progress update" (aggiornamento di avanzamento) tra le chiamate agli strumenti. Un aggiornamento di avanzamento è una o due frasi su ciò che il modello ha appena trovato e su ciò che sta per fare, scritte per la persona che osserva l'agente anziché come ragionamento. Ciascuno viene restituito come 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 thinking interleaved: appaiono indipendentemente dal fatto che blocchi di ragionamento appaiano tra le chiamate agli strumenti, e una risposta può contenere entrambi.

Cosa contiene un blocco di aggiornamento di avanzamento dipende da display:

Usa display: "updates" per un'interfaccia 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 (su Amazon Bedrock, Google Cloud e Microsoft Foundry, passa il valore beta come descritto in Header beta). 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 rimane vuoto, come sarebbe 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:

• Ripassa i blocchi di aggiornamento di avanzamento invariati con il 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 uguale a un blocco di ragionamento vuoto e non richiede una gestione separata.
• Quando una risposta si interrompe su 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, ripassa 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 che un blocco di aggiornamento di avanzamento si apra. Vedi la traccia "updates" in Streaming del thinking.
• Questi modelli scrivono meno aggiornamenti di avanzamento con effort più alto e in lunghe catene di strumenti. Se la tua interfaccia dipende da essi, vedi Chiedere aggiornamenti di avanzamento rivolti all'utente.

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.1, Claude Mythos 5.1, 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 consentono cache hit durante l'uso degli strumenti, poiché vengono ripassati con i risultati degli strumenti e memorizzati nella cache in modo incrementale lungo il turno dell'assistente, con conseguente risparmio di token nei flussi di lavoro a più passaggi.
• Nessun impatto sull'intelligenza: preservare i blocchi thinking non ha effetti negativi 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 né header beta, e dovresti continuare a ripassare blocchi thinking completi e non modificati come descritto in Preservare i blocchi thinking. Per sovrascrivere il comportamento predefinito in entrambe le direzioni, usa la cancellazione dei blocchi thinking.

Cambiare modello a metà conversazione. Continua a ripassare i blocchi thinking invariati quando cambi modello, ad esempio dopo un fallback per rifiuto del classificatore. Un blocco thinking è leggibile solo dal modello che lo ha prodotto o da uno più recente, 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 thinking di ogni modello precedente e nessun modello precedente legge i loro, quindi passare a essi mantiene il ragionamento della conversazione e passare a un modello inferiore lo scarta (vedi Thinking preservato per l'elenco esatto e per come i blocchi scartati vengono fatturati e segnalati). Rimuovi tu stesso 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.

Thinking preservato

Claude preserva un blocco thinking, mantenendolo utilizzabile nei turni successivi, solo nelle condizioni in cui è stato creato. A partire da Claude Fable 5.1 e Claude Mythos 5.1, un blocco thinking o redacted_thinking viene preservato solo:

• Per il modello che lo ha prodotto, o uno più recente. Un modello precedente non può usare il blocco, e l'API lo scarta da quella richiesta. Vedi Solo per il modello che lo ha prodotto, o uno più recente.
• Nella conversazione che lo ha prodotto (solo Claude Fable 5.1). Se il prompt system, i tools o qualsiasi messaggio precedente cambia, il blocco non è più valido, e l'API rifiuta la richiesta o scarta il blocco. Vedi Solo nella conversazione che lo ha prodotto.

La signature del blocco registra entrambe le condizioni su entrambi i modelli. L'API la verifica ogni volta che il blocco ritorna in una richiesta successiva, inclusa una richiesta a un modello diverso; Claude Mythos 5.1 verifica solo la condizione del modello.

Ripassa i blocchi invariati. Invia ogni turno dell'assistente esattamente come lo hai ricevuto, blocchi thinking inclusi, e lascia che l'API decida quali blocchi il modello può usare.

Solo per il modello che lo ha prodotto, o uno più recente

Questa condizione è unidirezionale: Claude Fable 5.1 e Claude Mythos 5.1 leggono i blocchi thinking dei modelli precedenti, e nessun modello precedente legge i loro.

• Una conversazione che passa a Claude Fable 5.1 o Claude Mythos 5.1 mantiene il suo ragionamento. I blocchi thinking del modello precedente rimangono leggibili, quindi il modello pensa come di consueto dal primo turno dopo il cambio.
• Una conversazione che passa da essi a qualsiasi modello precedente lo perde. Il modello precedente non può leggere i loro blocchi, l'API li scarta per quella richiesta e il modello precedente ragiona di nuovo a partire dai messaggi visibili. Se la conversazione torna successivamente a Claude Fable 5.1 con la stessa cronologia, i suoi blocchi sono di nuovo leggibili.

Nel dettaglio, Claude Fable 5.1 e Claude Mythos 5.1 leggono i blocchi thinking prodotti l'uno dall'altro, da Claude Opus 5, Claude Fable 5 e Claude Mythos 5, e da Claude Opus 4.8 e modelli Opus precedenti, dai modelli Claude Sonnet e da Claude Haiku 4.5. Nessun modello diverso da questi due può leggere un blocco prodotto da Claude Fable 5.1 o Claude Mythos 5.1.

Un blocco che il modello ricevente non può leggere viene scartato. L'API lo rimuove prima che il prompt raggiunga il modello. Non conta ai fini di input_tokens e non viene fatturato. Quando esegui un fallback da Claude Fable 5.1 a un modello più vecchio a metà conversazione, ad esempio dopo un fallback per rifiuto del classificatore, il modello più vecchio ragiona di nuovo a partire dalla conversazione visibile. Con l'header beta dei controlli lo scarto viene segnalato in input_transformations come model_binding_mismatch. Senza di esso lo scarto è silenzioso. Un fallback lato server scarta i blocchi illeggibili allo stesso modo.

Solo nella conversazione che lo ha prodotto

Un blocco di pensiero di Claude Fable 5.1 viene preservato solo finché il prefisso della conversazione da cui è stato prodotto rimane invariato. La sua signature copre il prompt system, i tools e i messaggi che hanno preceduto il blocco. Claude Mythos 5.1 registra la stessa signature ma non esegue questo controllo.

Questo controllo viene applicato per i nuovi account creati a partire dal 31 agosto 2026. Per gli account creati in precedenza, l'API registra la condizione nella signature ma non interviene in caso di mancata corrispondenza, a meno che la richiesta non imposti thinking.block_binding.prefix_mismatch_behavior, che attiva l'applicazione del controllo. Anthropic prevede di applicare questa condizione a ogni organizzazione sui modelli futuri. Se il tuo account è stato creato in precedenza, rendi la tua applicazione compatibile ora: gli stessi pattern append-only mantengono calda la cache dei prompt, e puoi testare il controllo inviando prefix_mismatch_behavior: "error". Se distribuisci uno strumento o un framework che le persone eseguono con la propria chiave API, testa in questo modo: i tuoi utenti con account nuovi sono soggetti al controllo prima di te. Pensiero preservato contiene la checklist di integrazione: come capire se il tuo codice modifica la cronologia e la funzionalità API che sostituisce ciascun tipo di modifica.

Dove il controllo è applicato, una richiesta che ripropone un blocco rispetto a un prefisso modificato viene rifiutata con un errore 400 invalid_request_error:

messages.5.content.0: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block". That setting requires the `thinking-binding-controls-2026-08-01` value in the `anthropic-beta` header.

L'ultima frase appare solo quando la richiesta non ha inviato l'header beta. Il messaggio può terminare con un'ulteriore frase che indica il primo messaggio modificato. Riprovare con lo stesso corpo della richiesta fallisce allo stesso modo. Per continuare invece senza il ragionamento invalidato, invia l'header beta thinking-binding-controls-2026-08-01 e imposta prefix_mismatch_behavior su "drop_block". L'API scarta quindi il blocco non valido e ogni blocco di pensiero successivo nella conversazione, e segnala ciascuno in input_transformations come prefix_binding_mismatch. L'endpoint di conteggio dei token esegue lo stesso controllo e restituisce lo stesso 400.

Cosa invalida i blocchi di pensiero successivi:

• Modificare, riordinare o rimuovere un messaggio precedente, incluso rimuovere un promemoria per turno che avevi inserito in un turno utente precedente.
• Cambiare il contenuto del prompt system di primo livello, oppure aggiungere, rimuovere o modificare uno strumento nell'array tools, tra una richiesta e l'altra.
• Compattazione o troncamento lato client che mantiene i turni recenti dell'assistente alla lettera, pensiero incluso, riscrivendo i turni precedenti.
• Un URL di immagine o documento in un turno precedente che serve byte diversi in una richiesta successiva. Il controllo copre i byte, non la stringa dell'URL, quindi un URL firmato a rotazione per lo stesso file va bene. Per i contenuti a cui fai riferimento su più turni, caricali una volta con la Files API e invia il file_id, oppure invia base64.

Cosa non li invalida:

• Rimuovere una sequenza iniziale di blocchi di pensiero, dal più vecchio: il primo blocco di pensiero nella conversazione (o il primo dopo il blocco di compattazione più recente), poi il successivo, e così via. Rimuovere un blocco di pensiero da qualsiasi altra posizione invalida ogni blocco di pensiero successivo, in quel turno e in ogni turno seguente.
• Cambiare output_config.effort, max_tokens o altre impostazioni di campionamento tra le richieste.
• I marcatori cache_control, ovunque li posizioni o li sposti.
• La compattazione lato server e la modifica del contesto: non contano come modifiche, perché il controllo confronta la conversazione così come l'hai inviata, non la copia modificata dal server. Dopo una compattazione, il prefisso controllato inizia dal blocco di compattazione.

Pattern che mantengono validi i blocchi di pensiero:

• Solo aggiunte in coda. Aggiungi i nuovi messaggi alla fine di messages e lascia i turni precedenti invariati byte per byte.
• Usa i messaggi di sistema a metà conversazione e le modifiche degli strumenti a metà conversazione per aggiungere istruzioni o cambiare la disponibilità degli strumenti in corso d'opera, invece di modificare il campo system di primo livello o l'array tools. Per un promemoria che deve applicarsi a un solo turno, invialo come messaggio di sistema con ambito di turno e lascialo nella cronologia invece di eliminarlo in seguito. Questo preserva anche la cache dei prompt.
• Usa la gestione del contesto lato server invece di tagliare la cronologia da solo.
• Se una richiesta viene rifiutata per una mancata corrispondenza del prefisso e non puoi riparare la cronologia, reinviala con l'header beta e prefix_mismatch_behavior: "drop_block", oppure rimuovi ogni blocco thinking e redacted_thinking dalla cronologia e riprova una volta.

Quando il pensiero precedente viene scartato, il modello risponde a quel turno senza quei blocchi. Un client che invalida ripetutamente la propria cronologia riavvia ogni volta la cache dei prompt, il che aumenta i costi.

Compattazione lato client. Questo controllo non esclude la compattazione sul client. La regola è più ristretta: non mantenere un blocco di pensiero dietro un prefisso che hai riscritto. La compattazione lato server è il modo più semplice per rispettarla. Se compatti sul client, usa una di queste forme:

• Compattazione semplice (consigliata): riassumi la conversazione in un unico messaggio e inizia la richiesta successiva con quel riassunto più il nuovo turno utente, senza riproporre turni precedenti né blocchi di pensiero precedenti. Non rimane alcun pensiero precedente, quindi nulla fallisce, e il modello pensa da capo sulla conversazione compattata. I modelli Claude sono addestrati su attività a lungo orizzonte con questo schema, che offre prestazioni paragonabili a schemi più elaborati per la maggior parte dei carichi di lavoro. Reimposta la cache dei prompt, come qualsiasi compattazione.
• Compattazione con mantenimento della coda: riassumi i turni più vecchi e mantieni alla lettera i turni più recenti. I blocchi di pensiero dei turni mantenuti sono stati prodotti rispetto alla cronologia completa e falliscono dietro il riassunto. Rimuovi thinking e redacted_thinking da ogni turno che porti avanti (il loro testo e le chiamate agli strumenti possono restare), oppure imposta prefix_mismatch_behavior: "drop_block" e lascia che l'API li scarti.
• Compattazione in background: costruisci il riassunto fuori dal percorso critico e sostituiscilo mentre la conversazione continua. Ogni turno prodotto nel frattempo ha un pensiero che precede la sostituzione. Invia "drop_block" su ogni richiesta che contiene ancora blocchi di pensiero prodotti prima della sostituzione (oppure rimuovi tu stesso quei blocchi; input_transformations nella prima risposta dopo la sostituzione elenca esattamente quali), oppure compatta in modo sincrono.

Tagliare singoli turni dal mezzo della trascrizione invalida ogni blocco di pensiero successivo, e nessuna forma lato client lo evita. Usa un messaggio di sistema a metà conversazione per la modifica di istruzioni che stavi apportando, oppure la modifica del contesto lato server per la rimozione selettiva.

Controlli per i blocchi che non vengono preservati (beta)

Invia l'header beta thinking-binding-controls-2026-08-01 per ottenere due cose: un array input_transformations su ogni risposta che elenca gli eventuali blocchi di pensiero scartati dall'API, e un oggetto block_binding nella configurazione del pensiero con un campo.

block_binding è accettato insieme a thinking.type: "adaptive" e thinking.type: "enabled". Inviarlo senza l'header beta restituisce un errore 400. I modelli che non eseguono il controllo della conversazione accettano l'oggetto e segnalano solo gli scarti del controllo del modello, quindi un unico corpo di richiesta funziona su tutti i modelli. Su Amazon Bedrock e Google Cloud, passa i nomi delle beta come descritto in Header beta.

La richiesta seguente sceglie di scartare invece di rifiutare. In un primo turno non c'è nulla da riproporre, quindi input_transformations torna vuoto:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    thinking={
        "type": "adaptive",
        "block_binding": {"prefix_mismatch_behavior": "drop_block"},
    },
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
    betas=["thinking-binding-controls-2026-08-01"],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

print(f"Input transformations: {len(response.input_transformations or [])}")

The greatest common divisor of 1071 and 462 is 21.
Input transformations: 0

I blocchi scartati vengono segnalati in input_transformations. Con l'header beta, ogni risposta da un modello con capacità di pensiero contiene questo array di primo livello. È vuoto quando non è stato scartato nulla e non è mai null. Ogni voce indica la posizione di un blocco scartato e il controllo che non ha superato:

{
  "input_transformations": [
    {
      "type": "thinking_dropped",
      "path": "messages.1.content.0",
      "reason": "model_binding_mismatch"
    }
  ]
}

Il campo reason è model_binding_mismatch o prefix_binding_mismatch. Ignora le voci il cui type o reason non riconosci, perché controlli successivi aggiungono valori. Durante lo streaming, input_transformations arriva sull'oggetto message nell'evento message_start. Dopo un fallback lato server a metà stream, l'evento finale message_delta contiene nuovamente l'array con le voci del modello che ha servito la richiesta. Senza l'header beta il campo è assente.

Una signature manomessa o non decifrabile è un errore diverso: restituisce sempre un 400 (Invalid `signature` in `thinking` block, senza clausola di motivazione) e prefix_mismatch_behavior non si applica. In un batch di messaggi, un elemento il cui blocco non supera il controllo della conversazione con "error" si risolve come errored.

Pensiero e cache dei prompt

La cache dei prompt ("prompt caching") interagisce con il pensiero in alcuni modi specifici. Le regole seguenti 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. 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 degli strumenti e del prompt di sistema possono mancare, a seconda di dove il modello rende la configurazione. Considera qualsiasi modifica al pensiero o all'effort di primo livello come un riavvio della cache. Sui modelli che supportano l'effort per messaggio, una modifica dell'effort trasportata in un messaggio role: "system" all'interno di messages lascia intatto il prefisso in cache. 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 pensiero che l'API scarta in base a una delle due condizioni del pensiero preservato modifica il prefisso in cache dalla posizione di quel blocco in avanti. I blocchi ripassati invariati mantengono intatta la cache. Una dimostrazione pratica con output di utilizzo si trova nella pagina Guidare il pensiero.

I blocchi di pensiero vengono messi in cache con i risultati degli strumenti. Durante un ciclo di uso degli strumenti, la cache interviene quando effettui una richiesta successiva che include risultati degli strumenti. A quel punto la cronologia precedente della conversazione, inclusi i suoi blocchi di pensiero, può essere messa in cache, e quei blocchi di pensiero in 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 per quello interleaved. Il compromesso: i blocchi di pensiero che non rivedi mai più nelle risposte contribuiscono comunque all'utilizzo di token di input quando vengono letti dalla cache.

Se i blocchi precedenti siano nel contesto dipende dal modello. Il comportamento predefinito di preservazione governa questo aspetto. Sui modelli che mantengono tutto, i blocchi di pensiero dei turni precedenti restano in 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 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 in cache. Se il pensiero viene disabilitato a metà turno e passi contenuto di pensiero nel turno corrente di uso degli strumenti, il contenuto di pensiero viene rimosso e il pensiero rimane disabilitato per quella richiesta (vedi degradazione graduale). Il pensiero interleaved amplifica gli effetti di invalidazione della cache, perché i blocchi di pensiero possono comparire tra più chiamate agli strumenti.

Pensiero e finestra di contesto

max_tokens, che include tutto il pensiero 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 "context window" (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.

Il modo in cui 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 comportamento predefinito di preservazione. Sui modelli che mantengono tutti i turni precedenti, i blocchi di pensiero 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 mantengono solo l'ultimo turno, l'API rimuove automaticamente i blocchi di pensiero più vecchi quando li ripassi, 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 della conversazione, perché lo è. Le lunghe sessioni agentiche 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 solo-ultimo-turno (con rimozione). Il primo mostra una conversazione multi-turno: il blocco di pensiero di ogni turno viene generato nell'output ma non viene portato nell'input dei turni successivi.

Il secondo mostra lo stesso regime con l'uso degli strumenti: il pensiero resta nel contesto insieme al suo risultato di 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 pensiero.

Crittografia del pensiero

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

Tieni presente quanto segue quando lavori con le signature:

• È strettamente necessario rimandare i blocchi di pensiero solo quando usi gli strumenti con il pensiero. Altrimenti puoi omettere i blocchi di pensiero dei turni precedenti. Se li ripassi, il fatto che l'API li mantenga o li rimuova dipende dal modello (vedi Preservazione dei blocchi di pensiero per modello). Usa la modifica del contesto per configurare questo comportamento.
• Quando rimandi i blocchi di pensiero, 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 piattaforme (la Claude API, Amazon Bedrock e Google Cloud). I valori generati su una piattaforma funzionano su un'altra.

Blocchi di pensiero 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 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, 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, 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 usato. 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 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. Le eccezioni sono Claude Fable 5.1 e Claude Mythos 5.1, che rifiutano l'uso forzato degli strumenti su ogni richiesta con un errore 400. Su quei modelli, usa invece tool_choice: {"type": "auto"} con l'uso rigoroso degli strumenti o gli output strutturati. Vedi Pensiero 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

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. Vedi Streaming dei messaggi. Aspettati tempi di risposta più lunghi quando il pensiero è attivo, perché generare 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.

Prossimi passi