Claude Platform Docs
MessaggiRagionamento

Ragionamento esteso

Configura il ragionamento esteso manuale con un budget fisso budget_tokens sui modelli Claude che lo supportano, e migra al ragionamento adattivo.

Ragionamento esteso è una funzionalità legacy

Il ragionamento esteso (thinking.type: "enabled" con budget_tokens) è deprecato. I modelli Claude 4.7 e successivi non lo supportano e rifiutano le richieste che lo usano, restituendo un errore 400.

Alternativa consigliata
Ragionamento adattivoModalità di ragionamento in cui Claude decide, per ogni richiesta, se ragionare e quanto.

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

Modelli supportati

La disponibilità del ragionamento esteso per ciascun modello, inclusi i modelli in cui il ragionamento esteso è l’unica modalità, è indicata 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 il numero di token che Claude può utilizzare per il suo processo di ragionamento interno. Budget più ampi possono migliorare la qualità delle risposte 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 vengono conteggiati nel limite max_tokens per il turno, quindi il budget deve lasciare spazio per la risposta finale. L’unica eccezione è il ragionamento interlacciato in modalità manuale, dove budget_tokens può superare max_tokens perché il budget copre tutti i blocchi di ragionamento all’interno di un 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 potrebbe smettere di ragionare ben prima che il budget sia esaurito; max_tokens rimane il limite massimo assoluto sull’output totale.

Su Claude Opus 4.5, l’unico modello che supporta solo il ragionamento esteso e 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 gradualmente 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 regolalo 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 latenza maggiore. Per compiti critici, testa diverse impostazioni 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 ragionare tra le chiamate agli strumenti all’interno di un singolo turno dell’assistente, valutando ogni risultato dello strumento prima di decidere cosa fare dopo. Per il concetto, la struttura del turno e il suo comportamento sui modelli con ragionamento adattivo, consulta ragionamento interlacciato nella panoramica del ragionamento. Questa sezione spiega come abilitarlo quando usi il ragionamento manuale type: "enabled".

Su Claude Opus 4.5, Claude Sonnet 4.5 (deprecato) 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:

Il modo in cui le piattaforme gestiscono l’header beta varia. La Claude API, Claude Platform on AWS e Claude Models on Google Cloud (Anthropic managed) 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’interleaving in modalità manuale (Claude Opus 4.6), l’header non ha alcun effetto in modalità manuale; lì l’“adaptive thinking” (ragionamento adattivo) esegue l’interleaving automaticamente.

Le piattaforme gestite dai partner, Claude Models on Google Cloud (Google managed) e Amazon Bedrock (bedrock-mantle), accettano 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). Anche la modifica della configurazione del ragionamento tra i turni invalida la cache dei prompt; consulta la sezione seguente.

Cache dei prompt in modalità manuale

La modalità manuale aggiunge una regola al comportamento della cache 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 cache 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:

Output
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. Queste sezioni si applicano anche in modalità manuale:

Migrazione al ragionamento adattivo

Se il tuo modello supporta solo il ragionamento esteso, non è necessaria alcuna azione. Questi modelli sono Claude Sonnet 4.5 (deprecato), Claude Opus 4.5, Claude Haiku 4.5 e i modelli Claude 4 precedenti. Il ragionamento adattivo non è disponibile su questi modelli, e type: "adaptive" restituisce un errore 400. Mantieni budget_tokens finché non passi a un modello che supporta il ragionamento adattivo, quindi applica la corrispondenza descritta di seguito.

Devi migrare da type: "enabled" se:

  • Usi Claude Opus 4.6 o Claude Sonnet 4.6, dove budget_tokens è deprecato.
  • Usi un modello numerato 4.7 o superiore, dove type: "enabled" restituisce un errore 400. Alcuni esempi sono Claude Opus 5.5, Claude Sonnet 5, Claude Sonnet 5.5, Claude Fable 5.2, Claude Fable 5.1 e Claude Haiku 5.5.

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" è il valore predefinito su Claude Sonnet 4.6, quindi ometterlo qui produce un comportamento identico; compare solo per mostrare dove si trova il controllo della profondità in modalità adattiva. Claude Opus 5.5 e Claude Haiku 5.5 hanno come valore predefinito "medium", mentre gli altri modelli che supportano l’effort hanno come valore predefinito "high" (consulta Livelli di effort).

Aspettati una differenza di comportamento, non solo un cambiamento di sintassi. Con un budget fisso, Claude ragiona su ogni richiesta. Con il ragionamento adattivo, Claude determina se e quanto ragionare su ciascuna richiesta, e con impostazioni di effort più basse potrebbe saltare completamente il ragionamento sugli input semplici. Dopo la migrazione puoi anche rimuovere l’header beta interleaved-thinking-2025-05-14: il ragionamento adattivo si 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 nel contesto i blocchi di ragionamento dei turni precedenti e li fatturano come input. Claude Sonnet 4.5 (deprecato), Claude Haiku 4.5 e i modelli precedenti li rimuovono. 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, Effort e Guide alla migrazione.

Prossimi passi

Scopri come funziona il ragionamento: blocchi, visualizzazione, streaming e uso degli strumenti.

Lascia che Claude determini quando e quanto ragionare a ogni richiesta.

Conserva i blocchi di ragionamento e gestisci il ragionamento tra chiamate agli strumenti e turni.

Disponibilità

Ragionamento esteso
Stato
Legacy
API
  • Messages API
  • Managed Agents Non supportato
Modelli
  • Claude Mythos Preview
  • Claude Opus 4.6 Deprecato
  • Claude Opus 4.5
  • Claude Sonnet 4.6 Deprecato
  • Claude Sonnet 4.5
  • Claude Haiku 4.5

Questa pagina ti è stata utile?