Costruire con il pensiero esteso

Il pensiero esteso offre a Claude capacità di ragionamento migliorate per compiti complessi, fornendo vari livelli di trasparenza nel suo processo di pensiero passo dopo passo prima di fornisce la risposta finale.

Modelli supportati

Il pensiero esteso è supportato nei seguenti modelli:

• Claude Opus 4.6 (claude-opus-4-6) — pensiero adattivo solo; la modalità manuale (type: "enabled") è deprecata
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4.6 (claude-sonnet-4-6) — supporta sia il pensiero esteso manuale con modalità intercalata che il pensiero adattivo
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Sonnet 3.7 (claude-3-7-sonnet-20250219) (deprecato)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)

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 gli insegnamenti da questo ragionamento prima di formulare una risposta finale.

La risposta dell'API includerà 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, vedere il Riferimento API dei Messaggi.

Come utilizzare il pensiero esteso

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

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "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?"
        }
    ]
}'

Per attivare il pensiero esteso, aggiungi un oggetto thinking, con il parametro type impostato su enabled e budget_tokens su un budget di token specificato per il pensiero esteso. Per Claude Opus 4.6, consigliamo di utilizzare type: "adaptive" — vedere Pensiero adattivo per i dettagli. Mentre type: "enabled" con budget_tokens è ancora supportato su Opus 4.6, è deprecato e verrà rimosso in una futura versione.

Il parametro budget_tokens determina il numero massimo di token che Claude è autorizzato a utilizzare per il suo processo di ragionamento interno. Nei modelli Claude 4 e successivi, questo limite si applica ai token di pensiero completo, non all'output riassunto. Budget più grandi possono migliorare la qualità della risposta abilitando un'analisi più approfondita per problemi complessi, anche se Claude potrebbe non utilizzare l'intero budget allocato, specialmente in intervalli superiori a 32k.

budget_tokens deve essere impostato su un valore inferiore a max_tokens. Tuttavia, quando si utilizza il pensiero intercalato con strumenti, è possibile superare questo limite poiché il limite di token diventa l'intera finestra di contesto (200k token).

Pensiero riassunto

With extended thinking enabled, the Messages API for Claude 4 models returns a summary of Claude's full thinking process. Summarized thinking provides the full intelligence benefits of extended thinking, while preventing misuse.

Here are some important considerations for summarized thinking:

• You're charged for the full thinking tokens generated by the original request, not the summary tokens.
• The billed output token count will not match the count of tokens you see in the response.
• The first few lines of thinking output are more verbose, providing detailed reasoning that's particularly helpful for prompt engineering purposes.
• As Anthropic seeks to improve the extended thinking feature, summarization behavior is subject to change.
• Summarization preserves the key ideas of Claude's thinking process with minimal added latency, enabling a streamable user experience and easy migration from Claude Sonnet 3.7 to Claude 4 and later models.
• Summarization is processed by a different model than the one you target in your requests. The thinking model does not see the summarized output.

Streaming del pensiero

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

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

Per ulteriore documentazione sullo streaming tramite l'API dei Messaggi, vedere Streaming dei Messaggi.

Ecco come gestire lo streaming con il pensiero:

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-6",
    "max_tokens": 16000,
    "stream": true,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 10000
    },
    "messages": [
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?"
        }
    ]
}'

Esempio di output dello 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": ""}}

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"}

Pensiero esteso con uso di strumenti

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

Quando si utilizza il pensiero esteso con l'uso di strumenti, tieni presente le seguenti limitazioni:

1. Limitazione della scelta dello strumento: L'uso di 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": "..."} comporterà un errore perché queste opzioni forzano l'uso dello strumento, che è incompatibile con il pensiero esteso.

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

Alternanza delle modalità di pensiero nelle conversazioni

Non puoi alternare il pensiero nel mezzo di un turno dell'assistente, incluso durante i cicli di uso dello strumento. 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 dello strumento 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 di strumenti e risultati.

Ad esempio, questa sequenza fa 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 dello strumento è concettualmente parte di una risposta continua dell'assistente.

Degradazione del pensiero elegante

Quando si verifica un conflitto di pensiero a metà turno (come alternare il pensiero on o off durante un ciclo di uso dello strumento), l'API disabilita automaticamente il pensiero per quella richiesta. Per preservare la qualità del modello e rimanere sulla 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 il tentativo di alternare il pensiero a metà turno non causerà un errore, ma il pensiero verrà silenziosamente disabilitato per quella richiesta. Per confermare se il pensiero era attivo, controlla la presenza di blocchi thinking nella risposta.

Guida pratica

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

Esempio: Alternanza del pensiero dopo il completamento di 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, assicuri che il pensiero sia effettivamente abilitato per la nuova richiesta.

Preservazione dei blocchi di pensiero

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

Quando Claude richiama gli strumenti, sta mettendo in pausa la costruzione di una risposta per attendere informazioni esterne. Quando i risultati degli strumenti vengono restituiti, Claude continuerà a costruire quella risposta esistente. Ciò rende necessaria la preservazione dei blocchi di pensiero durante l'uso dello strumento, 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 pubblichi i risultati degli strumenti, includere il pensiero originale assicura che Claude possa continuare il suo ragionamento da dove l'ha lasciato.

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

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

Pensiero intercalato

Il pensiero esteso con uso di strumenti nei modelli Claude 4 supporta il pensiero intercalato, che consente a Claude di pensare tra le chiamate di strumenti e fare ragionamenti più sofisticati dopo aver ricevuto i risultati degli strumenti.

Con il pensiero intercalato, Claude può:

• Ragionare sui risultati di una chiamata di strumento prima di decidere cosa fare dopo
• Concatenare più chiamate di strumenti con passaggi di ragionamento nel mezzo
• Prendere decisioni più sfumate basate sui risultati intermedi

Supporto del modello:

• Claude Opus 4.6: Il pensiero intercalato è automaticamente abilitato quando si utilizza il pensiero adattivo — non è necessaria alcuna intestazione beta. L'intestazione beta interleaved-thinking-2025-05-14 è deprecata su Opus 4.6 e viene ignorata in sicurezza se inclusa.
• Claude Sonnet 4.6: Supporta l'intestazione beta interleaved-thinking-2025-05-14 con il pensiero esteso manuale (thinking: {type: "enabled"}). Puoi anche utilizzare il pensiero adattivo, che abilita automaticamente il pensiero intercalato.
• Altri modelli Claude 4 (Opus 4.5, Opus 4.1, Opus 4, Sonnet 4.5, Sonnet 4): Aggiungi l'intestazione beta interleaved-thinking-2025-05-14 alla tua richiesta API per abilitare il pensiero intercalato.

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 dei Messaggi.
• Le chiamate dirette all'API Claude ti consentono di passare interleaved-thinking-2025-05-14 nelle richieste a qualsiasi modello, senza effetto (tranne Opus 4.6, dove è deprecato e ignorato in sicurezza).
• Sulle piattaforme di terze parti (ad esempio, Amazon Bedrock e Vertex AI), se passi interleaved-thinking-2025-05-14 a qualsiasi modello diverso da Claude Sonnet 4.6, Claude Opus 4.5, Claude Opus 4.1, Opus 4, Sonnet 4.5 o Sonnet 4, la tua richiesta avrà esito negativo.

Pensiero esteso con cache dei prompt

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

Rimozione del contesto dei blocchi di pensiero

• I blocchi di pensiero dai turni precedenti vengono rimossi dal contesto, il che può influire sui punti di interruzione della cache
• Quando si continuano conversazioni con l'uso dello strumento, i blocchi di pensiero vengono memorizzati nella cache e contano come token di input quando letti dalla cache
• Questo crea un compromesso: mentre i blocchi di pensiero non consumano spazio nella finestra di contesto visivamente, contano comunque verso l'utilizzo dei token di input quando memorizzati nella cache
• Se il pensiero diventa disabilitato e passi il contenuto del pensiero nel turno di uso dello strumento corrente, il contenuto del pensiero verrà rimosso e il pensiero rimarrà disabilitato per quella richiesta

Modelli di invalidazione della cache

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

Comprensione del comportamento della cache dei blocchi di pensiero

Quando si utilizza il pensiero esteso con l'uso di strumenti, i blocchi di pensiero presentano un comportamento specifico della cache che influisce sul conteggio dei token:

Come funziona:

1. La cache si verifica solo quando effettui una richiesta successiva che include i risultati dello strumento
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 metriche di utilizzo quando vengono letti dalla cache
4. Quando è incluso un blocco utente non relativo ai risultati dello strumento, tutti i blocchi di pensiero precedenti vengono ignorati e rimossi dal contesto

Flusso di esempio dettagliato:

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 di utilizzo dello strumento 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 Claude Opus 4.5 e versioni successive (incluso Claude Opus 4.6), tutti i blocchi di pensiero precedenti vengono conservati per impostazione predefinita. Per i modelli più vecchi, poiché è stato incluso un blocco utente non relativo ai risultati dello strumento, tutti i blocchi di pensiero precedenti vengono ignorati. Questa richiesta verrà elaborata allo stesso modo di:

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 della cache avviene automaticamente, anche senza marcatori cache_control espliciti
• Questo comportamento è coerente sia che si utilizzi il pensiero regolare che il pensiero intercalato

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

Nei modelli Claude più vecchi (precedenti a Claude Sonnet 3.7), se la somma dei token del prompt e di max_tokens superava la finestra di contesto del modello, il sistema regolava automaticamente max_tokens per adattarsi al limite di contesto. Ciò significava che potevi impostare un valore max_tokens grande e il sistema lo avrebbe silenziosamente ridotto secondo le necessità.

Con i modelli Claude 3.7 e 4, max_tokens (che include il tuo budget di pensiero quando il pensiero è abilitato) viene applicato come limite rigoroso. Il sistema ora restituirà un errore di convalida se i token del prompt + max_tokens superano la dimensione della finestra di contesto.

La finestra di contesto con il pensiero esteso

Quando si calcola l'utilizzo della finestra di contesto con il pensiero abilitato, ci sono alcune considerazioni di cui essere consapevoli:

• I blocchi di pensiero dai turni precedenti vengono rimossi e non contano verso la tua finestra di contesto
• Il pensiero del turno attuale conta verso il tuo limite max_tokens per quel turno

Il diagramma sottostante dimostra 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)

Consigliamo di utilizzare l'API di conteggio dei token per ottenere conteggi di token accurati per il tuo caso d'uso specifico, soprattutto quando si lavora con conversazioni multi-turno che includono il pensiero.

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

Quando si utilizza il pensiero esteso con l'uso di strumenti, i blocchi di pensiero devono essere esplicitamente preservati e restituiti con i risultati dello strumento.

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

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

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

Gestione dei token con il pensiero esteso

Data la finestra di contesto e il comportamento di max_tokens con il pensiero esteso nei modelli Claude 3.7 e 4, potrebbe essere necessario:

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

Questo cambiamento è stato apportato per fornire un comportamento più prevedibile e trasparente, soprattutto poiché i limiti massimi di token sono aumentati significativamente.

Crittografia del pensiero

Full thinking content is encrypted and returned in the signature field. This field is used to verify that thinking blocks were generated by Claude when passed back to the API.

Here are some important considerations on thinking encryption:

• When streaming responses, the signature is added via a signature_delta inside a content_block_delta event just before the content_block_stop event.
• signature values are significantly longer in Claude 4 models than in previous models.
• The signature field is an opaque field and should not be interpreted or parsed - it exists solely for verification purposes.
• signature values are compatible across platforms (Claude APIs, Amazon Bedrock, and Vertex AI). Values generated on one platform will be compatible with another.

Redazione del pensiero

Occasionally Claude's internal reasoning will be flagged by our safety systems. When this occurs, we encrypt some or all of the thinking block and return it to you as a redacted_thinking block. redacted_thinking blocks are decrypted when passed back to the API, allowing Claude to continue its response without losing context.

When building customer-facing applications that use extended thinking:

• Be aware that redacted thinking blocks contain encrypted content that isn't human-readable
• Consider providing a simple explanation like: "Some of Claude's internal reasoning has been automatically encrypted for safety reasons. This doesn't affect the quality of responses."
• If showing thinking blocks to users, you can filter out redacted blocks while preserving normal thinking blocks
• Be transparent that using extended thinking features may occasionally result in some reasoning being encrypted
• Implement appropriate error handling to gracefully manage redacted thinking without breaking your UI

Here's an example showing both normal and redacted thinking blocks:

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

When passing thinking and redacted_thinking blocks back to the API in a multi-turn conversation, you must include the complete unmodified block back to the API for the last assistant turn. This is critical for maintaining the model's reasoning flow. We suggest always passing back all thinking blocks to the API. For more details, see the Preserving thinking blocks section.

Differenze nel pensiero tra le versioni dei modelli

L'API Messages gestisce il pensiero diversamente tra i modelli Claude Sonnet 3.7 e Claude 4, principalmente nel comportamento di redazione e riassunto.

Vedi la tabella sottostante per un confronto condensato:

Preservazione del blocco di pensiero in Claude Opus 4.5 e versioni successive

A partire da Claude Opus 4.5 (e continuando in Claude Opus 4.6), i blocchi di pensiero dai turni dell'assistente precedenti vengono preservati nel contesto del modello per impostazione predefinita. Questo differisce dai modelli precedenti, che rimuovono i blocchi di pensiero dai turni precedenti.

Vantaggi della preservazione del blocco di pensiero:

• Ottimizzazione della cache: Quando si utilizza l'uso di strumenti, i blocchi di pensiero preservati abilitano i cache hit poiché vengono passati indietro con i risultati dello strumento e memorizzati nella cache in modo incrementale nel turno dell'assistente, risultando in risparmi di token nei flussi di lavoro multi-step
• Nessun impatto sull'intelligenza: La preservazione 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 conservati nel contesto
• Comportamento automatico: Questo è il comportamento predefinito per i modelli Claude Opus 4.5 e versioni successive (incluso Opus 4.6)—non sono necessarie modifiche al codice o header beta
• Compatibilità all'indietro: Per sfruttare questa funzione, continua a passare i blocchi di pensiero completi e non modificati all'API come faresti per l'uso di strumenti

Prezzi

For complete pricing information including base rates, cache writes, cache hits, and output tokens, see the pricing page.

The thinking process incurs charges for:

• Tokens used during thinking (output tokens)
• Thinking blocks from the last assistant turn included in subsequent requests (input tokens)
• Standard text output tokens

When using summarized thinking:

• Input tokens: Tokens in your original request (excludes thinking tokens from previous turns)
• Output tokens (billed): The original thinking tokens that Claude generated internally
• Output tokens (visible): The summarized thinking tokens you see in the response
• No charge: Tokens used to generate the summary

Best practice e considerazioni per il pensiero esteso

Lavorare con i budget di pensiero

• Ottimizzazione del budget: Il budget minimo è 1.024 token. Consigliamo di iniziare con il minimo e aumentare il budget di pensiero in modo incrementale per trovare l'intervallo ottimale per il tuo caso d'uso. Conteggi di token più elevati abilitano un ragionamento più completo ma con rendimenti decrescenti a seconda dell'attività. Aumentare il budget può migliorare la qualità della risposta al costo di una latenza aumentata. Per attività critiche, testa diverse impostazioni per trovare l'equilibrio ottimale. Nota che il budget di pensiero è un target piuttosto che un limite rigoroso—l'utilizzo effettivo dei token può variare in base all'attività.
• Punti di partenza: Inizia con budget di pensiero più grandi (16k+ token) per attività complesse e regola in base alle tue esigenze.
• Budget grandi: Per budget di pensiero superiori a 32k, consigliamo di utilizzare l'elaborazione batch per evitare problemi di rete. Le richieste che spingono il modello a pensare oltre 32k token causano richieste a lunga esecuzione che potrebbero scontrarsi con timeout di sistema e limiti di connessione aperta.
• Tracciamento dell'utilizzo dei token: Monitora l'utilizzo dei token di pensiero per ottimizzare i costi e le prestazioni.

Considerazioni sulle prestazioni

• Tempi di risposta: Preparati a potenziali tempi di risposta più lunghi a causa dell'elaborazione aggiuntiva richiesta per il processo di ragionamento. Tieni in considerazione che la generazione di blocchi di pensiero può aumentare 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 a lunga esecuzione. Questa è una convalida lato client, non una restrizione API. Se non hai bisogno di elaborare gli eventi in modo incrementale, utilizza .stream() con .get_final_message() (Python) o .finalMessage() (TypeScript) per ottenere l'oggetto Message completo senza gestire gli eventi individuali — vedi Streaming Messages per i dettagli. Quando esegui lo streaming, preparati a gestire sia i blocchi di contenuto di pensiero che di testo mentre arrivano.

Compatibilità delle funzioni

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

Linee guida sull'utilizzo

• Selezione dell'attività: Utilizza il pensiero esteso per attività particolarmente complesse che beneficiano del ragionamento passo dopo passo come matematica, codifica e analisi.
• Gestione del contesto: Non è necessario rimuovere i blocchi di pensiero precedenti da solo. L'API Claude ignora automaticamente i blocchi di pensiero dai turni precedenti e non vengono inclusi quando si calcola l'utilizzo del contesto.
• Ingegneria del prompt: Rivedi i nostri suggerimenti per il prompt del pensiero esteso se desideri massimizzare le capacità di pensiero di Claude.

Passaggi successivi