Costruire con il ragionamento esteso

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

Modelli supportati

Il ragionamento esteso manuale (thinking: {type: "enabled", budget_tokens: N}) è supportato su tutti i modelli Claude attuali eccetto Claude Opus 4.7 e modelli successivi, dove non è più accettato e restituisce un errore 400. Alcuni modelli hanno comportamenti specifici della modalità:

• Claude Opus 4.7 (claude-opus-4-7) e modelli successivi: il ragionamento esteso manuale non è più supportato. Utilizza invece il ragionamento adattivo (thinking: {type: "adaptive"}) con il parametro effort.
• Claude Mythos Preview: il ragionamento adattivo è l'impostazione predefinita; thinking: {type: "enabled", budget_tokens: N} è anche accettato. thinking: {type: "disabled"} non è supportato e display è impostato per impostazione predefinita su "omitted" anziché restituire il contenuto del ragionamento. Passa display: "summarized" per ricevere i riassunti.
• Claude Opus 4.6 (claude-opus-4-6): ragionamento adattivo consigliato; la modalità manuale (type: "enabled") è deprecata ma ancora funzionale.
• Claude Sonnet 4.6 (claude-sonnet-4-6): ragionamento adattivo consigliato; la modalità manuale (type: "enabled") con modalità intercalata è deprecata ma ancora funzionale.

Come funziona il ragionamento esteso

Quando il ragionamento esteso è attivato, Claude crea blocchi di contenuto thinking dove produce il suo ragionamento interno. Claude incorpora gli approfondimenti da questo ragionamento prima di formulare 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 ragionamento esteso, vedi il Riferimento API Messages.

Come utilizzare il ragionamento esteso

Ecco un esempio di utilizzo del ragionamento 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?",
        }
    ],
)

# The response contains summarized thinking blocks and text blocks
for block in response.content:
    if block.type == "thinking":
        print(f"\nThinking summary: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")

Per attivare il ragionamento esteso, aggiungi un oggetto thinking, con il parametro type impostato su enabled e budget_tokens impostato su un budget di token specificato per il ragionamento esteso. Per Claude Opus 4.6 e Claude Sonnet 4.6, utilizza invece type: "adaptive". Vedi Ragionamento adattivo per i dettagli. Mentre type: "enabled" con budget_tokens è ancora funzionale su questi modelli, è deprecato e verrà rimosso in una futura versione.

Il parametro budget_tokens determina il numero massimo di token che Claude può utilizzare per il suo processo di ragionamento interno. Nei modelli Claude 4 e successivi, questo limite si applica ai token di ragionamento 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 negli intervalli superiori a 32k.

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

Ragionamento 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. This is the default behavior on Claude 4 models when the display field on the thinking configuration is unset or set to "summarized". On Claude Opus 4.7 and Claude Mythos Preview, display defaults to "omitted" instead, so you must set display: "summarized" explicitly to receive summarized thinking.

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.
• On Claude 4 models, the first few lines of thinking output are more verbose, providing detailed reasoning that's particularly helpful for prompt engineering purposes. Claude Mythos Preview summarizes from the first token, so its thinking blocks do not show this verbose preamble.
• 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.
• Summarization is processed by a different model than the one you target in your requests. The thinking model does not see the summarized output.

Controllo della visualizzazione del ragionamento

The display field on the thinking configuration controls how thinking content is returned in API responses. It accepts two values:

• "summarized": Thinking blocks contain summarized thinking text. See Summarized thinking for details. This is the default on Claude Opus 4.6, Claude Sonnet 4.6, and earlier Claude 4 models.
• "omitted": Thinking blocks are returned with an empty thinking field. The signature field still carries the encrypted full thinking for multi-turn continuity (see Thinking encryption). This is the default on Claude Opus 4.7 and Claude Mythos Preview.

Setting display: "omitted" is useful when your application doesn't surface thinking content to users. The primary benefit is faster time-to-first-text-token when streaming: The server skips streaming thinking tokens entirely and delivers only the signature, so the final text response begins streaming sooner.

Here are some important considerations for omitted thinking:

• You're still charged for the full thinking tokens. Omitting reduces latency, not cost.
• If you pass thinking blocks back in multi-turn conversations, pass them unchanged. The server decrypts the signature to reconstruct the original thinking for prompt construction (see Preserving thinking blocks). Any text you place in the thinking field of a round-tripped omitted block is ignored.
• display is invalid with thinking.type: "disabled" (there is nothing to display).
• When using thinking.type: "adaptive" and the model skips thinking for a simple request, no thinking block is produced regardless of display.

Le pipeline automatizzate che non espongono mai il contenuto del ragionamento agli utenti finali possono saltare il sovraccarico di ricezione dei token di ragionamento sulla rete. Le applicazioni sensibili alla latenza ottengono la stessa qualità di ragionamento senza aspettare che il testo del ragionamento venga trasmesso prima che inizi la risposta finale.

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 trasmette con display: "omitted", non vengono emessi eventi thinking_delta; vedi Ragionamento in streaming di seguito per la sequenza di eventi.

Streaming del pensiero

Puoi trasmettere risposte di pensiero esteso utilizzando 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. Vedi Controlling thinking display.

Per ulteriore documentazione sullo streaming tramite l'API Messages, vedi Streaming Messages.

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...")
            # Reset flags for each new block
            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 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": "", "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 uso di strumenti

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

Quando utilizzi 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": "..."} risulterà in 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 di strumenti, devi passare i blocchi thinking indietro all'API per l'ultimo messaggio dell'assistente. Includi il blocco completo non modificato indietro all'API per mantenere la continuità del ragionamento.

Attivazione/disattivazione delle modalità di thinking nelle conversazioni

Non puoi attivare/disattivare il thinking nel mezzo di un turno dell'assistente, incluso durante i loop di utilizzo degli strumenti. L'intero turno dell'assistente dovrebbe operare in una singola modalità di thinking:

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

Dal punto di vista del modello, i loop di utilizzo 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 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 loop di utilizzo degli strumenti è concettualmente parte di una risposta dell'assistente continua.

Degradazione elegante del thinking

Quando si verifica un conflitto di thinking a metà turno (come l'attivazione o la disattivazione del thinking durante un loop di utilizzo degli strumenti), l'API disabilita automaticamente il thinking per quella richiesta. Per preservare la qualità del modello e rimanere on-distribution, l'API può:

• Rimuovere i blocchi di thinking dalla conversazione quando creerebbero una struttura di turno non valida
• Disabilitare il thinking per la richiesta corrente quando la cronologia della conversazione è incompatibile con l'abilitazione del thinking

Ciò significa che il tentativo di attivare/disattivare il thinking a metà turno non causerà un errore, ma il thinking sarà silenziosamente disabilitato per quella richiesta. Per confermare se il thinking era attivo, controlla la presenza di blocchi thinking nella risposta.

Guida pratica

Best practice: Pianifica la tua strategia di thinking all'inizio di ogni turno piuttosto che cercare di attivare/disattivare a metà turno.

Esempio: Attivazione/disattivazione del thinking 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 attivare/disattivare il thinking, assicuri che il thinking sia effettivamente abilitato per la nuova richiesta.

Preservazione dei blocchi di thinking

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

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

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

2. Mantenimento del contesto: Mentre i risultati degli strumenti appaiono come messaggi utente nella struttura dell'API, fanno parte di un flusso di ragionamento continuo. Preservare i blocchi di thinking mantiene questo flusso concettuale attraverso più chiamate API. Per ulteriori informazioni sulla gestione del contesto, vedi 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 riordinare o modificare la sequenza di questi blocchi.

Thinking interleaved

Extended thinking con utilizzo degli strumenti nei modelli Claude 4 supporta il thinking interleaved, che consente a Claude di pensare tra le chiamate agli strumenti e di fare ragionamenti più sofisticati dopo aver ricevuto i risultati degli strumenti.

Con il thinking interleaved, Claude può:

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

Supporto del modello:

• Claude Mythos Preview: Il thinking interleaved avviene automaticamente. Ogni passaggio di ragionamento inter-strumento si sposta in un blocco di thinking invece di testo semplice, e i blocchi di thinking vengono preservati tra i turni per impostazione predefinita. Nessun header beta è necessario o supportato.
• Claude Opus 4.7: Il thinking interleaved è automaticamente abilitato quando si utilizza adaptive thinking (l'unica modalità di thinking supportata su Opus 4.7). Nessun header beta è necessario.
• Claude Opus 4.6: Il thinking interleaved è automaticamente abilitato quando si utilizza adaptive thinking. Nessun header beta è necessario. L'header beta interleaved-thinking-2025-05-14 è deprecato su Opus 4.6 e viene ignorato in sicurezza se incluso.
• Claude Sonnet 4.6: Il thinking interleaved è automaticamente abilitato quando si utilizza adaptive thinking (consigliato). L'header beta interleaved-thinking-2025-05-14 con extended thinking manuale (thinking: {type: "enabled"}) è ancora funzionale ma deprecato.
• Altri modelli Claude 4 (Opus 4.5, Opus 4.1, Opus 4 (deprecato), Sonnet 4.5, Sonnet 4 (deprecato)): Aggiungi l'header beta interleaved-thinking-2025-05-14 alla tua richiesta API per abilitare il thinking interleaved.

Ecco alcune considerazioni importanti per il thinking interleaved:

• Con il thinking interleaved, il budget_tokens può superare il parametro max_tokens, poiché rappresenta il budget totale su tutti i blocchi di thinking all'interno di un turno dell'assistente.
• Il thinking interleaved è supportato solo per strumenti utilizzati tramite l'API Messages.
• Le chiamate dirette all'API Claude ti consentono di passare interleaved-thinking-2025-05-14 nelle richieste a qualsiasi modello, senza effetto (eccetto Opus 4.7 e Opus 4.6, dove è deprecato e ignorato in sicurezza).
• Su piattaforme di terze parti (ad esempio, Amazon Bedrock e Vertex AI), se passi interleaved-thinking-2025-05-14 a qualsiasi modello diverso da Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6, Claude Opus 4.5, Claude Opus 4.1, Opus 4 (deprecato), Sonnet 4.5 o Sonnet 4 (deprecato), la tua richiesta avrà esito negativo.

Extended thinking con prompt caching

Prompt caching con thinking ha diverse considerazioni importanti:

Rimozione del contesto dei blocchi di thinking

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

Modelli di invalidazione della cache

• Le modifiche ai parametri di thinking (abilitato/disabilitato o allocazione del budget) invalidano i punti di interruzione della cache dei messaggi
• Interleaved thinking amplifica l'invalidazione della cache, poiché i blocchi di thinking possono verificarsi tra più tool call
• I prompt di sistema e gli strumenti rimangono memorizzati nella cache nonostante le modifiche ai parametri di thinking 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 mostrano 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 uso 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 mantenuti 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 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 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 di prompt e 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 di 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 corrente 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)

Utilizza l'API di conteggio dei token per ottenere conteggi dei 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 utilizza il pensiero esteso con l'uso degli strumenti, i blocchi di pensiero devono essere esplicitamente preservati 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 sottostante 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 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 max_tokens al variare della lunghezza del prompt
• 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, specialmente 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.
• signature values are compatible across platforms (Claude APIs, Amazon Bedrock, and Vertex AI). Values generated on one platform will be compatible with another.

Blocchi di pensiero redatti

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 alcun riassunto leggibile:

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

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

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 riassunto.

Vedi la tabella sottostante per un confronto condensato:

Preservazione dei blocchi 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 precedenti dell'assistente 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 dei blocchi di pensiero:

• Ottimizzazione della cache: Quando si utilizza l'uso degli strumenti, i blocchi di pensiero preservati abilitano i cache hit poiché vengono passati indietro con i risultati degli strumenti 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 mantenuti nel contesto
• Comportamento automatico: Questo è il comportamento predefinito per Claude Opus 4.5 e i modelli successivi (inclusi Claude Mythos Preview e Claude Opus 4.6). Non sono richiesti cambiamenti di codice o header beta
• Compatibilità all'indietro: Per sfruttare questa funzionalità, continua a passare i blocchi di pensiero completi e non modificati all'API come faresti per l'uso degli 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 prior assistant turns kept in context: only the last turn on earlier Opus/Sonnet models and all Haiku models; all turns by default on Opus 4.5+ and Sonnet 4.6+ (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

When using display: "omitted":

• Input tokens: Tokens in your original request (same as summarized)
• Output tokens (billed): The original thinking tokens that Claude generated internally (same as summarized)
• Output tokens (visible): Zero thinking tokens (the thinking field is empty)

Best practice e considerazioni per il pensiero esteso

Lavorare con i budget di pensiero

• Ottimizzazione del budget: Il budget minimo è 1.024 token. Inizia con il minimo e aumenta il budget di pensiero in modo incrementale per trovare l'intervallo ottimale per il tuo caso d'uso. Conteggi di token più elevati consentono un ragionamento più completo ma con rendimenti decrescenti a seconda dell'attività. L'aumento del 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 obiettivo 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, utilizza 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 per 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 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 i singoli eventi. Vedi Streaming Messages per i dettagli. Durante lo streaming, preparati a gestire sia i blocchi di pensiero che di testo mentre arrivano.
• Omissione del pensiero per la latenza: Se la tua applicazione non visualizza il contenuto di pensiero, imposta display: "omitted" sulla configurazione del pensiero per ridurre il tempo al primo token di testo. Vedi Controlling thinking display.

Compatibilità delle funzionalità

• Il pensiero non è compatibile con le modifiche temperature o top_k così come con l'uso forzato degli strumenti.
• 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 di 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 hai bisogno di 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.
• Prompt engineering: Rivedi i suggerimenti per il prompt di pensiero esteso se vuoi massimizzare le capacità di pensiero di Claude.

Passaggi successivi