Pensiero esteso

Il "extended thinking" (pensiero esteso) fornisce a Claude capacità di ragionamento avanzate per compiti complessi, offrendo al contempo diversi livelli di trasparenza nel suo processo di pensiero passo dopo passo prima di fornire la risposta finale.



Modelli supportati

Il pensiero esteso è disponibile su tutti i modelli Claude attuali. Il modo in cui lo abiliti dipende dal modello:

Con il pensiero adattivo, il modello decide quando e quanto pensare per ogni richiesta. Su Claude Mythos Preview, Claude Fable 5 e Claude Mythos 5, thinking: {type: "disabled"} non è supportato. Per le differenze di comportamento per modello (output del pensiero, pensiero intercalato e conservazione dei blocchi), consulta Differenze nel pensiero tra le versioni dei modelli.



Come funziona il pensiero esteso

Quando il pensiero esteso è attivato, Claude crea blocchi di contenuto thinking in cui produce il suo ragionamento interno. Claude incorpora le intuizioni derivanti da questo ragionamento prima di elaborare una risposta finale.

La risposta dell'API include blocchi di contenuto thinking, seguiti da blocchi di contenuto text.

Ecco un esempio del formato di risposta predefinito:

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me analyze this step by step...",
      "signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
    },
    {
      "type": "text",
      "text": "Based on my analysis..."
    }
  ]
}

Per ulteriori informazioni sul formato di risposta del pensiero esteso, consulta il Riferimento dell'API Messages.



Come usare il pensiero esteso

Ecco un esempio di utilizzo del pensiero esteso nell'API Messages:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[
        {
            "role": "user",
            "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
        }
    ],
)

# La risposta contiene blocchi di pensiero riassunti e blocchi di testo
for block in response.content:
    match block.type:
        case "thinking":
            print(f"\nThinking summary: {block.thinking}")
        case "text":
            print(f"\nResponse: {block.text}")

Per attivare il pensiero esteso, aggiungi un oggetto thinking con type impostato su enabled e un valore budget_tokens. Sui modelli in cui il pensiero esteso manuale è deprecato o non supportato (consulta Modelli supportati), usa invece type: "adaptive" come descritto in Pensiero adattivo.

Il parametro budget_tokens imposta il numero massimo di token che Claude può utilizzare per il suo processo di ragionamento interno. Questo limite si applica ai token di pensiero completi, non all'output riassunto. Budget più ampi possono migliorare la qualità della risposta consentendo un'analisi più approfondita per problemi complessi, anche se Claude potrebbe non utilizzare l'intero budget allocato, specialmente per intervalli superiori a 32k.

budget_tokens deve essere impostato su un valore inferiore a max_tokens. Tuttavia, quando usi il pensiero intercalato con strumenti, puoi superare questo limite poiché il limite di token diventa l'intera finestra di contesto. Poiché budget_tokens deve essere inferiore a max_tokens, il pensiero esteso non può essere combinato con max_tokens: 0 (pre-riscaldamento della cache).



Controllare la visualizzazione del pensiero

Il campo display nella configurazione del thinking controlla come il contenuto del thinking viene restituito nelle risposte dell'API. Accetta due valori:

• "summarized": I blocchi di thinking contengono testo di thinking riassunto. Consulta Thinking riassunto per i dettagli. Questa è l'impostazione predefinita su Claude Opus 4.6, Claude Sonnet 4.6 e sui modelli Claude 4 precedenti.
• "omitted": I blocchi di thinking vengono restituiti con un campo thinking vuoto. Il campo signature contiene comunque il thinking completo crittografato per la continuità multi-turno (consulta Crittografia del thinking). Questa è l'impostazione predefinita su Claude Fable 5, Claude Mythos 5, Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7 e Claude Mythos Preview.

Impostare display: "omitted" è utile quando la tua applicazione non mostra il contenuto del thinking agli utenti. Il vantaggio principale è un time-to-first-text-token più rapido durante lo streaming: il server salta completamente lo streaming dei token di thinking e fornisce solo la signature, quindi la risposta testuale finale inizia lo streaming prima.

Ecco alcune considerazioni importanti per il thinking omesso:

• Ti vengono comunque addebitati i token di thinking completi. L'omissione riduce la latenza, non il costo.
• Se passi i blocchi di thinking nelle conversazioni multi-turno, passali senza modifiche. Il server decrittografa la signature per ricostruire il thinking originale per la costruzione del prompt (consulta Preservare i blocchi di thinking). Qualsiasi testo inserito nel campo thinking di un blocco omesso restituito al server viene ignorato.
• display non è valido con thinking.type: "disabled" (non c'è nulla da visualizzare).
• Quando si utilizza thinking.type: "adaptive" e il modello salta il thinking per una richiesta semplice, non viene prodotto alcun blocco di thinking indipendentemente da display.

Le pipeline automatizzate che non mostrano mai il contenuto del pensiero agli utenti finali possono evitare l'overhead di ricevere i token di pensiero via rete. Le applicazioni sensibili alla latenza ottengono la stessa qualità di ragionamento senza attendere che il testo del pensiero venga trasmesso in streaming prima che inizi la risposta finale.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000,
        "display": "omitted",
    },
    messages=[
        {"role": "user", "content": "What is 27 * 453?"},
    ],
)

for block in response.content:
    if block.type == "thinking":
        if block.thinking:
            print(f"Thinking: {block.thinking}")
        else:
            print("Thinking: [omitted]")
    elif block.type == "text":
        print(f"Response: {block.text}")

Quando display: "omitted" è impostato, la risposta contiene blocchi thinking con un campo thinking vuoto:

{
  "content": [
    {
      "type": "thinking",
      "thinking": "",
      "signature": "EosnCkYICxIMMb3LzNrMu..."
    },
    {
      "type": "text",
      "text": "The answer is 12,231."
    }
  ]
}

Quando si usa lo streaming con display: "omitted", non vengono emessi eventi thinking_delta; consulta Streaming del pensiero per la sequenza degli eventi.



Pensiero riassunto

Con il pensiero esteso abilitato, l'API Messages per i modelli Claude 4 restituisce un riepilogo del processo di pensiero completo di Claude. Il pensiero riepilogato fornisce tutti i vantaggi di intelligenza del pensiero esteso, prevenendo al contempo usi impropri. Questo è il comportamento predefinito sui modelli Claude 4 quando il campo display nella configurazione del pensiero non è impostato o è impostato su "summarized". Su Claude Fable 5, Claude Mythos 5, Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7 e Claude Mythos Preview, display ha come valore predefinito "omitted", quindi devi impostare esplicitamente display: "summarized" per ricevere il pensiero riepilogato.

Ecco alcune considerazioni importanti per il pensiero riepilogato:

• Ti vengono addebitati i token di pensiero completi generati dalla richiesta originale, non i token del riepilogo.
• Il conteggio dei token di output fatturati non corrisponderà al conteggio dei token che vedi nella risposta.
• Sui modelli Claude 4, le prime righe dell'output di pensiero 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 di pensiero non mostrano questo preambolo dettagliato.
• Poiché Anthropic cerca di migliorare la funzionalità di pensiero esteso, il comportamento di riepilogo è soggetto a modifiche.
• Il riepilogo preserva le idee chiave del processo di pensiero di Claude con una latenza aggiuntiva minima, consentendo un'esperienza utente in streaming.
• Il riepilogo viene elaborato da un modello diverso da quello che specifichi nelle tue richieste. Il modello di pensiero non vede l'output riepilogato.



Streaming del pensiero

Puoi trasmettere in streaming le risposte del pensiero esteso utilizzando i server-sent events (SSE).

Quando lo streaming è abilitato per il pensiero esteso, ricevi il contenuto del pensiero tramite eventi thinking_delta.

Quando display: "omitted" è impostato, non vengono emessi eventi thinking_delta. Consulta Controllare la visualizzazione del pensiero.

Per ulteriore documentazione sullo streaming tramite l'API Messages, consulta Streaming dei messaggi.

Ecco come gestire lo streaming con il pensiero:

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
) as stream:
    thinking_started = False
    response_started = False

    for event in stream:
        if event.type == "content_block_start":
            print(f"\nStarting {event.content_block.type} block...")
            # Reimposta i flag per ogni nuovo blocco
            thinking_started = False
            response_started = False
        elif event.type == "content_block_delta":
            if event.delta.type == "thinking_delta":
                if not thinking_started:
                    print("Thinking: ", end="", flush=True)
                    thinking_started = True
                print(event.delta.thinking, end="", flush=True)
            elif event.delta.type == "text_delta":
                if not response_started:
                    print("Response: ", end="", flush=True)
                    response_started = True
                print(event.delta.text, end="", flush=True)
        elif event.type == "content_block_stop":
            print("\nBlock complete.")

Esempio di output in streaming:

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-sonnet-4-6", "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": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}

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 display: "omitted" è impostato, 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":""}}



Pensiero esteso con l'uso degli strumenti

Il pensiero esteso può essere utilizzato insieme all'uso degli strumenti, consentendo a Claude di ragionare sulla selezione degli strumenti e sull'elaborazione dei risultati.

Quando usi il pensiero esteso con l'uso degli strumenti, tieni presente le seguenti limitazioni:

1. Limitazione sulla scelta dello strumento: L'uso degli strumenti con il pensiero supporta solo tool_choice: {"type": "auto"} (il valore predefinito) o tool_choice: {"type": "none"}. L'utilizzo di tool_choice: {"type": "any"} o tool_choice: {"type": "tool", "name": "..."} genererà un errore perché queste opzioni forzano l'uso degli strumenti, il che è incompatibile con il pensiero esteso.

2. Conservazione dei blocchi di pensiero: Durante l'uso degli strumenti, devi passare i blocchi thinking all'API per l'ultimo messaggio dell'assistente. Includi il blocco completo e non modificato nell'API per mantenere la continuità del ragionamento.



Alternare le modalità di pensiero nelle conversazioni

Non puoi alternare il pensiero nel mezzo di un turno dell'assistente, incluso durante i cicli di uso degli strumenti. L'intero turno dell'assistente dovrebbe operare in una singola modalità di pensiero:

• Se il pensiero è abilitato, il turno finale dell'assistente dovrebbe iniziare con un blocco di pensiero.
• Se il pensiero è disabilitato, il turno finale dell'assistente non dovrebbe contenere alcun blocco di pensiero

Dal punto di vista del modello, i cicli di uso degli strumenti fanno parte del turno dell'assistente. Un turno dell'assistente non si completa finché Claude non termina la sua risposta completa, che può includere più chiamate agli strumenti e relativi risultati.

Ad esempio, questa sequenza fa tutta parte di 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"]

Anche se ci sono più messaggi API, il ciclo di uso degli strumenti è concettualmente parte di una risposta continua dell'assistente.



Degradazione graduale del pensiero

Quando si verifica un conflitto di pensiero a metà turno (come attivare o disattivare il pensiero durante un ciclo di uso degli strumenti), l'API disabilita automaticamente il pensiero per quella richiesta. Per preservare la qualità del modello e rimanere nella distribuzione, l'API può:

• Rimuovere i blocchi di pensiero dalla conversazione quando creerebbero una struttura di turno non valida
• Disabilitare il pensiero per la richiesta corrente quando la cronologia della conversazione è incompatibile con il pensiero abilitato

Ciò significa che tentare di alternare il pensiero a metà turno non causerà un errore, ma il pensiero verrà disabilitato silenziosamente per quella richiesta. Per confermare se il pensiero era attivo, verifica la presenza di blocchi thinking nella risposta.



Indicazioni pratiche

Best practice: Pianifica la tua strategia di pensiero all'inizio di ogni turno piuttosto che tentare di alternarla a metà turno.

Esempio: Alternare il pensiero dopo aver completato un turno

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)

Completando il turno dell'assistente prima di alternare il pensiero, ti assicuri che il pensiero sia effettivamente abilitato per la nuova richiesta.



Conservazione dei blocchi di pensiero

Durante l'uso degli strumenti, devi passare i blocchi thinking all'API e devi includere il blocco completo e non modificato nell'API. Questo è fondamentale per mantenere il flusso di ragionamento del modello e l'integrità della conversazione.

Quando Claude invoca strumenti, sta mettendo in pausa la costruzione di una risposta in attesa di informazioni esterne. Quando vengono restituiti i risultati degli strumenti, Claude continua a costruire quella risposta esistente. Ciò rende necessaria la conservazione dei blocchi di pensiero durante l'uso degli strumenti, per un paio di motivi:

1. Continuità del ragionamento: I blocchi di pensiero catturano il ragionamento passo dopo passo di Claude che ha portato alle richieste di strumenti. Quando invii i risultati degli strumenti, includere il pensiero originale garantisce che Claude possa continuare il suo ragionamento da dove si era interrotto.

2. Mantenimento del contesto: Anche se i risultati degli strumenti appaiono come messaggi utente nella struttura dell'API, fanno parte di un flusso di ragionamento continuo. La conservazione dei blocchi di pensiero mantiene questo flusso concettuale attraverso più chiamate API. Per ulteriori informazioni sulla gestione del contesto, consulta la guida sulle finestre di contesto.

Importante: Quando fornisci blocchi thinking, l'intera sequenza di blocchi thinking consecutivi deve corrispondere agli output generati dal modello durante la richiesta originale; non puoi riorganizzare o modificare la sequenza di questi blocchi.



Pensiero intercalato

Il pensiero esteso con l'uso degli strumenti nei modelli Claude 4 supporta il "interleaved thinking" (pensiero intercalato), che consente a Claude di pensare tra le chiamate agli strumenti e di effettuare ragionamenti più sofisticati dopo aver ricevuto i risultati degli strumenti.

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

Il modo in cui abiliti il pensiero intercalato dipende dal modello:

Per modelli Claude 4 precedenti si intendono Claude Sonnet 4.5, Claude Opus 4.1 (deprecato), Claude Opus 4 (ritirato, tranne su Google Cloud) e Claude Sonnet 4 (ritirato, tranne su Bedrock e Google Cloud).

Ecco alcune considerazioni importanti per il pensiero intercalato:

• Con il pensiero intercalato, budget_tokens può superare il parametro max_tokens, poiché rappresenta il budget totale su tutti i blocchi di pensiero all'interno di un turno dell'assistente.
• Il pensiero intercalato è supportato solo per gli strumenti utilizzati tramite l'API Messages.
• L'API Claude e Claude Platform su AWS accettano interleaved-thinking-2025-05-14 nelle richieste a qualsiasi modello senza restituire un errore. Sui modelli che non supportano il pensiero intercalato, l'header viene ignorato. Su Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 e Claude Sonnet 5, è deprecato e viene ignorato in modo sicuro. Su Claude Mythos Preview, non è necessario e viene ignorato in modo sicuro.
• Sulle piattaforme gestite da partner (ad esempio, Amazon Bedrock e Google Cloud), se passi interleaved-thinking-2025-05-14 a qualsiasi modello diverso da Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5, Claude Opus 4.6, Claude Sonnet 4.6, Claude Opus 4.5, Claude Opus 4.1 (deprecato), Opus 4 (ritirato, tranne su Google Cloud), Sonnet 4.5 o Sonnet 4 (ritirato, tranne su Bedrock e Google Cloud), la tua richiesta fallirà.



Pensiero esteso con la cache dei prompt

La cache dei prompt con il pensiero presenta diverse considerazioni importanti:

Rimozione dei blocchi di pensiero dal contesto

• Sui modelli Opus/Sonnet precedenti e su tutti i modelli Haiku, i blocchi di pensiero dei turni precedenti vengono rimossi dal contesto, il che può influire sui breakpoint della cache. Su Opus 4.5+ e Sonnet 4.6+, vengono mantenuti per impostazione predefinita.
• Quando si continuano conversazioni con l'uso degli strumenti, i blocchi di pensiero vengono memorizzati nella cache e contano come token di input quando letti dalla cache
• Questo crea un compromesso: anche se i blocchi di pensiero non consumano visivamente spazio nella finestra di contesto, contano comunque nell'utilizzo dei token di input quando memorizzati nella cache
• Se il pensiero viene disabilitato e passi contenuto di pensiero nel turno corrente di uso degli strumenti, il contenuto di pensiero verrà rimosso e il pensiero rimarrà disabilitato per quella richiesta

Pattern di invalidazione della cache

• Le modifiche ai parametri di pensiero (abilitato/disabilitato o allocazione del budget) invalidano i breakpoint della cache dei messaggi
• Il pensiero intercalato amplifica l'invalidazione della cache, poiché i blocchi di pensiero possono verificarsi tra più chiamate agli strumenti
• I prompt di sistema e gli strumenti rimangono nella cache nonostante le modifiche ai parametri di pensiero o la rimozione dei blocchi



Comprendere il comportamento di caching dei blocchi di pensiero

Quando si usa il pensiero esteso con l'uso degli strumenti, i blocchi di pensiero mostrano un comportamento di caching specifico che influisce sul conteggio dei token:

Come funziona:

1. Il caching avviene solo quando effettui una richiesta successiva che include risultati degli strumenti
2. Quando viene effettuata la richiesta successiva, la cronologia della conversazione precedente (inclusi i blocchi di pensiero) può essere memorizzata nella cache
3. Questi blocchi di pensiero memorizzati nella cache contano come token di input nelle tue metriche di utilizzo quando letti dalla cache
4. Quando viene incluso un blocco utente non-tool-result: su Opus 4.5+ e Sonnet 4.6+, i blocchi di pensiero precedenti vengono mantenuti; sui modelli Opus/Sonnet precedenti e su tutti i modelli Haiku, tutti i blocchi di pensiero precedenti vengono ignorati e rimossi dal contesto

Esempio dettagliato del flusso:

Richiesta 1:

User: "What's the weather in Paris?"

Risposta 1:

[thinking_block_1] + [tool_use block 1]

Richiesta 2:

User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]

Risposta 2:

[thinking_block_2] + [text block 2]

La Richiesta 2 scrive una cache del contenuto della richiesta (non della risposta). La cache include il messaggio utente originale, il primo blocco di pensiero, il blocco tool use e il risultato dello strumento.

Richiesta 3:

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]

Per Opus 4.5+ e Sonnet 4.6+, tutti i blocchi di pensiero precedenti vengono mantenuti per impostazione predefinita. Per i modelli Opus/Sonnet precedenti e tutti i modelli Haiku, poiché è stato incluso un blocco utente non-tool-result, tutti i blocchi di pensiero precedenti vengono ignorati e rimossi dal contesto. Questa richiesta verrà elaborata come:

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]

Punti chiave:

• Questo comportamento di caching avviene automaticamente, anche senza marcatori cache_control espliciti
• Questo comportamento è coerente sia che si usi il pensiero regolare sia il pensiero intercalato



Max tokens e dimensione della finestra di contesto con il pensiero esteso

max_tokens (che include il tuo budget di pensiero quando il pensiero è abilitato) viene applicato come limite rigido. Sui modelli Claude 4.5 e successivi, se i token di input più max_tokens superano la dimensione della finestra di contesto, l'API accetta la richiesta. Se la generazione raggiunge poi il limite della finestra di contesto, si interrompe con stop_reason: "model_context_window_exceeded". Sui modelli precedenti, l'API restituisce invece un errore di validazione. Consulta Gestione dei motivi di interruzione.



La finestra di contesto con il pensiero esteso

Quando calcoli l'utilizzo della finestra di contesto con il pensiero abilitato, ci sono alcune considerazioni da tenere presenti:

• Su Opus 4.5+ e Sonnet 4.6+, i blocchi di pensiero dei turni precedenti vengono mantenuti e contano nella tua finestra di contesto; sui modelli Opus/Sonnet precedenti e su tutti i modelli Haiku, vengono rimossi e non conteggiati
• Il pensiero del turno corrente conta nel tuo limite max_tokens per quel turno

Il diagramma seguente illustra la gestione specializzata dei token quando il pensiero esteso è abilitato:

La finestra di contesto effettiva viene calcolata come:

context window =
  (current input tokens - previous thinking tokens) +
  (thinking tokens + encrypted thinking tokens + text output tokens)

Usa l'API di conteggio dei token per ottenere conteggi di token accurati per il tuo caso d'uso specifico, specialmente quando lavori con conversazioni multi-turno che includono il pensiero.



La finestra di contesto con il pensiero esteso e l'uso degli strumenti

Quando si usa il pensiero esteso con l'uso degli strumenti, i blocchi di pensiero devono essere esplicitamente conservati e restituiti con i risultati degli strumenti.

Il calcolo della finestra di contesto effettiva per il pensiero esteso con l'uso degli strumenti diventa:

context window =
  (current input tokens + previous thinking tokens + tool use tokens) +
  (thinking tokens + encrypted thinking tokens + text output tokens)

Il diagramma seguente illustra la gestione dei token per il pensiero esteso con l'uso degli strumenti:



Gestione dei token con il pensiero esteso

Dato il comportamento della finestra di contesto e di max_tokens con il pensiero esteso, potresti dover:

• Monitorare e gestire più attivamente l'utilizzo dei token
• Regolare i valori di max_tokens man mano che la lunghezza del tuo prompt cambia
• Potenzialmente usare gli endpoint di conteggio dei token più frequentemente
• Tenere presente che i blocchi di pensiero precedenti non si accumulano nella tua finestra di contesto



Crittografia del pensiero

Il contenuto completo del pensiero è crittografato e restituito nel campo signature. Questo campo viene utilizzato per verificare che i blocchi di pensiero siano stati generati da Claude quando vengono ritrasmessi all'API.

Ecco alcune considerazioni importanti sulla crittografia del pensiero:

• Durante lo streaming delle risposte, la firma viene aggiunta tramite un 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 rispetto ai modelli precedenti.
• Il campo signature è un campo opaco e non deve essere interpretato o analizzato.
• I valori di signature sono compatibili tra le piattaforme (API di Claude, Amazon Bedrock e Google Cloud). I valori generati su una piattaforma saranno compatibili con un'altra.



Blocchi di pensiero oscurati

Oltre ai normali blocchi thinking, l'API può restituire blocchi redacted_thinking. Un blocco redacted_thinking contiene contenuto di pensiero crittografato in un campo data, senza riepilogo leggibile:

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

Il campo data è opaco e crittografato. Come il campo signature sui normali blocchi di pensiero, dovresti passare i blocchi redacted_thinking all'API senza modifiche quando continui una conversazione multi-turno con strumenti.



Differenze nel pensiero tra le versioni dei modelli

L'API Messages gestisce il pensiero in modo diverso tra le versioni dei modelli Claude. La tabella seguente fornisce un confronto sintetico:

¹ Imposta display: "summarized" per ricevere il pensiero riassunto. Su Claude Fable 5, Claude Mythos 5 e Claude Mythos Preview, i token di pensiero grezzi non vengono mai restituiti.
² Con il pensiero adattivo. L'header beta interleaved-thinking-2025-05-14 non è necessario su questi modelli e viene ignorato in modo sicuro se incluso.
³ I blocchi vengono rimossi quando si continua la conversazione su un modello che non supporta il formato di pensiero Mythos.



Conservazione dei blocchi di pensiero per modello

Se i blocchi di pensiero dei turni precedenti dell'assistente vengono conservati nel contesto per impostazione predefinita dipende dalla classe del modello. Opus: Claude Opus 4.5 e i modelli Opus successivi mantengono tutti i blocchi di pensiero precedenti; Claude Opus 4.1 (deprecato) e i modelli Opus precedenti mantengono solo il pensiero dell'ultimo turno dell'assistente. Sonnet: Claude Sonnet 4.6 e i modelli Sonnet successivi mantengono tutti; Claude Sonnet 4.5 e i modelli Sonnet precedenti mantengono solo l'ultimo turno. Haiku: tutti i modelli Haiku fino a Claude Haiku 4.5 mantengono solo l'ultimo turno. Anche Claude Mythos Preview mantiene tutti i blocchi di pensiero precedenti.

Vantaggi della conservazione dei blocchi di pensiero:

• Ottimizzazione della cache: Quando si usa l'uso degli strumenti, i blocchi di pensiero conservati consentono cache hit poiché vengono passati indietro con i risultati degli strumenti e memorizzati nella cache in modo incrementale durante il turno dell'assistente, con conseguente risparmio di token nei flussi di lavoro multi-step
• Nessun impatto sull'intelligenza: La conservazione dei blocchi di pensiero non ha alcun effetto negativo sulle prestazioni del modello

Considerazioni importanti:

• Utilizzo del contesto: Le conversazioni lunghe consumeranno più spazio di contesto poiché i blocchi di pensiero vengono mantenuti nel contesto
• Comportamento automatico: Questo è il valore predefinito per ogni modello come elencato sopra. Non sono richieste modifiche al codice o header beta
• Retrocompatibilità: Per sfruttare questa funzionalità, continua a passare blocchi di pensiero completi e non modificati all'API come faresti per l'uso degli strumenti



Prezzi

Per informazioni complete sui prezzi, inclusi i costi base, le scritture in cache, gli accessi alla cache e i token di output, consulta la pagina dei prezzi.

Il processo di pensiero comporta costi per:

• Token utilizzati durante il pensiero (token di output)
• Blocchi di pensiero dai turni precedenti dell'assistente mantenuti nel contesto: solo l'ultimo turno sui modelli Opus/Sonnet precedenti e su tutti i modelli Haiku; tutti i turni per impostazione predefinita su Opus 4.5+ e Sonnet 4.6+ (token di input)
• Token di output di testo standard

Quando si utilizza il pensiero riassunto:

• Token di input: Token nella tua richiesta originale (esclusi i token di pensiero dei turni precedenti)
• Token di output (fatturati): I token di pensiero originali che Claude ha generato internamente
• Token di output (visibili): I token di pensiero riassunti che vedi nella risposta
• Nessun addebito: Token utilizzati per generare il riassunto

Quando si utilizza display: "omitted":

• Token di input: Token nella tua richiesta originale (come per il pensiero riassunto)
• Token di output (fatturati): I token di pensiero originali che Claude ha generato internamente (come per il pensiero riassunto)
• Token di output (visibili): Zero token di pensiero (il campo thinking è vuoto)

Per vedere quanti token di output fatturati sono stati spesi per il ragionamento interno, leggi usage.output_tokens_details.thinking_tokens nella risposta. Questo valore riflette il ragionamento grezzo generato dal modello (non il testo riassunto restituito nel corpo della risposta) ed è sempre minore o uguale a output_tokens. Sottrailo da output_tokens per ottenere un'approssimazione della porzione di output non relativa al ragionamento.

{
  "usage": {
    "input_tokens": 25,
    "output_tokens": 348,
    "output_tokens_details": {
      "thinking_tokens": 312
    }
  }
}

output_tokens rimane il totale inclusivo e autorevole utilizzato per la fatturazione. output_tokens_details è una suddivisione di sola lettura a scopo di osservabilità.



Best practice e considerazioni per il pensiero esteso



Lavorare con i budget di pensiero

• Ottimizzazione del budget: Il budget minimo è di 1.024 token. Inizia dal minimo e aumenta il budget di pensiero in modo incrementale per trovare l'intervallo ottimale per il tuo caso d'uso. Un numero maggiore di token consente un ragionamento più completo, ma con rendimenti decrescenti a seconda del compito. Aumentare il budget può migliorare la qualità della risposta al costo di una maggiore "latency" (latenza). Per compiti critici, testa diverse impostazioni per trovare l'equilibrio ottimale. Nota che il budget di pensiero è un obiettivo piuttosto che un limite rigido. L'utilizzo effettivo dei token può variare in base al compito.
• Punti di partenza: Inizia con budget di pensiero più ampi (16k+ token) per compiti complessi e regola in base alle tue esigenze.
• Budget elevati: Per budget di pensiero superiori a 32k, usa l'elaborazione batch per evitare problemi di rete. Le richieste che spingono il modello a pensare oltre i 32k token causano richieste di lunga durata che potrebbero scontrarsi con timeout di sistema e limiti di connessioni aperte.
• Monitoraggio dell'utilizzo dei token: Monitora l'utilizzo dei token di pensiero per ottimizzare costi e prestazioni. Il campo usage.output_tokens_details.thinking_tokens nella risposta riporta quanti dei token di output fatturati sono stati utilizzati per il ragionamento interno. Durante lo streaming, questa suddivisione appare solo nell'evento finale message_delta.



Considerazioni sulle prestazioni

• Tempi di risposta: Preparati a tempi di risposta più lunghi a causa dell'elaborazione aggiuntiva. La generazione di blocchi di pensiero aumenta il tempo di risposta complessivo.
• Requisiti di streaming: 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 per i dettagli. Durante lo streaming, preparati a gestire sia i blocchi di contenuto di pensiero che quelli di testo man mano che arrivano.
• Omettere il pensiero per ridurre la latenza: Se la tua applicazione non visualizza il contenuto del pensiero, imposta display: "omitted" nella configurazione del pensiero per ridurre il tempo al primo token di testo. Consulta Controllare la visualizzazione del pensiero.



Compatibilità delle funzionalità

• Il pensiero non è compatibile con le modifiche a temperature o top_k, né con l'uso forzato degli strumenti.
• Quando il pensiero è abilitato, puoi impostare top_p su valori compresi tra 1 e 0,95.
• Non puoi precompilare le risposte quando il pensiero è abilitato.
• Le modifiche al budget di pensiero invalidano i prefissi di prompt memorizzati nella cache che includono messaggi. Tuttavia, i prompt di sistema e le definizioni degli strumenti memorizzati nella cache continueranno a funzionare quando i parametri di pensiero cambiano.



Linee guida per l'utilizzo

• Selezione dei compiti: Usa il pensiero esteso per compiti particolarmente complessi che beneficiano di un ragionamento passo dopo passo, come matematica, programmazione e analisi.
• Gestione del contesto: Non è necessario rimuovere manualmente i blocchi di pensiero precedenti. Su Opus 4.5+ e Sonnet 4.6+, l'API di Claude mantiene per impostazione predefinita i blocchi di pensiero dei turni precedenti; sui modelli Opus/Sonnet precedenti e su tutti i modelli Haiku, li ignora automaticamente e non vengono inclusi nel calcolo dell'utilizzo del contesto.
• Prompt engineering: Consulta i suggerimenti per i prompt con pensiero esteso se vuoi massimizzare le capacità di pensiero di Claude.



Passaggi successivi