Pensiero adattivo

Il pensiero adattivo è il modo consigliato per utilizzare il pensiero esteso con Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 e Claude Sonnet 4.6. Su Claude Fable 5 e Claude Mythos 5, il pensiero è sempre abilitato e non può essere disabilitato; il pensiero adattivo è l'unica modalità di pensiero. Su Claude Mythos Preview, il pensiero adattivo è la modalità predefinita e si applica automaticamente ogni volta che thinking non è impostato. Invece di impostare manualmente un budget di token per il pensiero, il pensiero adattivo consente a Claude di determinare dinamicamente quando e quanto utilizzare il pensiero esteso in base alla complessità di ciascuna richiesta. Su Claude Opus 4.8 e Claude Opus 4.7, il pensiero adattivo è l'unica modalità di pensiero supportata; thinking: {type: "enabled", budget_tokens: N} manuale non è più accettato. Su Claude Sonnet 5, il pensiero adattivo è attivo per impostazione predefinita; passa thinking: {type: "disabled"} per disattivarlo, e {type: "enabled", budget_tokens: N} manuale viene rifiutato con un errore 400.



Modelli supportati

Il pensiero adattivo è supportato sui seguenti modelli:

• Claude Fable 5 (claude-fable-5) e Claude Mythos 5 (claude-mythos-5), il pensiero adattivo è sempre attivo; thinking: {type: "disabled"} non è supportato
• Claude Mythos Preview (claude-mythos-preview), il pensiero adattivo è l'impostazione predefinita; thinking: {type: "disabled"} non è supportato
• Claude Opus 4.8 (claude-opus-4-8), il pensiero adattivo è l'unica modalità di pensiero supportata. Il pensiero è disattivato a meno che non imposti esplicitamente thinking: {type: "adaptive"} nella tua richiesta; thinking: {type: "enabled"} manuale viene rifiutato con un errore 400.
• Claude Opus 4.7 (claude-opus-4-7), il pensiero adattivo è l'unica modalità di pensiero supportata. Il pensiero è disattivato a meno che non imposti esplicitamente thinking: {type: "adaptive"} nella tua richiesta; thinking: {type: "enabled"} manuale viene rifiutato con un errore 400.
• Claude Opus 4.6 (claude-opus-4-6)
• Claude Sonnet 5 (claude-sonnet-5), il pensiero adattivo è attivo per impostazione predefinita; {type: "enabled"} manuale viene rifiutato con un errore 400.
• Claude Sonnet 4.6 (claude-sonnet-4-6)



Come funziona il pensiero adattivo

In modalità adattiva, il pensiero è opzionale per il modello. Claude valuta la complessità di ciascuna richiesta e determina se e quanto utilizzare il pensiero esteso. Al livello di effort predefinito (high), Claude pensa quasi sempre. A livelli di effort inferiori, Claude può saltare il pensiero per problemi più semplici.

Il pensiero adattivo abilita inoltre automaticamente il pensiero intercalato. Ciò significa che Claude può pensare tra le chiamate agli strumenti, rendendolo particolarmente efficace per i flussi di lavoro agentici.



Come usare il pensiero adattivo

Imposta thinking.type su "adaptive" nella tua richiesta API:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=[
        {
            "role": "user",
            "content": "Explain why the sum of two even numbers is always even.",
        }
    ],
)

for block in response.content:
    if block.type == "thinking":
        print(f"\nThinking: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")



Pensiero adattivo con il parametro effort

Puoi combinare il pensiero adattivo con il parametro effort per guidare la quantità di pensiero che Claude esegue. Il livello di effort funge da guida soft per l'allocazione del pensiero di Claude:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "What is the capital of France?"}],
)

print(response.content[0].text)



Streaming con il pensiero adattivo

Il pensiero adattivo funziona perfettamente con lo streaming. I blocchi di pensiero vengono trasmessi in streaming tramite eventi thinking_delta proprio come nella modalità di pensiero manuale:

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
) as stream:
    for event in stream:
        if event.type == "content_block_start":
            print(f"\nStarting {event.content_block.type} block...")
        elif event.type == "content_block_delta":
            if event.delta.type == "thinking_delta":
                print(event.delta.thinking, end="", flush=True)
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)



Pensiero adattivo vs manuale vs disabilitato



Considerazioni importanti



Modifiche alla validazione

Quando si utilizza il pensiero adattivo, i turni precedenti dell'assistente non devono necessariamente iniziare con blocchi di pensiero. Questo è più flessibile rispetto alla modalità manuale, in cui l'API impone che i turni con pensiero abilitato inizino con un blocco di pensiero.



Cache dei prompt

Le richieste consecutive che utilizzano il pensiero adaptive preservano i breakpoint della cache dei prompt. Tuttavia, passare tra le modalità di pensiero adaptive e enabled/disabled interrompe i breakpoint della cache per i messaggi. I prompt di sistema e le definizioni degli strumenti rimangono in cache indipendentemente dai cambiamenti di modalità.



Regolazione del comportamento del pensiero

Il comportamento di attivazione del pensiero adattivo è influenzabile tramite prompt. Se Claude pensa più o meno spesso di quanto desideri, puoi aggiungere indicazioni al tuo prompt di sistema:

Extended thinking adds latency and should only be used when it
will meaningfully improve answer quality, typically for problems
that require multi-step reasoning. When in doubt, respond directly.

Per incoraggiare invece il pensiero, usa una frase come:

This task involves multi-step reasoning. Think carefully before responding.

L'efficacia della guida può essere sensibile alla formulazione esatta. Se una formulazione non produce il comportamento desiderato, prova una variante più diretta.

Puoi anche guidare il pensiero su base per-messaggio dal turno dell'utente. Aggiungere "Please think hard before responding." a un messaggio utente incoraggia Claude a pensare in quel turno; "Answer directly without deliberating." lo sopprime. Questo funziona indipendentemente dal prompt di sistema ed è utile quando solo alcune richieste in una conversazione giustificano un ragionamento esteso.



Controllo dei costi

Usa max_tokens come limite rigido sull'output totale (pensiero + testo di risposta). Il parametro effort fornisce una guida soft aggiuntiva su quanto pensiero Claude alloca. Insieme, questi ti danno un controllo efficace sui costi.

Ai livelli di effort high e max, Claude può pensare in modo più esteso e può essere più probabile che esaurisca il budget di max_tokens. Se osservi stop_reason: "max_tokens" nelle risposte, considera di aumentare max_tokens per dare al modello più spazio, o di abbassare il livello di effort.



Lavorare con i blocchi di pensiero

I seguenti concetti si applicano a tutti i modelli che supportano il pensiero esteso, indipendentemente dal fatto che tu utilizzi la modalità adattiva o manuale.



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.



Controllo della 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.

thinking = {
    "type": "adaptive",
    "display": "summarized",
}

Per esempi di codice e comportamento dello streaming con display: "omitted", consulta Controllo della visualizzazione del pensiero nella pagina del pensiero esteso. Gli esempi lì utilizzano type: "enabled"; con il pensiero adattivo, usa:

thinking = {"type": "adaptive", "display": "omitted"}



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.



Output del pensiero su Claude Fable 5 e Claude Mythos 5

Su Claude Fable 5 e Claude Mythos 5, la catena di pensiero grezza non viene mai restituita. I blocchi di pensiero che ricevi sono blocchi thinking regolari, non redacted_thinking. L'impostazione thinking.display funziona allo stesso modo degli altri modelli:

• "summarized" restituisce un riassunto leggibile del ragionamento.
• "omitted" (il valore predefinito su questi modelli) include comunque blocchi thinking nelle risposte, ma il loro campo thinking è una stringa vuota.

Per la forma della risposta dei blocchi di pensiero, consulta il riferimento dell'API Messages.

Quando continui una conversazione sullo stesso modello, passa ciascun blocco di pensiero all'API esattamente come ricevuto, inclusi i blocchi il cui campo thinking è vuoto. Non modificarli né ricostruirli. Leggere il testo del riassunto per la visualizzazione va bene: l'API rifiuta i blocchi il cui contenuto è stato modificato, non i blocchi che hai letto.

Quando cambi modello, ad esempio dopo un fallback per rifiuto del classificatore, rimuovi i blocchi thinking e redacted_thinking dai turni precedenti dell'assistente. I blocchi di pensiero sono legati al modello che li ha prodotti. Altri modelli li ignorano silenziosamente invece di rifiutare la richiesta, ma i blocchi ignorati aggiungono comunque token di input.

Due eccezioni, trattate in Credito di fallback:

• I tentativi con credito di fallback devono riprodurre il corpo della richiesta rifiutata senza modifiche.
• I blocchi fallback da un fallback a metà output rimangono dove sono apparsi.

Per ottenere visibilità sul ragionamento del modello, leggi i blocchi thinking descritti in questa sezione invece di richiedere il ragionamento nel testo della risposta. Su Claude Fable 5, una richiesta che tenta di estrarre il ragionamento interno del modello come parte del testo della risposta può essere rifiutata con stop_details.category: "reasoning_extraction". Consulta Categorie di rifiuto per il riferimento dei campi e le indicazioni sulla gestione.



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



Argomenti aggiuntivi

La pagina del pensiero esteso tratta diversi argomenti in modo più dettagliato con esempi di codice specifici per modalità:

• Uso degli strumenti con il pensiero: le stesse regole si applicano al pensiero adattivo: preserva i blocchi di pensiero tra le chiamate agli strumenti e tieni presente le limitazioni di tool_choice quando il pensiero è attivo.
• Cache dei prompt: con il pensiero adattivo, le richieste consecutive che utilizzano la stessa modalità di pensiero preservano i breakpoint della cache. Passare tra le modalità adaptive e enabled/disabled interrompe i breakpoint della cache per i messaggi (i prompt di sistema e le definizioni degli strumenti rimangono in cache).
• Finestre di contesto: come i token di pensiero interagiscono con max_tokens e i limiti della finestra di contesto.



Passaggi successivi