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



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 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 una chiamata di strumento e l'altra, rendendolo particolarmente efficace per i flussi di lavoro agentici.



Come utilizzare 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, il passaggio tra le modalità di pensiero adaptive ed enabled/disabled interrompe i breakpoint della cache per i messaggi. I prompt di sistema e le definizioni degli strumenti rimangono in cache indipendentemente dai cambi 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 offrono 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 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 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 sul 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 e forniscono un ragionamento approfondito particolarmente utile per scopi di prompt engineering. Claude Mythos Preview riepiloga a partire 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 pensiero viene restituito nelle risposte dell'API. Accetta due valori:

• "summarized": I blocchi di thinking contengono testo di pensiero riassunto. Consulta Pensiero 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 pensiero completo crittografato per la continuità multi-turno (consulta Crittografia del pensiero). Questa è l'impostazione predefinita su Claude Fable 5, Claude Mythos 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 pensiero agli utenti. Il vantaggio principale è un tempo più rapido per il primo token di testo durante lo streaming: il server salta completamente lo streaming dei token di pensiero e fornisce solo la signature, quindi la risposta testuale finale inizia lo streaming prima.

Ecco alcune considerazioni importanti per il pensiero omesso:

• Ti vengono comunque addebitati i token di pensiero completi. L'omissione riduce la latenza, non il costo.
• Se passi i blocchi di thinking nelle conversazioni multi-turno, passali invariati. Il server decrittografa la signature per ricostruire il pensiero 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 pensiero 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:

• Quando si utilizzano risposte in streaming, 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 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 signature sono compatibili tra le piattaforme (API di Claude, Amazon Bedrock e Vertex AI). 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, e thinking.display funziona allo stesso modo degli altri modelli: "summarized" restituisce un riassunto leggibile del ragionamento, e con "omitted" (il valore predefinito su questi modelli), le risposte includono comunque blocchi thinking, ma il campo thinking è una stringa vuota. Per la struttura della risposta dei blocchi di pensiero, consulta il riferimento dell'API Messages.

Quando continui una conversazione sullo stesso modello, passa ogni 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.

I blocchi di pensiero sono legati al modello che li ha prodotti. Gli altri modelli li ignorano silenziosamente invece di rifiutare la richiesta, ma i blocchi ignorati aggiungono comunque token di input, quindi quando cambi modello, ad esempio dopo un fallback per rifiuto del classificatore, rimuovi i blocchi thinking e redacted_thinking dai turni precedenti dell'assistente. Le eccezioni, trattate in Credito di fallback, sono i retry con credito di fallback (che devono riprodurre il corpo della richiesta rifiutata senza modifiche) e i blocchi fallback da un fallback a metà output (che rimangono dove sono apparsi).

Su Claude Fable 5, una richiesta che tenta di estrarre il ragionamento interno del modello come parte del testo di risposta può essere rifiutata con stop_details.category: "reasoning_extraction". Le applicazioni che necessitano di visibilità sul ragionamento dovrebbero leggere i blocchi thinking descritti in questa sezione invece di richiedere il ragionamento nella risposta tramite prompt. 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 di 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. Il passaggio tra le modalità adaptive ed 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