Ragionamento esteso

L'"extended thinking" (ragionamento esteso) in modalità manuale ti offre un controllo diretto su quanto Claude pensa. Imposti un budget di token di ragionamento su ogni richiesta con thinking: {type: "enabled", budget_tokens: N}, e Claude pensa entro quel budget prima di iniziare la sua risposta finale. La modalità manuale rimane utile quando il tuo carico di lavoro richiede una latenza prevedibile o un controllo preciso sui costi del ragionamento. Questa pagina spiega come impostare e regolare il budget, come la modalità manuale interagisce con il ragionamento interlacciato e la "prompt caching" (cache dei prompt), e come migrare al ragionamento adattivo.

Per capire come funziona il ragionamento in sé, inclusi i blocchi di ragionamento e la forma della risposta, il parametro display, lo streaming, il ragionamento con l'uso degli strumenti e la crittografia, consulta la panoramica sul ragionamento.

Modelli supportati

La disponibilità del ragionamento esteso per modello, inclusi i modelli in cui il ragionamento esteso è l'unica modalità, è elencata nella tabella di configurazione per modello.

Come usare il ragionamento esteso

Ecco un esempio di utilizzo del ragionamento esteso nella Messages API:

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 ragionamento 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 ragionamento esteso manuale, aggiungi un oggetto thinking con type impostato su enabled e un valore budget_tokens.

Il parametro budget_tokens imposta un obiettivo per quanti token Claude può usare per il suo processo di ragionamento interno. Budget più ampi possono migliorare la qualità della risposta consentendo un'analisi più approfondita per problemi complessi.

Regole del budget e regolazione

budget_tokens deve soddisfare questi vincoli:

• Minimo di 1.024 token. L'API rifiuta valori inferiori.
• Inferiore a max_tokens. I token di ragionamento contano ai fini del limite max_tokens per il turno, quindi il budget deve lasciare spazio per la risposta finale. L'unica eccezione è il ragionamento interlacciato, dove budget_tokens può superare max_tokens perché il budget copre tutti i blocchi di ragionamento all'interno di un singolo turno dell'assistente.
• Nessun pre-riscaldamento della cache. Poiché budget_tokens deve essere inferiore a max_tokens, il ragionamento esteso non può essere combinato con max_tokens: 0 (pre-riscaldamento della cache).

Il budget è un obiettivo piuttosto che un limite rigido. L'utilizzo effettivo dei token varia in base al compito, e Claude può smettere di ragionare ben prima che il budget sia esaurito; max_tokens rimane il tetto massimo rigido sull'output totale.

Su Claude Opus 4.5, l'unico modello con solo ragionamento esteso che supporta l'effort, l'effort modella la risposta complessiva mentre budget_tokens imposta la profondità del ragionamento; imposta entrambi.

Per regolare il budget:

• Adatta il punto di partenza al compito. Per compiti semplici, inizia vicino al minimo di 1.024 token e aumenta in modo incrementale per trovare l'intervallo ottimale per il tuo caso d'uso. Per compiti complessi, inizia con un budget più ampio di 16.000 token o più e regola in base alle tue esigenze di latenza e qualità. Budget più elevati consentono un ragionamento più completo, con rendimenti decrescenti che dipendono dal compito, e al costo di una maggiore latenza. Per compiti critici, testa impostazioni diverse per trovare il giusto equilibrio.
• Per budget di ragionamento superiori a 32k, usa l'elaborazione batch per evitare problemi di rete. Spingere il modello a pensare oltre i 32k token produce richieste di lunga durata che possono incorrere in timeout di sistema e limiti di connessioni aperte.

Per tenere traccia di quanto ti costa effettivamente un budget, monitora il campo usage.output_tokens_details.thinking_tokens nella risposta, che riporta quanti dei token di output fatturati erano ragionamento interno. In streaming, questa suddivisione appare solo nell'evento finale message_delta.

Quando sei pronto ad abbandonare i budget manuali, consulta Migrazione al ragionamento adattivo.

Ragionamento interlacciato in modalità manuale

L'"interleaved thinking" (ragionamento interlacciato) consente a Claude di pensare tra le chiamate agli strumenti all'interno di un singolo turno dell'assistente, ragionando su ogni risultato degli strumenti prima di decidere cosa fare dopo. Per il concetto, la struttura del turno e il comportamento sui modelli con ragionamento adattivo, consulta ragionamento interlacciato nella panoramica sul ragionamento. Questa sezione spiega come abilitarlo quando usi il ragionamento manuale type: "enabled".

Su Claude Opus 4.5, Claude Sonnet 4.5 e sui modelli Claude 4 precedenti, aggiungi l'header beta interleaved-thinking-2025-05-14 alla tua richiesta API.

La generazione 4.6 si divide in modalità manuale:

• Claude Sonnet 4.6: l'header beta con type: "enabled" manuale è ancora funzionante ma deprecato. Preferisci il ragionamento adattivo, che interlaccia automaticamente senza alcun header.
• Claude Opus 4.6: la modalità manuale non ha alcun ragionamento interlacciato. Solo la sua modalità adattiva interlaccia, quindi passa a thinking: {type: "adaptive"} se hai bisogno di ragionamento tra le chiamate agli strumenti su questo modello.

Claude Haiku 4.5 non supporta il ragionamento interlacciato. Sulla Claude API, l'header beta viene accettato ma ignorato.

Altre due considerazioni per il ragionamento interlacciato in modalità manuale:

• budget_tokens può superare max_tokens in questo caso; le regole del budget spiegano questa eccezione.
• Il ragionamento interlacciato è supportato solo per gli strumenti usati tramite la Messages API.

Il modo in cui le piattaforme trattano l'header beta differisce. La Claude API e Claude Platform on AWS accettano interleaved-thinking-2025-05-14 su qualsiasi modello e lo ignorano dove non è supportato. L'accettazione non equivale all'effetto: sui modelli che rifiutano type: "enabled" (4.7 e successivi) o che non dispongono dell'interlacciamento in modalità manuale (Claude Opus 4.6), l'header non ha alcun effetto in modalità manuale; lì il ragionamento adattivo interlaccia automaticamente.

Le piattaforme gestite dai partner (Amazon Bedrock e Google Cloud) accettano allo stesso modo l'header su qualsiasi modello senza restituire un errore, e lo ignorano sui modelli che non supportano il ragionamento interlacciato.

Struttura del turno in modalità manuale

Le regole generali sulla struttura del turno, inclusi il ciclo di uso degli strumenti a turno singolo, la gestione dei conflitti a metà turno e l'attivazione/disattivazione del ragionamento tra i turni, si trovano in Ragionamento con l'uso degli strumenti.

La modalità manuale aggiunge un requisito: il turno finale dell'assistente di una richiesta con ragionamento abilitato deve iniziare con un blocco di ragionamento (il ragionamento adattivo elimina tale requisito). Modificare la configurazione del ragionamento tra i turni invalida anche la cache dei prompt; consulta la sezione seguente.

Cache dei prompt in modalità manuale

La modalità manuale aggiunge una regola al comportamento di caching indipendente dalla modalità descritto in ragionamento e cache dei prompt: modificare budget_tokens tra le richieste invalida i breakpoint della cache, proprio come il cambio di modalità di ragionamento, perché il valore del budget viene reso nel prompt. I breakpoint a livello di messaggio falliscono sempre dopo una modifica del budget; se falliscono anche i breakpoint degli strumenti e del prompt di sistema dipende da dove il modello rende la configurazione.

In pratica, scegli un budget e mantienilo stabile per tutta la durata di una conversazione in cache. Eseguire una conversazione multi-turno con caching a livello di messaggio su Claude Sonnet 4.6 e modificare il budget alla terza richiesta da 4.000 a 8.000 token mostra direttamente l'invalidazione:

First request - establishing cache
First response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 17, output_tokens: 700 }

Second request - same thinking parameters (cache hit expected)
Second response usage: { cache_creation_input_tokens: 0, cache_read_input_tokens: 1370, input_tokens: 303, output_tokens: 874 }

Third request - different thinking budget (cache miss expected)
Third response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 747, output_tokens: 619 }

La terza richiesta ricrea la cache (cache_creation_input_tokens=1370, cache_read_input_tokens=0) perché il budget è cambiato tra le richieste. Per una versione eseguibile dello stesso esperimento in modalità adattiva, dove il livello di effort svolge il ruolo nella cache che budget_tokens svolge qui, consulta Cache dei prompt nella pagina sull'orientamento del ragionamento.

Meccaniche condivise

La maggior parte del comportamento del ragionamento è indipendente dalla modalità ed è documentata una sola volta nella pagina Ragionamento. Tutto ciò che è descritto lì si applica anche in modalità manuale:

• Controllo della visualizzazione del ragionamento
• Streaming del ragionamento
• Ragionamento con l'uso degli strumenti, inclusa la conservazione dei blocchi di ragionamento
• Ragionamento e cache dei prompt
• Ragionamento e finestra di contesto
• Crittografia del ragionamento
• Prezzi (nella pagina Orientare il ragionamento)

Migrazione al ragionamento adattivo

Se il tuo modello supporta solo il ragionamento esteso (Claude Sonnet 4.5, Claude Opus 4.5, Claude Haiku 4.5 e i modelli Claude 4 precedenti), non è necessaria alcuna azione ora: il ragionamento adattivo non è disponibile lì, e type: "adaptive" restituisce un errore 400. Mantieni budget_tokens finché non passi a un modello che supporta il ragionamento adattivo, quindi applica la mappatura che segue.

Devi migrare da type: "enabled" se:

• Usi Claude Opus 4.6 o Claude Sonnet 4.6, dove budget_tokens è deprecato.
• Usi Claude 4.7 o un modello successivo, come Claude Opus 5.5, Claude Sonnet 5, Claude Sonnet 5.5 o Claude Fable 5.1, dove type: "enabled" restituisce un errore 400.

La mappatura è minima: rimuovi budget_tokens, imposta thinking: {type: "adaptive"} e controlla la profondità del ragionamento con output_config: {effort: ...} invece di un budget di token.

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 16000,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 10000
  }
}

diventa:

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 16000,
  "thinking": {
    "type": "adaptive"
  },
  "output_config": {
    "effort": "high"
  }
}

effort: "high" corrisponde al valore predefinito dell'API; appare qui solo per mostrare dove risiede ora il controllo della profondità, e ometterlo produce un comportamento identico.

Aspettati una differenza comportamentale, non solo un cambiamento di sintassi. Con un budget fisso, Claude pensa a ogni richiesta. Con il ragionamento adattivo, Claude decide se e quanto pensare a ogni richiesta, e con impostazioni di effort più basse può saltare del tutto il ragionamento su input semplici. Puoi anche rimuovere l'header beta interleaved-thinking-2025-05-14 dopo la migrazione: il ragionamento adattivo interlaccia automaticamente, e la Claude API ignora l'header su questi modelli. Cambia anche la conservazione dei blocchi di ragionamento: Claude Opus 4.5 e i modelli numerati 4.6 e superiori mantengono i blocchi di ragionamento dei turni precedenti nel contesto e li fatturano come input, mentre Claude Sonnet 4.5, Claude Haiku 4.5 e i modelli precedenti li rimuovevano; consulta conservazione dei blocchi di ragionamento per modello.

Il cambio di modalità è una modifica della configurazione del ragionamento, quindi la prima richiesta dopo il cambio invalida i breakpoint della cache, come descritto in Cache dei prompt in modalità manuale.

Per una guida completa, consulta ragionamento adattivo, effort e la guida alla migrazione dei modelli.

Prossimi passi