Orientare il pensiero

Il pensiero di Claude è adattivo: il modello valuta ogni richiesta e decide autonomamente se pensare e quanto. Tu imposti un'intenzione, specifichi facoltativamente l'effort, e il modello alloca il ragionamento dove ritiene che il ragionamento sia utile.

Questo rende il pensiero 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 pensiero, come leggere l'output del pensiero e per informazioni sull'output del pensiero su Claude Fable 5 e Claude Mythos 5, consulta la panoramica Pensiero. Questa pagina spiega come Claude decide quando pensare, come orientare tale decisione e i meccanismi di cache, costo e prezzo che ne derivano.

Come Claude decide quando pensare

Il pensiero è facoltativo per il modello. A ogni richiesta, Claude valuta la complessità dell'input e decide se un ragionamento più approfondito migliorerebbe la risposta. Una semplice domanda fattuale può ricevere una risposta diretta senza alcun blocco di pensiero; un problema matematico a più passaggi o un'attività di debugging complicata attiva un ragionamento più profondo.

La decisione avviene per singola richiesta. La stessa conversazione può contenere turni con e senza pensiero, e un turno in cui Claude ha scelto di non pensare non contiene alcun blocco di pensiero. 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 pensiero si alterna inoltre automaticamente con l'uso degli strumenti: Claude può pensare tra una chiamata di strumento e l'altra, riflettendo su ciascun risultato prima di decidere cosa fare dopo (pensiero interleaved). Non è necessario alcun header beta né alcuna configurazione aggiuntiva per questo.

Per il quadro completo di come interagiscono la configurazione del pensiero e il parametro effort, consulta Pensiero 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 pensiero di Claude non corrisponde ancora alle tue esigenze a quel livello.

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

Livelli di effort

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

Questa tabella descrive come ciascun livello modifica il comportamento del pensiero. 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",
  "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 pensiero 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 pensiero, 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 pensiero 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 pensare in quel turno; "Answer directly without deliberating." lo sopprime.

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 soppressione nelle conferme di routine, senza toccare il prompt di sistema né modificare alcun parametro della richiesta tra un turno e l'altro.

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 pensiero (la presenza di blocchi di pensiero 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 pensiero: 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 pensiero. (I modelli che usano un budget di pensiero manuale legacy impongono che l'ultimo turno dell'assistente di una richiesta con pensiero abilitato inizi con uno; consulta Struttura dei turni 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 pensiero, o che usava una configurazione di pensiero diversa, senza riscriverne la cronologia.
• La cronologia assemblata da fonti miste non richiede che i blocchi di pensiero 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 pensiero, 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 Pensiero per le regole complete.

Cache dei prompt

Le richieste consecutive che mantengono la stessa configurazione di pensiero e lo stesso livello di effort preservano la "prompt caching" (cache dei prompt); consulta Pensiero 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 pensiero e un livello di effort per conversazione e mantienili. Se alcuni turni richiedono più o meno pensiero, orienta con il prompting per singolo messaggio: le indicazioni aggiunte al messaggio utente più recente lasciano intatti i breakpoint della cache precedenti, mentre una modifica della configurazione o dell'effort non lo fa.

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: cache nei messaggi invece
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",
    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 previsto)
print("\nSecond request - same configuration (cache hit expected)")
response2 = client.messages.create(
    model="claude-opus-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 previsto)
print("\nThird request - different effort level (cache miss expected)")
response3 = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "medium"},
    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 pensiero. Due controlli limitano i costi:

• max_tokens è un limite rigido sull'output totale della richiesta, pensiero 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 pensiero. Modella il comportamento ma non garantisce un conteggio di token.

Poiché il pensiero 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 pensiero è 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 pensiero 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 pensiero comporta addebiti per:

• I token che Claude usa mentre pensa (fatturati come token di output)
• I blocchi di pensiero 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