---
title: Orientare il ragionamento
url: https://platform.claude.com/docs/it/build-with-claude/thinking-steering-and-cost
description: Orienta la frequenza e la profondità con cui Claude pensa tramite i livelli di effort, le indicazioni nel prompt di sistema e l'orientamento per singolo messaggio, e comprendi i costi e i prezzi del ragionamento.
---
Per scoprire come la "zero data retention" (conservazione zero dei dati), o ZDR, si applica a questa funzionalità, consulta [API e conservazione dei dati](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention).
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](https://platform.claude.com/docs/it/build-with-claude/thinking#thinking-output-on-claude-fable-5-and-claude-mythos-5), consulta la panoramica sul [Ragionamento](https://platform.claude.com/docs/it/build-with-claude/thinking). 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](https://platform.claude.com/docs/it/build-with-claude/effort), che funge da indicazione non vincolante su quanto Claude debba essere disposto a pensare e con quale profondità; consulta [Livelli di effort](https://platform.claude.com/docs/it/build-with-claude/thinking-steering-and-cost#effort-levels) 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](https://platform.claude.com/docs/it/build-with-claude/thinking#interleaved-thinking)). 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](https://platform.claude.com/docs/it/build-with-claude/thinking#thinking-and-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 ottenere meno ragionamento su Claude Sonnet 5.5 e Claude Haiku 5.5, abbassa il livello di effort. Chiedere a Claude Sonnet 5.5 nel prompt di sistema di ragionare meno non riduce in modo affidabile il suo ragionamento e, nei test di Anthropic, dire a Claude Haiku 5.5 nel prompt di rispondere direttamente non gli ha impedito di ragionare. Consulta [Scrivere prompt per Claude Sonnet 5.5](https://platform.claude.com/docs/it/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#calibrate-effort) e [Prompting per Claude Haiku 5.5](https://platform.claude.com/docs/it/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#use-effort-to-control-thinking).
Per indicazioni più ampie sul prompting con il ragionamento, consulta [sfruttare le capacità di ragionamento e di ragionamento interlacciato](https://platform.claude.com/docs/it/build-with-claude/prompt-engineering/claude-prompting-best-practices#leverage-thinking-and-interleaved-thinking-capabilities).
### 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:
| Livello di effort | Comportamento del ragionamento |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `max` | Claude pensa con la massima prontezza e alla massima profondità, senza vincoli sulla lunghezza del ragionamento. |
| `xhigh` | Claude pensa con maggiore prontezza e a maggiore profondità rispetto a `high`, adatto a un'esplorazione estesa. |
| `high` (predefinito sulla maggior parte dei modelli) | Claude pensa nella maggior parte delle richieste che ne traggono beneficio. Fornisce un ragionamento approfondito sulle attività complesse. |
| `medium` (predefinito su Claude Opus 5.5 e Claude Haiku 5.5) | Claude usa un ragionamento moderato. Può saltare il ragionamento per le query semplici. |
| `low` | Claude riduce al minimo il ragionamento. Salta il ragionamento per le attività semplici in cui la velocità conta di più. |
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](https://platform.claude.com/docs/it/build-with-claude/effort#when-to-adjust-the-effort-parameter) 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](https://platform.claude.com/docs/it/build-with-claude/effort#basic-usage).
```json
{
"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](https://platform.claude.com/docs/it/build-with-claude/effort#effort-levels) 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:
```text wrap
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:
```text wrap
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](https://platform.claude.com/docs/it/build-with-claude/effort#change-effort-mid-conversation-beta) (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.
Orientare Claude a pensare meno spesso può ridurre la qualità nelle attività che beneficiano del ragionamento. Abbassare il livello di [effort](https://platform.claude.com/docs/it/build-with-claude/effort) è di solito la prima leva migliore, poiché è un controllo calibrato anziché un'istruzione sensibile alla formulazione. Misura l'impatto sui tuoi carichi di lavoro specifici prima di distribuire in produzione una regolazione basata sui prompt.
## 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](https://platform.claude.com/docs/it/build-with-claude/extended-thinking#turn-structure-in-manual-mode).)
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](https://platform.claude.com/docs/it/build-with-claude/thinking) 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](https://platform.claude.com/docs/it/build-with-claude/thinking#thinking-and-prompt-caching) 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`](https://platform.claude.com/docs/it/build-with-claude/extended-thinking#extended-thinking-with-prompt-caching) 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](https://platform.claude.com/docs/it/build-with-claude/effort#change-effort-mid-conversation-beta) (beta) sui modelli che la supportano, oppure orienta con il [prompting per singolo messaggio](https://platform.claude.com/docs/it/build-with-claude/thinking-steering-and-cost#tuning-thinking-behavior). 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:
Questo flusso di lavoro non si presta bene a un singolo comando shell. Consulta le schede degli SDK per il pattern multi-turno; le richieste HTTP per turno seguono gli esempi della pagina [Cache dei prompt](https://platform.claude.com/docs/it/build-with-claude/prompt-caching).
Questo flusso di lavoro non si presta bene a un singolo comando shell. Consulta le schede degli SDK per il pattern multi-turno; le invocazioni CLI per turno seguono gli esempi della pagina [Cache dei prompt](https://platform.claude.com/docs/it/build-with-claude/prompt-caching).
```python
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}")
```
```typescript
const client = new Anthropic();
async function fetchArticleContent(url: string): Promise {
const response = await fetch(url);
const text = await response.text();
const lines = text.split("\n").map((line) => line.trim());
return lines.filter((line) => line).join("\n");
}
const bookUrl = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt";
const bookContent = await fetchArticleContent(bookUrl);
const LARGE_TEXT = bookContent.substring(0, 10000);
// Nessun prompt di sistema: cache nei messaggi
const messages: Anthropic.MessageParam[] = [
{
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
console.log("First request - establishing cache");
const response1 = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 16000,
thinking: { type: "adaptive" },
messages
});
console.log("First response usage: ", response1.usage);
messages.push(
{ role: "assistant", content: response1.content },
{ role: "user", content: "Analyze the characters in this passage." }
);
// Seconda richiesta: stessa configurazione (cache hit previsto)
console.log("\nSecond request - same configuration (cache hit expected)");
const response2 = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 16000,
thinking: { type: "adaptive" },
messages
});
console.log("Second response usage: ", response2.usage);
messages.push(
{ role: "assistant", content: response2.content },
{ role: "user", content: "Analyze the setting in this passage." }
);
// Terza richiesta: livello di effort diverso (cache miss previsto)
console.log("\nThird request - different effort level (cache miss expected)");
const response3 = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 16000,
thinking: { type: "adaptive" },
output_config: { effort: "low" },
messages
});
console.log("Third response usage: ", response3.usage);
```
```csharp
AnthropicClient client = new();
string bookUrl = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt";
string bookContent = await FetchArticleContent(bookUrl);
string largeText = bookContent.Substring(0, Math.Min(10000, bookContent.Length));
Console.WriteLine("First request - establishing cache");
var parameters1 = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 16000,
Thinking = new ThinkingConfigAdaptive(),
Messages =
[
new()
{
Role = Role.User,
Content = new MessageParamContent(new List
{
new ContentBlockParam(new TextBlockParam()
{
Text = largeText,
CacheControl = new CacheControlEphemeral(),
}),
new ContentBlockParam(new TextBlockParam()
{
Text = "Analyze the tone of this passage."
}),
})
}
]
};
var response1 = await client.Messages.Create(parameters1);
Console.WriteLine($"First response usage: {response1.Usage}");
Console.WriteLine("\nSecond request - same configuration (cache hit expected)");
var parameters2 = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 16000,
Thinking = new ThinkingConfigAdaptive(),
Messages =
[
new()
{
Role = Role.User,
Content = new MessageParamContent(new List
{
new ContentBlockParam(new TextBlockParam()
{
Text = largeText,
CacheControl = new CacheControlEphemeral(),
}),
new ContentBlockParam(new TextBlockParam()
{
Text = "Analyze the tone of this passage."
}),
})
},
new()
{
Role = Role.Assistant,
Content = response1.Content.Select(block => new ContentBlockParam(block.Json)).ToList()
},
new()
{
Role = Role.User,
Content = "Analyze the characters in this passage."
}
]
};
var response2 = await client.Messages.Create(parameters2);
Console.WriteLine($"Second response usage: {response2.Usage}");
Console.WriteLine("\nThird request - different effort level (cache miss expected)");
var parameters3 = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 16000,
Thinking = new ThinkingConfigAdaptive(),
OutputConfig = new OutputConfig
{
Effort = Effort.Low
},
Messages =
[
new()
{
Role = Role.User,
Content = new MessageParamContent(new List
{
new ContentBlockParam(new TextBlockParam()
{
Text = largeText,
CacheControl = new CacheControlEphemeral(),
}),
new ContentBlockParam(new TextBlockParam()
{
Text = "Analyze the tone of this passage."
}),
})
},
new()
{
Role = Role.Assistant,
Content = response1.Content.Select(block => new ContentBlockParam(block.Json)).ToList()
},
new()
{
Role = Role.User,
Content = "Analyze the characters in this passage."
},
new()
{
Role = Role.Assistant,
Content = response2.Content.Select(block => new ContentBlockParam(block.Json)).ToList()
},
new()
{
Role = Role.User,
Content = "Analyze the setting in this passage."
}
]
};
var response3 = await client.Messages.Create(parameters3);
Console.WriteLine($"Third response usage: {response3.Usage}");
static async Task FetchArticleContent(string url)
{
using HttpClient httpClient = new();
string content = await httpClient.GetStringAsync(url);
return content;
}
```
```go
client := anthropic.NewClient()
bookURL := "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"
bookContent, err := fetchArticleContent(bookURL)
if err != nil {
log.Fatal(err)
}
largeText := bookContent
if len(largeText) > 10000 {
largeText = largeText[:10000]
}
// Nessun prompt di sistema: cache nei messaggi
messages := []anthropic.MessageParam{
anthropic.NewUserMessage(
anthropic.ContentBlockParamUnion{OfText: &anthropic.TextBlockParam{
Text: largeText,
CacheControl: anthropic.NewCacheControlEphemeralParam(),
}},
anthropic.NewTextBlock("Analyze the tone of this passage."),
),
}
// Prima richiesta: crea la cache
fmt.Println("First request - establishing cache")
response1, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 16000,
Thinking: anthropic.ThinkingConfigParamUnion{
OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{},
},
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("First response usage: %s\n", response1.Usage.RawJSON())
messages = append(messages, response1.ToParam())
messages = append(messages, anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the characters in this passage.")))
// Seconda richiesta: stessa configurazione (cache hit previsto)
fmt.Println("\nSecond request - same configuration (cache hit expected)")
response2, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 16000,
Thinking: anthropic.ThinkingConfigParamUnion{
OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{},
},
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Second response usage: %s\n", response2.Usage.RawJSON())
messages = append(messages, response2.ToParam())
messages = append(messages, anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the setting in this passage.")))
// Terza richiesta: livello di effort diverso (cache miss previsto)
fmt.Println("\nThird request - different effort level (cache miss expected)")
response3, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 16000,
Thinking: anthropic.ThinkingConfigParamUnion{
OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{},
},
OutputConfig: anthropic.OutputConfigParam{
Effort: anthropic.OutputConfigEffortLow,
},
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Third response usage: %s\n", response3.Usage.RawJSON())
```
```java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
void main() throws Exception {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
String bookUrl = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt";
String bookContent = fetchArticleContent(bookUrl);
String largeText = bookContent.substring(0, Math.min(10000, bookContent.length()));
// Prima richiesta - creazione della cache
IO.println("First request - establishing cache");
MessageCreateParams params1 = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(16000L)
.thinking(ThinkingConfigAdaptive.builder().build())
.addUserMessageOfBlockParams(List.of(
ContentBlockParam.ofText(TextBlockParam.builder()
.text(largeText)
.cacheControl(CacheControlEphemeral.builder().build())
.build()),
ContentBlockParam.ofText(TextBlockParam.builder()
.text("Analyze the tone of this passage.")
.build())
))
.build();
Message response1 = client.messages().create(params1);
IO.println("First response usage: " + response1.usage());
// Seconda richiesta - stessa configurazione (cache hit previsto)
IO.println("\nSecond request - same configuration (cache hit expected)");
MessageCreateParams params2 = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(16000L)
.thinking(ThinkingConfigAdaptive.builder().build())
.addUserMessageOfBlockParams(List.of(
ContentBlockParam.ofText(TextBlockParam.builder()
.text(largeText)
.cacheControl(CacheControlEphemeral.builder().build())
.build()),
ContentBlockParam.ofText(TextBlockParam.builder()
.text("Analyze the tone of this passage.")
.build())
))
.addAssistantMessageOfBlockParams(response1.content().stream()
.map(block -> block.toParam())
.collect(java.util.stream.Collectors.toList()))
.addUserMessage("Analyze the characters in this passage.")
.build();
Message response2 = client.messages().create(params2);
IO.println("Second response usage: " + response2.usage());
// Terza richiesta - livello di effort diverso (cache miss previsto)
IO.println("\nThird request - different effort level (cache miss expected)");
MessageCreateParams params3 = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(16000L)
.thinking(ThinkingConfigAdaptive.builder().build())
.outputConfig(OutputConfig.builder()
.effort(OutputConfig.Effort.LOW)
.build())
.addUserMessageOfBlockParams(List.of(
ContentBlockParam.ofText(TextBlockParam.builder()
.text(largeText)
.cacheControl(CacheControlEphemeral.builder().build())
.build()),
ContentBlockParam.ofText(TextBlockParam.builder()
.text("Analyze the tone of this passage.")
.build())
))
.addAssistantMessageOfBlockParams(response1.content().stream()
.map(block -> block.toParam())
.collect(java.util.stream.Collectors.toList()))
.addUserMessage("Analyze the characters in this passage.")
.addAssistantMessageOfBlockParams(response2.content().stream()
.map(block -> block.toParam())
.collect(java.util.stream.Collectors.toList()))
.addUserMessage("Analyze the setting in this passage.")
.build();
Message response3 = client.messages().create(params3);
IO.println("Third response usage: " + response3.usage());
}
String fetchArticleContent(String url) throws Exception {
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.build();
HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
return response.body();
}
```
```php
function fetchArticleContent($url) {
$content = file_get_contents($url);
$lines = explode("\n", $content);
$cleanedLines = array_filter(array_map('trim', $lines));
return implode("\n", $cleanedLines);
}
$client = new Client();
$bookUrl = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt";
$bookContent = fetchArticleContent($bookUrl);
$largeText = substr($bookContent, 0, 10000);
echo "First request - establishing cache\n";
$response1 = $client->messages->create(
maxTokens: 16000,
messages: [[
'role' => 'user',
'content' => [
[
'type' => 'text',
'text' => $largeText,
'cache_control' => ['type' => 'ephemeral']
],
[
'type' => 'text',
'text' => 'Analyze the tone of this passage.'
]
]
]],
model: 'claude-opus-5-5',
thinking: ['type' => 'adaptive'],
);
echo "First response usage: " . json_encode($response1->usage) . "\n";
echo "\nSecond request - same configuration (cache hit expected)\n";
$response2 = $client->messages->create(
maxTokens: 16000,
messages: [
[
'role' => 'user',
'content' => [
[
'type' => 'text',
'text' => $largeText,
'cache_control' => ['type' => 'ephemeral']
],
[
'type' => 'text',
'text' => 'Analyze the tone of this passage.'
]
]
],
[
'role' => 'assistant',
'content' => $response1->content
],
[
'role' => 'user',
'content' => 'Analyze the characters in this passage.'
]
],
model: 'claude-opus-5-5',
thinking: ['type' => 'adaptive'],
);
echo "Second response usage: " . json_encode($response2->usage) . "\n";
echo "\nThird request - different effort level (cache miss expected)\n";
$response3 = $client->messages->create(
maxTokens: 16000,
messages: [
[
'role' => 'user',
'content' => [
[
'type' => 'text',
'text' => $largeText,
'cache_control' => ['type' => 'ephemeral']
],
[
'type' => 'text',
'text' => 'Analyze the tone of this passage.'
]
]
],
[
'role' => 'assistant',
'content' => $response1->content
],
[
'role' => 'user',
'content' => 'Analyze the characters in this passage.'
],
[
'role' => 'assistant',
'content' => $response2->content
],
[
'role' => 'user',
'content' => 'Analyze the setting in this passage.'
]
],
model: 'claude-opus-5-5',
thinking: ['type' => 'adaptive'],
outputConfig: ['effort' => 'low'],
);
echo "Third response usage: " . json_encode($response3->usage) . "\n";
```
```ruby
require "net/http"
require "uri"
def fetch_article_content(url)
uri = URI.parse(url)
response = Net::HTTP.get_response(uri)
text = response.body
lines = text.split("\n").map(&:strip)
lines.reject(&:empty?).join("\n")
end
client = Anthropic::Client.new
book_url = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"
book_content = fetch_article_content(book_url)
large_text = book_content[0...10000]
puts "First request - establishing cache"
response1 = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 16000,
thinking: {
type: "adaptive"
},
messages: [{
role: "user",
content: [
{
type: "text",
text: large_text,
cache_control: { type: "ephemeral" }
},
{
type: "text",
text: "Analyze the tone of this passage."
}
]
}]
)
puts "First response usage: #{response1.usage}"
puts "\nSecond request - same configuration (cache hit expected)"
response2 = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 16000,
thinking: {
type: "adaptive"
},
messages: [
{
role: "user",
content: [
{
type: "text",
text: large_text,
cache_control: { type: "ephemeral" }
},
{
type: "text",
text: "Analyze the tone of this passage."
}
]
},
{
role: "assistant",
content: response1.content
},
{
role: "user",
content: "Analyze the characters in this passage."
}
]
)
puts "Second response usage: #{response2.usage}"
puts "\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: [
{
role: "user",
content: [
{
type: "text",
text: large_text,
cache_control: { type: "ephemeral" }
},
{
type: "text",
text: "Analyze the tone of this passage."
}
]
},
{
role: "assistant",
content: response1.content
},
{
role: "user",
content: "Analyze the characters in this passage."
},
{
role: "assistant",
content: response2.content
},
{
role: "user",
content: "Analyze the setting in this passage."
}
]
)
puts "Third response usage: #{response3.usage}"
```
Ecco l'output dello script (potresti vedere numeri leggermente diversi):
```text Output wrap
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 }
```
Con il breakpoint della cache nell'array dei messaggi, modificare l'effort da `medium`, il valore predefinito su Claude Opus 5.5, a `low` lo invalida: la terza richiesta mostra `cache_creation_input_tokens=3546` e `cache_read_input_tokens=0`, mentre la seconda mostrava una lettura completa dalla cache.
### 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"`](https://platform.claude.com/docs/it/build-with-claude/thinking-troubleshooting#stopped-at-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](https://platform.claude.com/docs/it/build-with-claude/thinking#thinking-block-preservation-by-model): 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
Quando il ragionamento è attivo, viene incluso automaticamente un prompt di sistema specializzato per supportare questa funzionalità.
Ciò che ti viene fatturato è lo stesso indipendentemente dall'impostazione `display`; cambia solo ciò che vedi:
| | `display: "summarized"` | `display: "omitted"` |
| ------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------- |
| **Token di input** | I token della tua richiesta originale | Come per summarized |
| **Token di output (fatturati)** | Tutti i token di ragionamento che Claude ha generato internamente | Come per summarized |
| **Token di output (visibili)** | Il testo di ragionamento riassunto | Zero token di ragionamento (il campo `thinking` è vuoto) |
| **Generazione del riassunto** | Nessun addebito | Non applicabile |
Il conteggio dei token di output fatturati **non** corrisponde al conteggio dei token visibili nella risposta. Ti viene fatturato l'intero processo di pensiero, non il contenuto di ragionamento visibile nella risposta.
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`.
```json
{
"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](https://platform.claude.com/docs/it/about-claude/pricing).
## Passaggi successivi
Attiva il ragionamento, leggi l'output del ragionamento e verifica il supporto per modello.
Preserva i blocchi di ragionamento tra le chiamate di strumento e gestisci il ragionamento nelle conversazioni multi-turno.
Controlla quanto ragionamento e output Claude alloca per richiesta.