Orientare il ragionamento

Il "thinking" (ragionamento) di Claude è adattivo: il modello valuta ogni richiesta e determina se ragionare e quanto. Tu stabilisci un intento, specifichi facoltativamente l'"effort" (sforzo) e il modello alloca il ragionamento dove ritiene che possa essere utile.

Questo rende il ragionamento particolarmente adatto a carichi di lavoro che mescolano richieste banali e complesse, e a flussi di lavoro agentici a lungo orizzonte in cui la giusta quantità di ragionamento varia da un passaggio all'altro.

Per scoprire come attivare il ragionamento, come leggerne l'output e per informazioni sull'output del ragionamento su Claude Fable 5 e Claude Mythos 5, consulta la panoramica sul Ragionamento. Questa pagina spiega come Claude determina quando ragionare, come orientare il ragionamento e i meccanismi di caching, costo e prezzo che ne derivano.

Come Claude determina quando ragionare

Il ragionamento è facoltativo per il modello. A ogni richiesta, Claude valuta la complessità dell'input e determina se un ragionamento più approfondito migliorerebbe la risposta. Una semplice domanda fattuale può ricevere una risposta diretta senza alcun blocco di ragionamento; un problema matematico in più passaggi o un'attività di debug complessa attivano un ragionamento più approfondito.

La decisione avviene per singola richiesta. La stessa conversazione può contenere turni con e senza ragionamento, e un turno in cui Claude ha scelto di non pensare non contiene alcun blocco di ragionamento. Non costruire logica applicativa che presupponga che ogni turno dell'assistente inizi con uno.

Il controllo principale su questa decisione è il parametro effort, che funge da indicazione non vincolante su quanto Claude debba essere disposto a pensare e con quale profondità; consulta Livelli di effort in questa pagina per sapere cosa fa ciascun livello.

Se vuoi che Claude pensi meno spesso, abbassa il livello di effort prima di ricorrere all'orientamento basato sui prompt.

Il ragionamento si alterna inoltre automaticamente con il "tool use" (uso degli strumenti): Claude può ragionare tra una chiamata a uno strumento e l'altra, riflettendo su ogni risultato prima di determinare cosa fare dopo (ragionamento interlacciato). Non hai bisogno di un header beta né di alcuna configurazione aggiuntiva per questo.

Per il quadro completo di come interagiscono la configurazione del ragionamento e il parametro effort, consulta Ragionamento ed effort.

Orientare la frequenza con cui Claude pensa

Il fatto che Claude pensi o meno in un determinato turno è influenzabile tramite prompt. L'effort imposta l'atteggiamento generale, ma puoi anche modellare direttamente la decisione con indicazioni in linguaggio naturale, sia globalmente nel "system prompt" (prompt di sistema) sia per singolo messaggio dal turno dell'utente.

Usa le due leve insieme in questo ordine:

1. Imposta il livello di effort che corrisponde all'equilibrio predefinito tra qualità e latenza del tuo carico di lavoro.
2. Aggiungi indicazioni nel prompt solo se l'attivazione del ragionamento di Claude non corrisponde ancora alle tue esigenze a quel livello.

Per indicazioni più ampie sul prompting con il ragionamento, consulta sfruttare le capacità di ragionamento e di ragionamento interlacciato.

Livelli di effort

L'effort è la leva di orientamento principale per il ragionamento. Ogni livello imposta un valore predefinito diverso per la frequenza e la profondità con cui Claude pensa:

A ogni livello, Claude determina per ciascuna richiesta se ragionare. In un ciclo di uso degli strumenti, la prima richiesta dopo un nuovo input dell'utente contiene tipicamente la maggior parte del ragionamento, e le richieste successive che elaborano solo i risultati degli strumenti possono saltare il ragionamento, anche a xhigh e max. Il ragionamento per richiesta tende inoltre a diminuire man mano che una conversazione si allunga. Nessun livello garantisce un blocco di ragionamento a ogni richiesta.

Questa tabella descrive come ciascun livello modifica il comportamento del ragionamento. Per indicazioni su quale livello scegliere per un determinato carico di lavoro, incluse le raccomandazioni per modello, consulta Quando regolare il parametro effort nella pagina dell'effort.

L'effort si imposta in output_config.effort, non all'interno dell'oggetto thinking; per esempi completi in ogni linguaggio, consulta Effort.

{
  "model": "claude-opus-5-5",
  "max_tokens": 4096,
  "output_config": { "effort": "medium" },
  "messages": [{ "role": "user", "content": "..." }]
}

La disponibilità dei livelli varia in base al modello; la tabella di disponibilità dell'effort nella pagina dell'effort è il riferimento autorevole per sapere quali livelli supporta ciascun modello.

Indicazioni nel prompt di sistema

Le indicazioni nel prompt di sistema spostano la soglia di ragionamento di Claude per ogni richiesta della conversazione. Se Claude pensa più spesso di quanto richieda il tuo carico di lavoro, aggiungi al prompt di sistema indicazioni come questa:

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

Per incoraggiare invece il ragionamento, usa una frase come:

This task involves multistep reasoning. Think carefully before responding.

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

Orientamento per singolo messaggio

Puoi anche orientare il ragionamento per singolo messaggio dal turno dell'utente, indipendentemente dal prompt di sistema. Aggiungere "Please think hard before responding." a un messaggio dell'utente incoraggia Claude a ragionare in quel turno; "Answer directly without deliberating." lo scoraggia.

L'orientamento per singolo messaggio è utile quando solo alcune richieste di una conversazione giustificano un ragionamento esteso. Un harness per agenti, ad esempio, può aggiungere la frase di incoraggiamento nei passaggi di pianificazione e la frase di scoraggiamento nelle conferme di routine, senza toccare il prompt di sistema né modificare alcun parametro della richiesta tra un turno e l'altro.

Su Claude Haiku 5.5, la frase di scoraggiamento non riduce in modo affidabile il ragionamento. Sulla Claude API e su Google Cloud, esegui i turni di routine su quel modello con meno ragionamento usando invece una modifica dell'effort per messaggio (beta), che preserva anche la cache dei prompt.

Verifica l'orientamento sul tuo carico di lavoro

L'orientamento basato sui prompt modifica il comportamento del modello, quindi trattalo come qualsiasi altra modifica al prompt: misura prima di rilasciare. Esegui un campione rappresentativo del tuo traffico con e senza le indicazioni, e confronta la frequenza con cui si attiva il ragionamento (la presenza di blocchi di ragionamento nelle risposte), l'utilizzo di token di output, la latenza e la qualità delle risposte nei casi che ti interessano.

Meccanismi

Tre meccanismi derivano dal fatto che Claude gestisce il proprio ragionamento: la validazione dei turni, la cache dei prompt e il modo in cui limiti i costi.

Validazione dei turni

I turni dell'assistente non devono necessariamente iniziare con un blocco di ragionamento. (I modelli che usano un budget di ragionamento manuale legacy impongono che l'ultimo turno dell'assistente di una richiesta con ragionamento abilitato inizi con uno; consulta Struttura del turno in modalità manuale.)

Per le applicazioni multi-turno, questo significa che puoi ripassare la cronologia della conversazione in qualunque forma tu l'abbia:

• I turni dell'assistente in cui Claude ha scelto di non pensare sono cronologia valida così come sono.
• Puoi riprendere una conversazione iniziata senza ragionamento, o che usava una configurazione di ragionamento diversa, senza riscriverne la cronologia.
• La cronologia assemblata da fonti miste non richiede che i blocchi di ragionamento vengano reinseriti all'inizio di ogni turno dell'assistente per superare la validazione.

L'allentamento riguarda la validazione, non ciò che dovresti inviare. Quando disponi di blocchi di ragionamento, ripassali senza modifiche, in particolare durante l'uso degli strumenti, dove contengono il ragionamento alla base delle chiamate di strumento di Claude. Consulta la panoramica Ragionamento per le regole complete.

Cache dei prompt

Le richieste consecutive che mantengono la stessa configurazione di ragionamento e lo stesso livello di effort preservano la "prompt caching" (cache dei prompt); consulta Ragionamento e cache dei prompt per le regole complete. Il valore di effort risolto viene inserito nel prompt, quindi modificarlo tra una richiesta e l'altra invalida i breakpoint della cache, proprio come fa la modifica del parametro legacy budget_tokens sui modelli che lo usano. Impostare esplicitamente effort sul valore predefinito del modello equivale a ometterlo e non invalida la cache.

La conseguenza pratica: scegli una configurazione di ragionamento e un effort di primo livello per ogni conversazione e mantienili. Se alcuni turni richiedono più o meno ragionamento, usa una modifica dell'effort per messaggio (beta) sui modelli che la supportano, oppure orienta con il prompting per singolo messaggio. Entrambi lasciano intatti i breakpoint della cache precedenti, cosa che invece non avviene con una modifica alla configurazione di ragionamento o all'effort di primo livello.

L'esempio seguente dimostra l'invalidazione con uno script multi-turno che puoi eseguire tu stesso:

import requests

client = Anthropic()


def fetch_article_content(url):
    text = requests.get(url).text
    lines = (line.strip() for line in text.splitlines())
    return "\n".join(line for line in lines if line)


# Recupera il contenuto dell'articolo
book_url = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"
book_content = fetch_article_content(book_url)
# Usa solo il testo sufficiente per la cache (primi capitoli)
LARGE_TEXT = book_content[:10000]

# Nessun prompt di sistema: la cache è invece nei messaggi
MESSAGES = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": LARGE_TEXT,
                "cache_control": {"type": "ephemeral"},
            },
            {"type": "text", "text": "Analyze the tone of this passage."},
        ],
    }
]

# Prima richiesta: crea la cache
print("First request - establishing cache")
response1 = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=MESSAGES,
)

print(f"First response usage: {response1.usage}")

MESSAGES.append({"role": "assistant", "content": response1.content})
MESSAGES.append({"role": "user", "content": "Analyze the characters in this passage."})

# Seconda richiesta: stessa configurazione (cache hit prevista)
print("\nSecond request - same configuration (cache hit expected)")
response2 = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=MESSAGES,
)

print(f"Second response usage: {response2.usage}")

MESSAGES.append({"role": "assistant", "content": response2.content})
MESSAGES.append({"role": "user", "content": "Analyze the setting in this passage."})

# Terza richiesta: livello di effort diverso (cache miss prevista)
print("\nThird request - different effort level (cache miss expected)")
response3 = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "low"},
    messages=MESSAGES,
)

print(f"Third response usage: {response3.usage}")

First request - establishing cache
First response usage: { cache_creation_input_tokens: 3546, cache_read_input_tokens: 0, input_tokens: 15, output_tokens: 1033 }

Second request - same configuration (cache hit expected)
Second response usage: { cache_creation_input_tokens: 0, cache_read_input_tokens: 3546, input_tokens: 1062, output_tokens: 1630 }

Third request - different effort level (cache miss expected)
Third response usage: { cache_creation_input_tokens: 3546, cache_read_input_tokens: 0, input_tokens: 2706, output_tokens: 1468 }

Controllo dei costi

Non imposti un budget di token per il ragionamento. Due controlli limitano i costi:

• max_tokens è un limite rigido sull'output totale della richiesta, ragionamento e testo della risposta combinati. Claude non genera mai oltre questo limite. In un ciclo di uso degli strumenti, ogni richiesta del turno ha il proprio max_tokens, quindi non limita la spesa dell'intero turno.
• effort è un'indicazione non vincolante su quanta parte di quell'output Claude alloca al ragionamento. Modella il comportamento ma non garantisce un conteggio di token.

Poiché il ragionamento viene conteggiato in max_tokens, impostalo abbastanza alto da lasciare spazio sia al ragionamento sia alla risposta. Un max_tokens dimensionato per una risposta senza ragionamento è spesso troppo piccolo una volta che Claude inizia a pensare sulle richieste difficili.

A effort high e superiore, Claude può pensare in modo esteso ed è più probabile che esaurisca il budget. Se vedi stop_reason: "max_tokens" nelle risposte, hai due rimedi:

• Aumenta max_tokens per dare al modello più spazio per il ragionamento più la risposta.
• Abbassa il livello di effort in modo che Claude pensi meno e lasci una parte maggiore del budget al testo della risposta.

Quale sia quello giusto dipende dal fatto che le risposte troncate avessero bisogno del ragionamento. Se la qualità su quelle richieste è importante, aumenta il limite; se erano state pensate eccessivamente, abbassa l'effort.

Prezzi

Il ragionamento comporta addebiti per:

• I token che Claude usa mentre pensa (fatturati come token di output)
• I blocchi di ragionamento dei turni precedenti dell'assistente che rimangono nel contesto, secondo il comportamento predefinito di conservazione: tutti i turni per impostazione predefinita sui modelli keep-all, solo l'ultimo turno altrove (fatturati come token di input)
• I token di output di testo standard

Ciò che ti viene fatturato è lo stesso indipendentemente dall'impostazione display; cambia solo ciò che vedi:

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) ed è sempre minore o uguale a output_tokens. Sottrailo da output_tokens per approssimare la porzione dell'output non dedicata al ragionamento. In streaming, questa suddivisione appare solo nell'evento finale message_delta.

{
  "usage": {
    "input_tokens": 25,
    "output_tokens": 348,
    "output_tokens_details": {
      "thinking_tokens": 312
    }
  }
}

output_tokens rimane il totale inclusivo e autorevole usato per la fatturazione. output_tokens_details è una suddivisione di sola lettura a fini di osservabilità. Per informazioni complete sui prezzi, incluse le tariffe base, le scritture in cache, gli hit della cache e i token di output, consulta Prezzi.

Passaggi successivi