---
title: Guida alla migrazione a Claude Opus 5.5
url: https://platform.claude.com/docs/it/models/opus-5-5/migration-guide
description: Passa a Claude Opus 5.5 dai modelli Opus precedenti o da Claude Sonnet 5 con questa guida alla migrazione. Le indicazioni per abilitare Claude Opus 5.5 includono le impostazioni delle richieste che restituiscono errori, i blocchi di ragionamento in ogni risposta e una checklist per ciascun modello di partenza.
---
Questa guida copre la migrazione del codice della [Messages API](https://platform.claude.com/docs/it/build-with-claude/working-with-messages). Se usi [Claude Managed Agents](https://platform.claude.com/docs/it/managed-agents/overview), non sono necessarie modifiche oltre all’aggiornamento del nome del modello.
Lascia che Claude Code migri il tuo codice per te
```text
/claude-api migrate questo progetto a claude-opus-5-5
```
Questa pagina elenca le modifiche al codice per passare a Claude Opus 5.5 da [Claude Opus 5](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#migrating-from-claude-opus-5), [Claude Opus 4.8](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#migrating-from-claude-opus-4-8), [Claude Opus 4.7](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#migrating-from-claude-opus-47), [Claude Opus 4.6 e modelli Opus precedenti](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#migrating-from-claude-opus-46) o [Claude Sonnet 5](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#migrating-from-claude-sonnet-5). Ogni lettore ha bisogno di [Requisiti che ogni richiesta a Claude Opus 5.5 deve soddisfare](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#request-requirements) e [Gestire il ragionamento in ogni risposta](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#thinking-in-every-response). Poi vai alla sezione relativa al tuo modello attuale: la sua prima frase indica le altre sezioni che si applicano al tuo caso. La [checklist di migrazione](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#migration-checklist) elenca ogni modifica in base al modello di partenza.
Claude Opus 5.5 costa meno di Claude Opus 5 ($4 / $20 USD per milione di token di input / output, rispetto a $5 / $25 USD; consulta [Prezzi di Claude](https://platform.claude.com/docs/it/about-claude/pricing)). Per il supporto delle funzionalità, consulta [Novità di Claude Opus 5.5](https://platform.claude.com/docs/it/models/opus-5-5/whats-new-opus-5-5#feature-support). Per le differenze di comportamento e i pattern di prompting specifici del modello, consulta [Prompting per Claude Opus 5.5](https://platform.claude.com/docs/it/build-with-claude/prompt-engineering/prompting-claude-opus-5-5).
## Requisiti che ogni richiesta a Claude Opus 5.5 deve soddisfare
Qualunque sia il modello da cui provieni, una richiesta a `claude-opus-5-5` deve soddisfare quanto segue. Quando un elemento indica che un’impostazione viene rifiutata, l’API restituisce un errore 400.
* **ID del modello:** Usa `claude-opus-5-5`, un ID del modello fisso senza suffisso di data. Su Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), Claude Models on Google Cloud (Google managed) e Microsoft Foundry, usa l’ID del modello di quella piattaforma; consulta [Disponibilità](https://platform.claude.com/docs/it/models/opus-5-5/whats-new-opus-5-5#availability).
* **Ragionamento:** Non inviare alcun campo `thinking`, oppure invia `thinking: {"type": "adaptive"}`, che è equivalente: l’[“adaptive thinking” (ragionamento adattivo)](https://platform.claude.com/docs/it/build-with-claude/thinking) è sempre attivo. `thinking: {"type": "disabled"}` e i budget di ragionamento manuali (`thinking: {"type": "enabled", "budget_tokens": N}`) vengono rifiutati. Consulta il [prima e dopo per il ragionamento](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#thinking-cant-be-disabled).
* **Effort:** Controlla la profondità del ragionamento con il [parametro effort](https://platform.claude.com/docs/it/build-with-claude/effort), l’unico parametro della richiesta che la controlla. Tutti e cinque i livelli (`low`, `medium`, `high`, `xhigh`, `max`) sono supportati e il valore predefinito è `medium`. Consulta [Livelli di effort consigliati per Claude Opus 5.5](https://platform.claude.com/docs/it/build-with-claude/effort#recommended-effort-levels-for-claude-opus-5-5).
* **Scelta dello strumento:** Usa `tool_choice` `{"type": "auto"}` (il valore predefinito) oppure `{"type": "none"}`. Forzare una chiamata a uno strumento con `{"type": "any"}` o `{"type": "tool", "name": "..."}` viene rifiutato. Consulta il [prima e dopo per la scelta dello strumento](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#forced-tool-use).
* **Parametri di campionamento:** Ometti `temperature`, `top_p` e `top_k`. Usa il prompting per guidare il comportamento del modello.
* **Prefill:** Non terminare `messages` con un turno dell’assistente precompilato (“prefill”): viene rifiutato. Usa invece gli [“structured outputs” (output strutturati)](https://platform.claude.com/docs/it/build-with-claude/structured-outputs) o istruzioni nel prompt di sistema.
* **Computer use:** Dichiara il “computer use” (uso del computer) come toolset `computer_toolset_20260801`. Su Amazon Bedrock funziona anche `computer_20251124`. Consulta la [modifica incompatibile del computer use](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#computer-use-toolset).
* **Finestra di contesto:** Non è necessario alcun header beta per la “context window” (finestra di contesto). La [finestra di contesto da 1M token](https://platform.claude.com/docs/it/build-with-claude/context-windows) è quella predefinita, e un header inviato per modelli precedenti non ha alcun effetto.
La seguente richiesta soddisfa ogni elemento dell’elenco: l’effort è impostato e non c’è alcun campo `thinking`. Dove l’esempio stampa del testo, individua il blocco di testo in base al suo tipo, perché i blocchi `thinking` vengono prima.
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"messages": [{
"role": "user",
"content": "Analyze the trade-offs between microservices and monolithic architectures"
}],
"output_config": {
"effort": "medium"
}
}'
```
```bash CLI
ant messages create \
--model claude-opus-5-5 \
--max-tokens 4096 \
--output-config '{effort: medium}' \
--message '{role: user, content: "Analyze the trade-offs between microservices and monolithic architectures"}'
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Analyze the trade-offs between microservices and monolithic architectures",
}
],
output_config={"effort": "medium"},
)
for block in response.content:
if block.type == "text":
print(block.text)
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
messages: [
{
role: "user",
content: "Analyze the trade-offs between microservices and monolithic architectures"
}
],
output_config: {
effort: "medium"
}
});
const textBlock = response.content.find((block) => block.type === "text");
console.log(textBlock?.text);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Messages = [
new UserMessageParam
{
Content = "Analyze the trade-offs between microservices and monolithic architectures"
}
],
OutputConfig = new OutputConfig
{
Effort = Effort.Medium
}
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the trade-offs between microservices and monolithic architectures")),
},
OutputConfig: anthropic.OutputConfigParam{
Effort: anthropic.OutputConfigEffortMedium,
},
})
if err != nil {
log.Fatal(err)
}
for _, block := range response.Content {
if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
fmt.Println(textBlock.Text)
}
}
```
```java Java
import com.anthropic.models.messages.OutputConfig;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.addUserMessage("Analyze the trade-offs between microservices and monolithic architectures")
.outputConfig(OutputConfig.builder()
.effort(OutputConfig.Effort.MEDIUM)
.build())
.build();
Message response = client.messages().create(params);
response.content().stream()
.flatMap(block -> block.text().stream())
.forEach(textBlock -> IO.println(textBlock.text()));
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Analyze the trade-offs between microservices and monolithic architectures']
],
model: 'claude-opus-5-5',
outputConfig: ['effort' => 'medium'],
);
foreach ($message->content as $block) {
if ($block->type === 'text') {
echo $block->text, PHP_EOL;
}
}
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 4096,
messages: [
{ role: "user", content: "Analyze the trade-offs between microservices and monolithic architectures" }
],
output_config: {
effort: "medium"
}
)
message.content.each do |block|
puts block.text if block.type == :text
end
```
## Gestire il ragionamento in ogni risposta
Il ragionamento viene eseguito su ogni richiesta a Claude Opus 5.5, quindi ogni risposta può iniziare con blocchi `thinking`, e `max_tokens` copre ragionamento più testo. Se il tuo codice funziona già con il ragionamento attivo, i punti da 1 a 3 sono probabilmente già soddisfatti: controlla i punti 4 e 5. Se funzionava senza ragionamento, su qualsiasi modello precedente, ogni punto rappresenta una modifica.
1. **`max_tokens` copre ragionamento più testo:** Su Claude Opus 4.8 e sui modelli Opus precedenti, le richieste senza un campo `thinking` vengono eseguite senza ragionamento. Claude Opus 5 e Claude Sonnet 5 accettano `thinking: {"type": "disabled"}`. Su Claude Opus 5.5, ogni richiesta viene eseguita con il [ragionamento adattivo](https://platform.claude.com/docs/it/build-with-claude/thinking). `max_tokens` rimane un limite rigido sull’output totale, ragionamento più testo della risposta, quindi rivedilo per i carichi di lavoro che funzionavano senza ragionamento. I token di ragionamento vengono fatturati come token di output anche quando il testo del ragionamento non ti viene restituito, quindi un carico di lavoro di questo tipo può produrre più token di output per richiesta. Consulta [Controllo dei costi](https://platform.claude.com/docs/it/build-with-claude/thinking-steering-and-cost#cost-control). Per spendere meno token nel ragionamento, abbassa il livello di [effort](https://platform.claude.com/docs/it/build-with-claude/effort). Se lavori con effort `xhigh` o `max`, imposta un `max_tokens` elevato in modo che il modello abbia spazio per ragionare e agire; parti da 64k token e regola da lì. Se i tuoi prompt erano ottimizzati per funzionare senza ragionamento, consulta [Prompt scritti per il ragionamento disabilitato](https://platform.claude.com/docs/it/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#prompts-written-for-thinking-disabled).
2. **Le risposte iniziano con blocchi di ragionamento:** Una risposta può iniziare con uno o più blocchi `thinking` prima del primo blocco `text`. Il codice che legge la risposta per posizione, come `content[0].text` o un gestore di streaming che tratta il primo evento `content_block_start` come testo, si interrompe con queste risposte. Seleziona invece i blocchi di contenuto in base al loro campo `type`: leggi `text` dai blocchi il cui `type` è `"text"` e ramifica in base al tipo di blocco quando gestisci gli eventi di streaming.
3. **Restituisci i blocchi di ragionamento senza modifiche nei cicli di uso degli strumenti:** Se esegui un ciclo di “tool use” (uso degli strumenti), passa i blocchi `thinking` di ogni risposta dell’assistente all’API completi e senza modifiche quando restituisci i risultati degli strumenti, inclusi i blocchi il cui campo `thinking` è vuoto. Rimanda il messaggio dell’assistente così come ricevuto, invece di filtrarne i blocchi di contenuto per tipo o ricostruirlo: l’API rifiuta i blocchi di ragionamento modificati, riordinati o parzialmente rimossi con un errore 400. Consulta [Preservare i blocchi di ragionamento](https://platform.claude.com/docs/it/build-with-claude/thinking#preserving-thinking-blocks).
4. **Il testo del ragionamento è omesso per impostazione predefinita:** `thinking.display` ha come valore predefinito `"omitted"`, quindi i blocchi `thinking` arrivano con un campo `thinking` vuoto insieme alla loro `signature`. Tratta il campo `thinking` solo come testo da visualizzare. Per ricevere invece riepiloghi leggibili, imposta `thinking.display` su `"summarized"`:
```python Python
thinking = {
"type": "adaptive",
"display": "summarized",
}
```
```typescript TypeScript
const thinking = {
type: "adaptive",
display: "summarized"
};
```
```csharp C#
var thinking = new ThinkingConfigAdaptive { Display = Display.Summarized };
```
```go Go
thinking := anthropic.ThinkingConfigParamUnion{
OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{
Display: anthropic.ThinkingConfigAdaptiveDisplaySummarized,
},
}
```
```java Java
ThinkingConfigAdaptive thinking = ThinkingConfigAdaptive.builder()
.display(ThinkingConfigAdaptive.Display.SUMMARIZED)
.build();
```
```php PHP
$thinking = ['type' => 'adaptive', 'display' => 'summarized'];
```
```ruby Ruby
thinking = {
type: "adaptive",
display: "summarized"
}
```
Se il tuo prodotto trasmette in streaming il ragionamento agli utenti, l’impostazione predefinita appare come una lunga pausa prima dell’inizio dell’output; imposta `display: "summarized"` per ripristinare un avanzamento visibile durante il ragionamento. Consulta [Controllare la visualizzazione del ragionamento](https://platform.claude.com/docs/it/build-with-claude/thinking#controlling-thinking-display).
5. **Il testo tra le chiamate agli strumenti arriva nei blocchi di ragionamento:** Le brevi note che il modello scrive tra le chiamate agli strumenti vengono restituite come blocchi `thinking`, che sono vuoti con la visualizzazione predefinita. Consulta [Il testo tra le chiamate agli strumenti viene restituito nei blocchi di ragionamento](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#text-between-tool-calls).
## Checklist di migrazione per modello di partenza
Scorri i gruppi e fermati dopo quello che indica il tuo modello attuale: ogni elemento fino a quel punto si applica al tuo caso. Se usi Claude Opus 5, il primo gruppo è l’intero elenco. Se usi Claude Sonnet 5, applica il primo gruppo e l’ultimo.
### Ogni modello di partenza
* Aggiorna l’ID del modello a `claude-opus-5-5`.
* Rimuovi `thinking: {"type": "disabled"}` e `thinking: {"type": "enabled", ...}`; scegli invece un livello di effort.
* Imposta `effort` esplicitamente: il valore predefinito è `medium`, mentre quello di Claude Opus 5 è `high`.
* Sostituisci i tipi di `tool_choice` `any` e `tool` con `auto` più l’uso rigoroso degli strumenti (“strict tool use”) o gli output strutturati.
* Se usi una versione precedente dello strumento di computer use, dichiara invece `computer_toolset_20260801` (senza header beta) e aggiorna il tuo ciclo dell’agente per il toolset. Su Amazon Bedrock funziona anche `computer_20251124`.
* Se un router o un fallback può spostare una conversazione da Claude Opus 5.5 a un altro modello, aspettati che quel modello venga eseguito senza i blocchi di ragionamento di Claude Opus 5.5 (Claude Fable 5.1 e Claude Mythos 5.1 sulla Claude API sono l’eccezione e li conservano). Claude Opus 5.5 stesso legge il ragionamento da Claude Opus 5, dai modelli Opus, Sonnet e Haiku precedenti e, sulla Claude API e su Claude Models on Google Cloud (Google managed), da Claude Sonnet 5.5 e Claude Haiku 5.5, ma non dai modelli Claude Fable o Claude Mythos.
* Leggi i blocchi di contenuto in base al `type` e restituisci i blocchi `thinking` senza modifiche nei cicli di uso degli strumenti.
* Se la tua interfaccia mostra il testo tra le chiamate agli strumenti, imposta `display: "updates"` (beta) o `"summarized"` e mostra i blocchi `thinking` non vuoti.
* Se il tuo codice modifica i turni precedenti, il prompt `system` o `tools` a metà conversazione, segui [Ragionamento preservato](https://platform.claude.com/docs/it/build-with-claude/preserved-thinking).
* Gestisci `stop_reason: "refusal"` e configura un fallback.
* Ristabilisci la baseline di costi e latenza al livello di effort scelto.
* Se il tuo codice disabilitava il ragionamento, rivedi `max_tokens`, che copre il ragionamento più il testo della risposta; con effort `xhigh` o `max`, parti da 64k. Consulta [Gestisci il ragionamento in ogni risposta](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#thinking-in-every-response).
### Claude Opus 4.8 o precedenti
* Rivedi i carichi di lavoro che funzionavano senza un campo `thinking`: su Claude Opus 5.5 vengono eseguiti con il ragionamento, e il ragionamento non può essere disabilitato. Rivedi `max_tokens`, che rimane un limite rigido sull’output totale (ragionamento più testo della risposta), e abbassa `effort` dove desideri meno ragionamento. I token di ragionamento vengono fatturati come token di output, quindi questi carichi di lavoro possono produrre più token di output per richiesta.
* Verifica che qualsiasi codice che analizza il campo `thinking` lo tratti solo come testo da visualizzare. Imposta `display: "summarized"` per ricevere riepiloghi leggibili.
* Rivedi i prompt vicini al minimo per la cache: i prompt di 512 token o più possono creare voci di cache.
* Se la tua organizzazione ha un impegno [Priority Tier](https://platform.claude.com/docs/it/api/service-tiers#supported-models), pianifica la capacità separatamente: Priority Tier non è supportato su Claude Opus 5.5.
* Se lavori con effort `xhigh` o `max`, aumenta `max_tokens` ad almeno 64k come punto di partenza.
* Per i carichi di lavoro agentici, considera i [budget delle attività](https://platform.claude.com/docs/it/build-with-claude/task-budgets) (beta) e le modifiche agli strumenti a metà conversazione (beta).
### Claude Opus 4.7 o precedenti
* Esegui una nuova analisi dei livelli di [effort](https://platform.claude.com/docs/it/build-with-claude/effort) sulle tue valutazioni invece di riportare un’impostazione ottimizzata per un modello precedente.
* Rimuovi qualsiasi header beta per la finestra di contesto.
* Se ricostruisci la cronologia della conversazione per aggiornare le istruzioni, considera il passaggio a un messaggio di sistema a metà conversazione per preservare gli hit della cache dei prompt.
* Verifica che la gestione dei motivi di arresto legga `stop_details` in caso di rifiuto.
* Se desideri la modalità veloce, che Claude Opus 4.7 rifiuta, imposta `speed: "fast"` nelle tue richieste alla Claude API. Claude Opus 5.5 non necessita di un header beta.
### Claude Opus 4.6 o precedenti
* Rimuovi `temperature`, `top_p` e `top_k` dai payload delle richieste.
* Sostituisci `thinking: {"type": "enabled", "budget_tokens": N}` con `thinking: {"type": "adaptive"}` più il [parametro effort](https://platform.claude.com/docs/it/build-with-claude/effort), oppure rimuovi completamente il campo `thinking`; il ragionamento adattivo è sempre attivo.
* Se la tua interfaccia utente visualizza il contenuto del ragionamento, attiva esplicitamente il riepilogo del ragionamento.
* Esegui nuovamente il benchmark di costi e latenza end-to-end con la tokenizzazione aggiornata.
* Regola nuovamente `max_tokens` per tenere conto della tokenizzazione aggiornata, inclusi i trigger di compattazione.
* Testa nuovamente qualsiasi stima del conteggio dei token lato client.
* Se la tua applicazione invia immagini, ricalcola il budget per il [supporto delle immagini ad alta risoluzione](https://platform.claude.com/docs/it/build-with-claude/vision#high-resolution-image-support-on-claude-opus-4-7) (fino a circa 3 volte più token immagine per ogni immagine a piena risoluzione). Riduci la risoluzione prima dell’invio se non ti serve la fedeltà aggiuntiva.
* Se utilizzi coordinate di puntamento o di bounding box dal modello, rimuovi qualsiasi conversione con fattore di scala; le coordinate sono 1:1 con i pixel effettivi dell’immagine su Claude Opus 4.7 e sui modelli successivi.
* Rivedi le [modifiche di comportamento](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#behavior-changes) iniziate con Claude Opus 4.7.
* Se il tuo prodotto svolge attività di sicurezza legittime, fai domanda al [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude-opus-and-sonnet) per ottenere restrizioni ridotte sui contenuti informatici.
### Claude Opus 4.5 o precedenti
* Rimuovi qualsiasi prefill dei messaggi dell’assistente; Claude Opus 4.6 li rifiuta già.
* Verifica che l’analisi del JSON delle chiamate agli strumenti utilizzi un parser JSON standard.
* Passa da `client.beta.messages.create()` (csharp: `client.Beta.Messages.Create()`; go: `client.Beta.Messages.New()`; java: `client.beta().messages().create()`; php: `$client->beta->messages->create()`; cli: `ant beta:messages create`) a `client.messages.create()` (csharp: `client.Messages.Create()`; go: `client.Messages.New()`; java: `client.messages().create()`; php: `$client->messages->create()`; cli: `ant messages create`): il ragionamento adattivo e l’effort non necessitano di un namespace beta.
* Rimuovi l’header beta `effort-2025-11-24` (il parametro effort non lo richiede).
* Rimuovi l’header beta `fine-grained-tool-streaming-2025-05-14`.
* Rimuovi l’header beta `interleaved-thinking-2025-05-14` (il ragionamento adattivo abilita automaticamente il ragionamento interleaved).
* Migra `output_format` a `output_config.format` (se applicabile).
### Claude 4.1 o precedenti
* Aggiorna le versioni degli strumenti (`text_editor_20250728`, `code_execution_20260521`).
* Gestisci il motivo di arresto `refusal`.
* Gestisci il motivo di arresto `model_context_window_exceeded`.
* Verifica la gestione dei parametri stringa degli strumenti per i caratteri di nuova riga finali.
* Rimuovi gli header beta `token-efficient-tools-2025-02-19` e `output-128k-2025-02-19`.
* Rivedi e aggiorna i prompt seguendo le [best practice di prompting](https://platform.claude.com/docs/it/build-with-claude/prompt-engineering/claude-prompting-best-practices).
### Solo Claude Sonnet 5
* Se ricostruisci la cronologia della conversazione per aggiornare le istruzioni, considera il passaggio a un messaggio di sistema a metà conversazione per preservare gli hit della cache dei prompt.
* Rivedi i prompt vicini al minimo per la cache: i prompt di 512 token o più possono creare voci di cache.
## Migrazione a Claude Opus 5.5 da Claude Opus 5
Per prima cosa, segui [Requisiti che ogni richiesta a Claude Opus 5.5 deve soddisfare](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#request-requirements) e [Gestire il ragionamento in ogni risposta](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#thinking-in-every-response). Ogni modello di partenza necessita delle modifiche in questa sezione. Si tratta delle impostazioni delle richieste che Claude Opus 5.5 rifiuta e delle modifiche alle risposte che lo accompagnano. La checklist per questa sezione è il primo gruppo della [checklist di migrazione](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#migration-checklist).
### Aggiorna il nome del modello
```python
model = "claude-opus-5" # Before
model = "claude-opus-5-5" # After
```
`claude-opus-5-5` è un ID del modello fisso senza suffisso di data, lo stesso schema di `claude-opus-5`. Su Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), Claude Models on Google Cloud (Google managed) e Microsoft Foundry, usa l’ID del modello di quella piattaforma; consulta [Disponibilità](https://platform.claude.com/docs/it/models/opus-5-5/whats-new-opus-5-5#availability).
### Modifiche incompatibili
Ogni modifica è spiegata in [Modifiche incompatibili](https://platform.claude.com/docs/it/models/opus-5-5/whats-new-opus-5-5#breaking-changes) in Novità di Claude Opus 5.5; questa sezione fornisce la modifica al codice per ciascuna.
#### Il ragionamento non può essere disabilitato
`thinking: {"type": "disabled"}` e `thinking: {"type": "enabled", "budget_tokens": N}` restituiscono entrambi un errore 400 (`"thinking.type.disabled" is not supported for this model.` o `"thinking.type.enabled" is not supported for this model.`). Rimuovi il campo `thinking` e scegli un livello di [effort](https://platform.claude.com/docs/it/build-with-claude/effort); dove disabilitavi il ragionamento per risparmiare token, usane uno più basso. Le risposte iniziano quindi con blocchi `thinking`, perciò seleziona i blocchi di contenuto in base a `type` e restituisci i blocchi `thinking` senza modifiche insieme ai risultati degli strumenti. Consulta [Il ragionamento non può essere disabilitato](https://platform.claude.com/docs/it/models/opus-5-5/whats-new-opus-5-5#thinking-cant-be-disabled).
Prima. Claude Opus 5 accetta questa richiesta, mentre Claude Opus 5.5 la rifiuta con un errore 400:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5",
"max_tokens": 16000,
"thinking": {"type": "disabled"},
"messages": [{"role": "user", "content": "..."}]
}'
```
```bash CLI
ant messages create \
--model claude-opus-5 \
--max-tokens 16000 \
--thinking '{type: disabled}' \
--message '{role: user, content: "..."}'
```
```python Python
client.messages.create(
model="claude-opus-5",
max_tokens=16000,
thinking={"type": "disabled"},
messages=[{"role": "user", "content": "..."}],
)
```
```typescript TypeScript
await client.messages.create({
model: "claude-opus-5",
max_tokens: 16000,
thinking: { type: "disabled" },
messages: [{ role: "user", content: "..." }]
});
```
```csharp C#
await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5,
MaxTokens = 16000,
Thinking = new ThinkingConfigDisabled(),
Messages = [new UserMessageParam { Content = "..." }],
});
```
```go Go
client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 16000,
Thinking: anthropic.ThinkingConfigParamUnion{
OfDisabled: &anthropic.ThinkingConfigDisabledParam{},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
},
})
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5)
.maxTokens(16000L)
.thinking(ThinkingConfigDisabled.builder().build())
.addUserMessage("...")
.build();
client.messages().create(params);
```
```php PHP
$client->messages->create(
model: Model::CLAUDE_OPUS_5,
maxTokens: 16000,
thinking: ThinkingConfigDisabled::with(),
messages: [['role' => 'user', 'content' => '...']],
);
```
```ruby Ruby
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5,
max_tokens: 16000,
thinking: Anthropic::ThinkingConfigDisabled.new,
messages: [{ role: "user", content: "..." }]
)
```
Dopo:
```bash cURL
# il ragionamento è sempre attivo; il controllo è effort
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 16000,
"output_config": {"effort": "low"},
"messages": [{"role": "user", "content": "..."}]
}'
```
```bash CLI
# il ragionamento è sempre attivo; il controllo è effort
ant messages create \
--model claude-opus-5-5 \
--max-tokens 16000 \
--output-config '{effort: low}' \
--message '{role: user, content: "..."}'
```
```python Python
client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
output_config={"effort": "low"}, # thinking is always on; effort is the control
messages=[{"role": "user", "content": "..."}],
)
```
```typescript TypeScript
await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 16000,
output_config: { effort: "low" }, // thinking is always on; effort is the control
messages: [{ role: "user", content: "..." }]
});
```
```csharp C#
await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 16000,
OutputConfig = new() { Effort = Effort.Low }, // thinking is always on; effort is the control
Messages = [new UserMessageParam { Content = "..." }],
});
```
```go Go
client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 16000,
OutputConfig: anthropic.OutputConfigParam{
Effort: anthropic.OutputConfigEffortLow, // thinking is always on; effort is the control
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
},
})
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(16000L)
// il ragionamento è sempre attivo; il controllo è l'effort
.outputConfig(OutputConfig.builder()
.effort(OutputConfig.Effort.LOW)
.build())
.addUserMessage("...")
.build();
client.messages().create(params);
```
```php PHP
$client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 16000,
// il ragionamento è sempre attivo; effort è il controllo
outputConfig: OutputConfig::with(effort: Effort::LOW),
messages: [['role' => 'user', 'content' => '...']],
);
```
```ruby Ruby
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 16000,
# il ragionamento è sempre attivo; il controllo è effort
output_config: { effort: Anthropic::OutputConfig::Effort::LOW },
messages: [{ role: "user", content: "..." }]
)
```
#### L’uso forzato degli strumenti non è supportato
I tipi di `tool_choice` `any` e `tool` restituiscono un errore 400 (`tool_choice: type "tool" and "any" are not supported for this model.`), anche sull’endpoint di conteggio dei token. Usa `auto` con l’[uso rigoroso degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/strict-tool-use) o gli [output strutturati](https://platform.claude.com/docs/it/build-with-claude/structured-outputs), e indica nel prompt quando lo strumento si applica. L’uso rigoroso degli strumenti accetta un sottoinsieme di JSON Schema, quindi controlla l’`input_schema` di ogni strumento prima di aggiungere `strict: true`. Ogni oggetto nello schema deve impostare `additionalProperties: false`; consulta [Limitazioni di JSON Schema](https://platform.claude.com/docs/it/build-with-claude/structured-outputs#json-schema-limitations). Consulta [L’uso forzato degli strumenti non è supportato](https://platform.claude.com/docs/it/models/opus-5-5/whats-new-opus-5-5#forced-tool-use-is-not-supported).
Prima. Claude Opus 5 accetta questa richiesta, mentre Claude Opus 5.5 la rifiuta con un errore 400:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5",
"max_tokens": 1024,
"tools": [{
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
}
},
"required": ["location"],
"additionalProperties": false
}
}],
"tool_choice": {"type": "tool", "name": "get_weather"},
"messages": [{"role": "user", "content": "What'\''s the weather in Paris?"}]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5
max_tokens: 1024
tools:
- name: get_weather
description: Get the current weather in a given location
input_schema:
type: object
properties:
location:
type: string
description: The city and state, e.g. San Francisco, CA
required: [location]
additionalProperties: false
tool_choice:
type: tool
name: get_weather
messages:
- role: user
content: What's the weather in Paris?
YAML
```
```python Python
client.messages.create(
model="claude-opus-5",
max_tokens=1024,
tools=tools,
tool_choice={"type": "tool", "name": "get_weather"},
messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)
```
```typescript TypeScript
await client.messages.create({
model: "claude-opus-5",
max_tokens: 1024,
tools,
tool_choice: { type: "tool", name: "get_weather" },
messages: [{ role: "user", content: "What's the weather in Paris?" }]
});
```
```csharp C#
await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5,
MaxTokens = 1024,
Tools = [.. tools],
ToolChoice = new ToolChoiceTool { Name = "get_weather" },
Messages = [new UserMessageParam { Content = "What's the weather in Paris?" }],
});
```
```go Go
client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 1024,
Tools: tools,
ToolChoice: anthropic.ToolChoiceParamOfTool("get_weather"),
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather in Paris?")),
},
})
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5)
.maxTokens(1024L)
.tools(tools)
.toolChoice(ToolChoiceTool.of("get_weather"))
.addUserMessage("What's the weather in Paris?")
.build();
client.messages().create(params);
```
```php PHP
$client->messages->create(
model: Model::CLAUDE_OPUS_5,
maxTokens: 1024,
tools: $tools,
toolChoice: ToolChoiceTool::with(name: 'get_weather'),
messages: [['role' => 'user', 'content' => "What's the weather in Paris?"]],
);
```
```ruby Ruby
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5,
max_tokens: 1024,
tools: tools,
tool_choice: Anthropic::ToolChoiceTool.new(name: "get_weather"),
messages: [{ role: "user", content: "What's the weather in Paris?" }]
)
```
Dopo:
```bash cURL
# uso rigoroso degli strumenti: ogni chiamata rispetta l'input_schema dello strumento
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"tools": [{
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
}
},
"required": ["location"],
"additionalProperties": false
},
"strict": true
}],
"tool_choice": {"type": "auto"},
"messages": [{
"role": "user",
"content": "What'\''s the weather in Paris? Use the get_weather tool."
}]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
tools:
- name: get_weather
description: Get the current weather in a given location
input_schema:
type: object
properties:
location:
type: string
description: The city and state, e.g. San Francisco, CA
required: [location]
additionalProperties: false
# uso degli strumenti rigoroso: ogni chiamata rispetta l'input_schema dello strumento
strict: true
tool_choice:
type: auto
messages:
- role: user
content: What's the weather in Paris? Use the get_weather tool.
YAML
```
```python Python
client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
# uso degli strumenti rigoroso: ogni chiamata rispetta l'input_schema dello strumento
tools=[{**tool, "strict": True} for tool in tools],
tool_choice={"type": "auto"},
messages=[
{
"role": "user",
"content": "What's the weather in Paris? Use the get_weather tool.",
}
],
)
```
```typescript TypeScript
await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
// uso degli strumenti rigoroso: ogni chiamata rispetta l'input_schema dello strumento
tools: tools.map((tool) => ({ ...tool, strict: true })),
tool_choice: { type: "auto" },
messages: [
{
role: "user",
content: "What's the weather in Paris? Use the get_weather tool."
}
]
});
```
```csharp C#
await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
// "strict tool use" (uso degli strumenti rigoroso): ogni chiamata rispetta l'input_schema dello strumento
Tools = [.. tools.Select(tool => tool with { Strict = true })],
ToolChoice = new ToolChoiceAuto(),
Messages =
[
new UserMessageParam { Content = "What's the weather in Paris? Use the get_weather tool." },
],
});
```
```go Go
// uso degli strumenti rigoroso: ogni chiamata rispetta l'input_schema dello strumento
var strictTools []anthropic.ToolUnionParam
for _, tool := range tools {
strictTool := *tool.OfTool
strictTool.Strict = anthropic.Bool(true)
strictTools = append(strictTools, anthropic.ToolUnionParam{OfTool: &strictTool})
}
client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Tools: strictTools,
ToolChoice: anthropic.ToolChoiceUnionParam{OfAuto: &anthropic.ToolChoiceAutoParam{}},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(
anthropic.NewTextBlock("What's the weather in Paris? Use the get_weather tool."),
),
},
})
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
// uso rigoroso degli strumenti: ogni chiamata rispetta l'input_schema dello strumento
.tools(tools.stream()
.map(tool -> tool.tool()
.map(customTool -> customTool.toBuilder()
.strict(true)
.build())
.map(ToolUnion::ofTool)
.orElse(tool))
.toList())
.toolChoice(ToolChoiceAuto.builder().build())
.addUserMessage("What's the weather in Paris? Use the get_weather tool.")
.build();
client.messages().create(params);
```
```php PHP
$client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 1024,
// strict tool use (uso degli strumenti rigoroso): ogni chiamata rispetta l'input_schema dello strumento
tools: array_map(fn (Tool $tool) => $tool->withStrict(true), $tools),
toolChoice: ToolChoiceAuto::with(),
messages: [
[
'role' => 'user',
'content' => "What's the weather in Paris? Use the get_weather tool.",
],
],
);
```
```ruby Ruby
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
# uso degli strumenti rigoroso: ogni chiamata rispetta l'input_schema dello strumento
tools: tools.map { |tool| tool.merge(strict: true) },
tool_choice: Anthropic::ToolChoiceAuto.new,
messages: [
{ role: "user", content: "What's the weather in Paris? Use the get_weather tool." }
]
)
```
#### I blocchi di ragionamento sono legati al modello e alla conversazione
Sulla Claude API, Claude Fable 5.1 e Claude Mythos 5.1 leggono i blocchi di ragionamento di Claude Opus 5.5; nessun altro modello lo fa. Un router o un fallback che sposta una conversazione da Claude Opus 5.5 a qualsiasi altro modello esegue quei turni senza di essi. Nella direzione opposta, Claude Opus 5.5 legge i blocchi di ragionamento di Claude Opus 5, dei modelli Opus, Sonnet e Haiku precedenti e, sulla Claude API e su Claude Models on Google Cloud (Google managed), di Claude Sonnet 5.5 e Claude Haiku 5.5, ma non dei modelli Claude Fable o Claude Mythos. Mantieni la conversazione in modalità append-only (nessuna modifica al prompt `system`, ai `tools` o ai messaggi precedenti a metà conversazione) affinché i blocchi rimangano validi; Claude Code, claude.ai, Claude Managed Agents e il Claude Agent SDK lo fanno già. Sugli account creati a partire dal 31 agosto 2026, 00:00 UTC, sulla Claude API e sulle piattaforme cloud, una richiesta che riproduce un blocco di ragionamento dopo una tale modifica e lascia `thinking.block_binding.prefix_mismatch_behavior` non impostato riceve un errore 400. Non è necessaria alcuna modifica al codice per le integrazioni append-only. Consulta [I blocchi di ragionamento sono legati al modello e alla conversazione](https://platform.claude.com/docs/it/models/opus-5-5/whats-new-opus-5-5#thinking-blocks-are-tied-to-the-model-that-produced-them) e [Ragionamento preservato](https://platform.claude.com/docs/it/build-with-claude/preserved-thinking).
#### Alcune versioni dello strumento di computer use non sono supportate
Claude Opus 5.5 supporta il computer use tramite il toolset `computer_toolset_20260801`. Su Amazon Bedrock, Claude Opus 5.5 accetta anche lo strumento `computer_20251124` con l’header beta `computer-use-2025-11-24`. Claude Opus 5.5 restituisce un errore 400 per qualsiasi versione dello strumento di computer use che non accetta, come `computer_20251124` sulla Claude API. Non accetta `computer_20250124` su nessuna piattaforma. Sulla Claude API, il messaggio di errore inizia con `'claude-opus-5-5' does not support tool types: computer_20251124.` e poi elenca i tipi di strumento che il modello accetta.
Le integrazioni che usano il toolset non richiedono modifiche. Per spostare un’integrazione `computer_20251124` al toolset, rimuovi l’header beta e invia la voce `computer_toolset_20260801` senza `name` né dimensioni del display. Nel tuo ciclo dell’agente, gestisci ogni blocco `tool_use` membro in un turno e riporta `toolset_name` in ogni risultato. Leggi l’azione dal `name` di ciascun blocco, non da `input.action`. [Migrare da `computer_20251124`](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124) elenca le modifiche al ciclo dell’agente.
Prima. Claude Opus 5 accetta questa richiesta, mentre Claude Opus 5.5 la rifiuta con un errore 400 sulla Claude API:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "anthropic-beta: computer-use-2025-11-24" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5",
"max_tokens": 4096,
"tools": [{
"type": "computer_20251124",
"name": "computer",
"display_width_px": 1024,
"display_height_px": 768
}],
"messages": [{"role": "user", "content": "Open the display settings."}]
}'
```
```bash CLI
ant beta:messages create \
--model claude-opus-5 \
--max-tokens 4096 \
--beta computer-use-2025-11-24 \
--tool '{
type: computer_20251124,
name: computer,
display_width_px: 1024,
display_height_px: 768
}' \
--message '{role: user, content: "Open the display settings."}'
```
```python Python
client.beta.messages.create(
model="claude-opus-5",
max_tokens=4096,
betas=["computer-use-2025-11-24"],
tools=[
{
"type": "computer_20251124",
"name": "computer",
"display_width_px": 1024,
"display_height_px": 768,
}
],
messages=[{"role": "user", "content": "Open the display settings."}],
)
```
```typescript TypeScript
await client.beta.messages.create({
model: "claude-opus-5",
max_tokens: 4096,
betas: ["computer-use-2025-11-24"],
tools: [
{
type: "computer_20251124",
name: "computer",
display_width_px: 1024,
display_height_px: 768
}
],
messages: [{ role: "user", content: "Open the display settings." }]
});
```
```csharp C#
await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5,
MaxTokens = 4096,
Betas = [AnthropicBeta.ComputerUse2025_11_24],
Tools =
[
new BetaToolComputerUse20251124
{
DisplayWidthPx = 1024,
DisplayHeightPx = 768,
},
],
Messages = [new BetaUserMessageParam { Content = "Open the display settings." }],
});
```
```go Go
client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 4096,
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaComputerUse2025_11_24},
Tools: []anthropic.BetaToolUnionParam{
{OfComputerUseTool20251124: &anthropic.BetaToolComputerUse20251124Param{
DisplayWidthPx: 1024,
DisplayHeightPx: 768,
}},
},
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Open the display settings.")),
},
})
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5)
.maxTokens(4096L)
.addBeta(AnthropicBeta.COMPUTER_USE_2025_11_24)
.addTool(BetaToolComputerUse20251124.builder()
.displayWidthPx(1024L)
.displayHeightPx(768L)
.build())
.addUserMessage("Open the display settings.")
.build();
client.beta().messages().create(params);
```
```php PHP
$client->beta->messages->create(
model: Model::CLAUDE_OPUS_5,
maxTokens: 4096,
betas: [AnthropicBeta::COMPUTER_USE_2025_11_24],
tools: [
BetaToolComputerUse20251124::with(
displayWidthPx: 1024,
displayHeightPx: 768,
),
],
messages: [['role' => 'user', 'content' => 'Open the display settings.']],
);
```
```ruby Ruby
client.beta.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5,
max_tokens: 4096,
betas: [Anthropic::AnthropicBeta::COMPUTER_USE_2025_11_24],
tools: [
Anthropic::Beta::BetaToolComputerUse20251124.new(
name: :computer,
display_width_px: 1024,
display_height_px: 768
)
],
messages: [{ role: "user", content: "Open the display settings." }]
)
```
Dopo:
```bash cURL
# nessun header beta; la voce del toolset non accetta nome né dimensioni di visualizzazione
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"tools": [{"type": "computer_toolset_20260801"}],
"messages": [{"role": "user", "content": "Open the display settings."}]
}'
```
```bash CLI
# nessun header beta; la voce del toolset non accetta nome né dimensioni del display
ant messages create \
--model claude-opus-5-5 \
--max-tokens 4096 \
--tool '{type: computer_toolset_20260801}' \
--message '{role: user, content: "Open the display settings."}'
```
```python Python
client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
# nessun header beta; la voce del toolset non accetta nome né dimensioni di visualizzazione
tools=[{"type": "computer_toolset_20260801"}],
messages=[{"role": "user", "content": "Open the display settings."}],
)
```
```typescript TypeScript
await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
// nessun header beta; la voce del toolset non accetta nome né dimensioni di visualizzazione
tools: [{ type: "computer_toolset_20260801" }],
messages: [{ role: "user", content: "Open the display settings." }]
});
```
```csharp C#
await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
// nessun header beta; la voce del toolset non accetta né nome né dimensione di visualizzazione
Tools = [new ComputerToolset20260801()],
Messages = [new UserMessageParam { Content = "Open the display settings." }],
});
```
```go Go
client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
// nessun header beta; la voce del toolset non accetta nome né dimensioni di visualizzazione
Tools: []anthropic.ToolUnionParam{
{OfComputerToolset20260801: &anthropic.ComputerToolset20260801Param{}},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Open the display settings.")),
},
})
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
// nessun header beta; la voce del toolset non accetta nome né dimensioni di visualizzazione
.addTool(ComputerToolset20260801.builder().build())
.addUserMessage("Open the display settings.")
.build();
client.messages().create(params);
```
```php PHP
$client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 4096,
// nessun header beta; la voce del toolset non accetta nome né dimensioni di visualizzazione
tools: [ComputerToolset20260801::with()],
messages: [['role' => 'user', 'content' => 'Open the display settings.']],
);
```
```ruby Ruby
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 4096,
# nessun header beta; la voce del toolset non accetta nome né dimensioni di visualizzazione
tools: [Anthropic::ComputerToolset20260801.new],
messages: [{ role: "user", content: "Open the display settings." }]
)
```
### Il testo tra le chiamate agli strumenti viene restituito nei blocchi di ragionamento
Su Claude Opus 5, il testo che il modello scrive tra le chiamate agli strumenti viene restituito come blocchi `text`. Su Claude Opus 5.5, come su Claude Fable 5.1, quella narrazione viene restituita come [blocchi `thinking` di aggiornamento sull’avanzamento](https://platform.claude.com/docs/it/build-with-claude/thinking#progress-updates), al massimo uno prima di ogni chiamata a uno strumento. Con il valore predefinito di `thinking.display`, ovvero `"omitted"`, il loro campo `thinking` è vuoto. Nessuna richiesta fallisce, ma un’applicazione che trasmette in streaming quel testo ai propri utenti come aggiornamenti sull’avanzamento diventa silenziosa tra le chiamate agli strumenti. Per ripristinare gli aggiornamenti, leggili dai blocchi `thinking` e imposta un valore di `display` che restituisca il loro testo: `"updates"` (beta, header `thinking-display-updates-2026-08-18`) restituisce gli aggiornamenti sull’avanzamento mantenendo nascosto il ragionamento, mentre `"summarized"` restituisce entrambi, mescolati insieme. Poi visualizza ogni blocco `thinking` non vuoto prima del blocco `tool_use` che lo segue, e restituisci i blocchi senza modifiche insieme al resto del turno dell’assistente. Consulta [Aggiornamenti sull’avanzamento rivolti agli utenti](https://platform.claude.com/docs/it/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#user-facing-progress-updates).
### Classificatori di sicurezza e fallback
Claude Opus 5.5 può restituire `stop_reason: "refusal"` con una categoria in `stop_details`. I suoi classificatori coprono un insieme di categorie più ampio rispetto a quelli di Claude Opus 5, quindi aspettati valori di `stop_details.category` come `"bio"` oltre a `"cyber"` e `"reasoning_extraction"`; consulta la [tabella delle categorie di rifiuto](https://platform.claude.com/docs/it/build-with-claude/refusals-and-fallback#refusal-response). Gestisci i rifiuti e configura il [fallback lato server](https://platform.claude.com/docs/it/build-with-claude/refusals-and-fallback#server-side-fallback) o un tuo meccanismo di nuovo tentativo (il fallback lato server non ripete le richieste rifiutate con `"reasoning_extraction"`; quel rifiuto ti viene restituito); consulta [Rifiuti e fallback](https://platform.claude.com/docs/it/build-with-claude/refusals-and-fallback) e [Rifiuti di salvaguardia](https://platform.claude.com/docs/it/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#safeguard-refusals).
### Modifiche consigliate
1. **Esegui di nuovo l’analisi dei livelli di effort.** L’effort è l’unico controllo del ragionamento su Claude Opus 5.5, e il suo valore predefinito è `medium`, mentre quello di Claude Opus 5 è `high`, quindi una richiesta che omette `effort` ora viene eseguita a `medium`. Scendi di livello dove la qualità regge e sali per il lavoro più impegnativo. Consulta [Effort](https://platform.claude.com/docs/it/build-with-claude/effort).
2. **Rivaluta le istruzioni del prompt specifiche del modello.** Le istruzioni ottimizzate per il comportamento di Claude Opus 5 potrebbero non essere più necessarie; consulta [Prompting per Claude Opus 5.5](https://platform.claude.com/docs/it/build-with-claude/prompt-engineering/prompting-claude-opus-5-5). Se lavoravi con il ragionamento disabilitato, consulta anche [Prompt scritti per il ragionamento disabilitato](https://platform.claude.com/docs/it/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#prompts-written-for-thinking-disabled).
3. **Esegui test in un ambiente di sviluppo** prima di spostare il traffico di produzione.
## Migrazione a Claude Opus 5.5 da Claude Opus 4.8
Per prima cosa, segui [Requisiti che ogni richiesta a Claude Opus 5.5 deve soddisfare](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#request-requirements), [Gestire il ragionamento in ogni risposta](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#thinking-in-every-response) e [Migrazione a Claude Opus 5.5 da Claude Opus 5](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#migrating-from-claude-opus-5). Usa `claude-opus-4-8` come ID del modello da sostituire. Quest’ultima sezione si applica al codice su Claude Opus 4.8 così com’è scritta, perché Claude Opus 4.8, come Claude Opus 5:
* Accetta `thinking: {"type": "disabled"}`, la scelta forzata dello strumento e lo strumento `computer_20251124`.
* Restituisce il testo tra le chiamate agli strumenti come blocchi `text`.
* Usa per impostazione predefinita l’effort `high`.
Questa sezione aggiunge ciò che è cambiato tra Claude Opus 4.8 e Claude Opus 5. Per una checklist, consulta i primi due gruppi della [checklist di migrazione](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#migration-checklist).
### Cosa è cambiato
1. **Il ragionamento viene eseguito sulle richieste che lo omettevano:** Su Claude Opus 4.8, il ragionamento è disattivato a meno che tu non lo richieda. Su Claude Opus 5.5, una richiesta senza campo `thinking` viene eseguita con il ragionamento, quindi ogni punto in [Gestire il ragionamento in ogni risposta](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#thinking-in-every-response) rappresenta una modifica per quel codice. Se il tuo codice non ha mai inviato un campo `thinking`, non c’è nulla da rimuovere secondo il [prima e dopo per il ragionamento](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#thinking-cant-be-disabled).
2. **Minimo più basso per la cache dei prompt:** La lunghezza minima del prompt memorizzabile nella cache su Claude Opus 5.5 è di 512 token, rispetto ai 1.024 token di Claude Opus 4.8. I prompt che erano troppo brevi per la cache su Claude Opus 4.8 possono creare voci di cache, senza alcuna modifica al codice. Consulta [Cache dei prompt](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#cache-limitations) per i minimi di ciascun modello.
3. **Priority Tier non è supportato:** [Priority Tier](https://platform.claude.com/docs/it/api/service-tiers#supported-models) non è supportato su Claude Opus 5.5, mentre Claude Opus 4.8 lo mantiene. Se la tua organizzazione ha un impegno Priority Tier, pianifica la capacità separatamente.
### Modifiche consigliate
Queste modifiche non sono obbligatorie, ma miglioreranno la tua esperienza:
1. **Valuta i budget delle attività (beta):** Per i carichi di lavoro agentici, i [“task budget”](https://platform.claude.com/docs/it/build-with-claude/task-budgets) (budget delle attività) indicano al modello quanti token ha a disposizione per un intero ciclo agentico. Richiedono l’header beta `task-budgets-2026-03-13`.
2. **Valuta le modifiche agli strumenti a metà conversazione (beta):** Le modifiche agli strumenti a metà conversazione ti consentono di aggiungere o rimuovere strumenti tra i turni di una conversazione senza invalidare gli hit della [cache dei prompt](https://platform.claude.com/docs/it/build-with-claude/prompt-caching) sui turni precedenti. Modificare l’array `tools` stesso invalida il prefisso memorizzato nella cache. Su Claude API, Claude Platform on AWS e Claude Models on Google Cloud (Anthropic managed), invia l’header beta `inline-tools-2026-09-15`. L’header `mid-conversation-tool-changes-2026-07-01` funziona per le modifiche che indicano uno strumento per riferimento, su Claude API, Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) e Claude Models on Google Cloud (Google managed).
## Migrazione a Claude Opus 5.5 da Claude Opus 4.7
Per prima cosa, segui [Requisiti che ogni richiesta a Claude Opus 5.5 deve soddisfare](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#request-requirements), [Gestire il ragionamento in ogni risposta](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#thinking-in-every-response), [Migrazione a Claude Opus 5.5 da Claude Opus 5](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#migrating-from-claude-opus-5) e [Migrazione a Claude Opus 5.5 da Claude Opus 4.8](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#migrating-from-claude-opus-4-8). Usa `claude-opus-4-7` come ID del modello da sostituire. Quelle sezioni si applicano al codice su Claude Opus 4.7 così come sono scritte. Come Claude Opus 4.8, accetta `thinking: {"type": "disabled"}`, la scelta forzata dello strumento e lo strumento `computer_20251124`. Usa per impostazione predefinita l’effort `high` e funziona senza ragionamento a meno che tu non lo richieda.
Questa sezione aggiunge ciò che è cambiato dopo Claude Opus 4.7. Se il tuo codice è su Claude Opus 4.6 o precedenti, prosegui con [Migrazione a Claude Opus 5.5 da Claude Opus 4.6 e modelli Opus precedenti](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#migrating-from-claude-opus-46) dopo questa sezione. Quella sezione aggiunge le modifiche incompatibili entrate in vigore con Claude Opus 4.7. Per una checklist, consulta i primi tre gruppi della [checklist di migrazione](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#migration-checklist).
### Cosa è cambiato
Nessuno di questi elementi aggiunge una modifica incompatibile a quelle delle sezioni precedenti; vale la pena verificarli dopo aver cambiato l’ID del modello.
1. **Livelli di effort ricalibrati:** L’allocazione di token alla base di ciascun livello di effort cambia su Claude Opus 5.5 rispetto a Claude Opus 4.7. Il valore predefinito è `medium`, mentre quello di Claude Opus 4.7 è `high`. Esegui una nuova analisi dei livelli di effort sulle tue valutazioni invece di riportare un’impostazione ottimizzata per Claude Opus 4.7. Consulta [Effort](https://platform.claude.com/docs/it/build-with-claude/effort).
2. **La finestra di contesto da 1M è quella predefinita:** Claude Opus 5.5 offre per impostazione predefinita l’intera [finestra di contesto](https://platform.claude.com/docs/it/build-with-claude/context-windows) da 1M token senza alcun header beta. Se il tuo client passa un header beta per la finestra di contesto per compatibilità con modelli precedenti, rimuovilo.
3. **Messaggi di sistema a metà conversazione:** Su Claude API, Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) e Claude Models on Google Cloud (Google managed), Claude Opus 5.5 accetta messaggi `role: "system"` immediatamente dopo un turno utente nell’array `messages` (nel rispetto delle [regole di posizionamento](https://platform.claude.com/docs/it/build-with-claude/mid-conversation-system-messages#limitations)). Usa il campo `system` di primo livello per le istruzioni che si applicano fin dall’inizio. Claude Opus 4.7 rifiuta `role: "system"` in `messages` con un errore 400. Se mantieni percorsi di codice che ricostruiscono l’intera cronologia dei messaggi per aggiornare le istruzioni, puoi semplificarli e preservare gli hit della [cache dei prompt](https://platform.claude.com/docs/it/build-with-claude/prompt-caching) sui turni precedenti.
4. **Dettagli di interruzione per rifiuto:** Quando il modello rifiuta una richiesta, Claude Opus 5.5 restituisce un oggetto `stop_details` che indica la categoria del rifiuto, insieme al motivo di interruzione `refusal`. Claude Opus 4.7 restituisce lo stesso oggetto, quindi questo è rilevante solo se la tua gestione dei motivi di interruzione non lo legge ancora. Non è richiesto alcun header beta e non è possibile disattivarlo. Se la tua gestione dei motivi di interruzione non lo legge ancora, consulta [Gestione dei motivi di interruzione](https://platform.claude.com/docs/it/build-with-claude/handling-stop-reasons). Claude Opus 5.5 rifiuta in un numero maggiore di categorie; consulta [Classificatori di sicurezza e fallback](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#safety-classifiers-and-fallback).
5. **Modalità veloce:** Claude Opus 5.5 supporta la [“fast mode”](https://platform.claude.com/docs/it/build-with-claude/fast-mode) (modalità veloce) su Claude API. La modalità veloce non è disponibile su Claude Opus 4.7, dove le richieste con `speed: "fast"` restituiscono un errore. Imposta `speed: "fast"` nelle tue richieste. Claude Opus 5.5 non richiede un header beta.
6. **Toolset di computer use e strumento di browser use:** Claude Opus 5.5 supporta il [“computer use”](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool) (uso del computer) come toolset `computer_toolset_20260801` e lo [strumento di “browser use”](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool) (uso del browser) per le attività all’interno delle pagine web. Claude Opus 4.7 non supporta nessuno dei due. Per migrare un’integrazione `computer_20251124` al toolset, consulta la [modifica non retrocompatibile del computer use](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#computer-use-toolset).
## Migrazione a Claude Opus 5.5 da Claude Opus 4.6 e modelli Opus precedenti
Per prima cosa, esamina ogni sezione precedente, nell’ordine della pagina. Si tratta di [Cosa deve soddisfare ogni richiesta a Claude Opus 5.5](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#request-requirements), [Gestire il ragionamento in ogni risposta](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#thinking-in-every-response) e delle sezioni relative a [Claude Opus 5](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#migrating-from-claude-opus-5), [Claude Opus 4.8](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#migrating-from-claude-opus-4-8) e [Claude Opus 4.7](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#migrating-from-claude-opus-47). Tali sezioni si applicano così come sono scritte al codice su Claude Opus 4.6. Come Claude Opus 4.7, accetta `thinking: {"type": "disabled"}`, la scelta forzata dello strumento e lo strumento `computer_20251124`. Usa per impostazione predefinita l’effort `high` ed è eseguito senza ragionamento a meno che tu non lo richieda. Anche Claude Opus 4.5 e i modelli Opus precedenti accettano `thinking: {"type": "disabled"}` e la scelta forzata dello strumento, e sono eseguiti senza ragionamento a meno che tu non lo richieda, quindi quelle sezioni si applicano anche a loro.
Questa sezione aggiunge ciò che è cambiato in Claude Opus 4.7, con `claude-opus-4-6` come ID del modello da sostituire. Le sue due sottosezioni aggiungono ciò che è cambiato prima, per chi utilizza [Claude Opus 4.5 o precedenti](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#migrating-from-claude-opus-45) e [Claude 4.1 o precedenti](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#migrating-from-claude-4-1-or-earlier). Per una checklist, consulta la [checklist di migrazione](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#migration-checklist) fino al gruppo che nomina il tuo modello.
### Modifiche che causano interruzioni
1. **Ragionamento esteso rimosso:** `thinking: {"type": "enabled", "budget_tokens": N}` non è più supportato su Claude Opus 4.7 e sui modelli successivi e restituisce un errore 400. Passa all’[“adaptive thinking” (ragionamento adattivo)](https://platform.claude.com/docs/it/build-with-claude/thinking) (`thinking: {"type": "adaptive"}`) e usa il [parametro effort](https://platform.claude.com/docs/it/build-with-claude/effort) per controllare la profondità del ragionamento. Su Claude Opus 5.5, il ragionamento adattivo è sempre attivo: `thinking: {"type": "adaptive"}` è valido ed equivale a omettere completamente il campo `thinking`.
Prima (Claude Opus 4.6):
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-4-6",
"max_tokens": 16000,
"thinking": {
"type": "enabled",
"budget_tokens": 10000
},
"messages": [
{
"role": "user",
"content": "..."
}
]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-4-6
max_tokens: 16000
thinking:
type: enabled
budget_tokens: 10000
messages:
- role: user
content: "..."
YAML
```
```python Python
client.messages.create(
model="claude-opus-4-6",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 10000},
messages=[{"role": "user", "content": "..."}],
)
```
```typescript TypeScript
await client.messages.create({
model: "claude-opus-4-6",
max_tokens: 16000,
thinking: { type: "enabled", budget_tokens: 10000 },
messages: [{ role: "user", content: "..." }]
});
```
```csharp C#
using Anthropic;
using Anthropic.Models.Messages;
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus4_6,
MaxTokens = 16000,
Thinking = new ThinkingConfigEnabled(budgetTokens: 10000),
Messages = [new UserMessageParam { Content = "..." }]
};
var response = await client.Messages.Create(parameters);
Console.WriteLine(response);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus4_6,
MaxTokens: 16000,
Thinking: anthropic.ThinkingConfigParamOfEnabled(10000),
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_6)
.maxTokens(16000L)
.enabledThinking(10000L)
.addUserMessage("...")
.build();
Message response = client.messages().create(params);
IO.println(response);
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 16000,
messages: [['role' => 'user', 'content' => '...']],
model: 'claude-opus-4-6',
thinking: ['type' => 'enabled', 'budget_tokens' => 10000],
);
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-4-6",
max_tokens: 16000,
thinking: {
type: "enabled",
budget_tokens: 10000
},
messages: [
{ role: "user", content: "..." }
]
)
```
Dopo (Claude Opus 5.5), dove differiscono le righe dell’ID del modello, di `thinking` e di `output_config`:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 16000,
"thinking": {
"type": "adaptive"
},
"output_config": {
"effort": "high"
},
"messages": [
{
"role": "user",
"content": "..."
}
]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 16000
thinking:
type: adaptive
output_config:
effort: high
messages:
- role: user
content: "..."
YAML
```
```python Python
client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
thinking={"type": "adaptive"},
output_config={"effort": "high"}, # or "max", "xhigh", "medium", "low"
messages=[{"role": "user", "content": "..."}],
)
```
```typescript TypeScript
await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 16000,
thinking: { type: "adaptive" },
output_config: { effort: "high" }, // or "max", "xhigh", "medium", "low"
messages: [{ role: "user", content: "..." }]
});
```
```csharp C#
using Anthropic;
using Anthropic.Models.Messages;
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 16000,
Thinking = new ThinkingConfigAdaptive(),
OutputConfig = new OutputConfig { Effort = Effort.High }, // or Max, Xhigh, Medium, Low
Messages = [new UserMessageParam { Content = "..." }]
};
var response = await client.Messages.Create(parameters);
Console.WriteLine(response);
```
```go Go
client := anthropic.NewClient()
response, 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.OutputConfigEffortHigh, // or Max, Xhigh, Medium, Low
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(16000L)
.thinking(ThinkingConfigAdaptive.builder().build())
.outputConfig(OutputConfig.builder()
.effort(OutputConfig.Effort.HIGH) // or MAX, XHIGH, MEDIUM, LOW
.build())
.addUserMessage("...")
.build();
Message response = client.messages().create(params);
IO.println(response);
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 16000,
messages: [['role' => 'user', 'content' => '...']],
model: Model::CLAUDE_OPUS_5_5,
thinking: ['type' => 'adaptive'],
outputConfig: ['effort' => 'high'], // or 'max', 'xhigh', 'medium', 'low'
);
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 16000,
thinking: {
type: "adaptive"
},
output_config: {
effort: "high" # or "max", "xhigh", "medium", "low"
},
messages: [
{ role: "user", content: "..." }
]
)
```
Il ragionamento adattivo può essere orientato tramite il prompting e il [parametro effort](https://platform.claude.com/docs/it/build-with-claude/effort), che sostituisce il budget di ragionamento come modo per controllare quanto il modello ragiona. Esegui una serie di test sui livelli di effort con le tue valutazioni invece di convertire un valore di `budget_tokens`. La [tabella dei livelli di effort](https://platform.claude.com/docs/it/build-with-claude/effort#effort-levels) descrive quando usare ciascun livello, e [Livelli di effort consigliati per Claude Opus 5.5](https://platform.claude.com/docs/it/build-with-claude/effort#recommended-effort-levels-for-claude-opus-5-5) copre questo modello.
2. **Parametri di campionamento rimossi:** Ometti `temperature`, `top_p` e `top_k`. Il prompting è il modo consigliato per guidare il comportamento del modello su Claude Opus 5.5. Se usavi `temperature = 0` per il determinismo, tieni presente che non ha mai garantito output identici sui modelli precedenti.
3. **Contenuto del ragionamento omesso per impostazione predefinita:** I blocchi di ragionamento compaiono ancora nello stream di risposta su Claude Opus 4.7 e sui modelli successivi, ma il loro campo `thinking` è vuoto a meno che tu non scelga esplicitamente di attivarlo. Si tratta di una modifica silenziosa rispetto a Claude Opus 4.6, dove l’impostazione predefinita era restituire il testo di ragionamento riassunto. Per ripristinarlo, consulta il punto 4 di [Gestire il ragionamento in ogni risposta](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#thinking-in-every-response).
4. **Conteggio dei token aggiornato:** Claude Opus 4.7 ha introdotto un nuovo tokenizer, utilizzato anche dai modelli Opus successivi, incluso Claude Opus 5.5. Contribuisce a migliorare le prestazioni su un’ampia gamma di attività e potrebbe usare da circa 1x a 1,35x token nell’elaborazione del testo rispetto ai modelli precedenti a Claude Opus 4.7 (fino a circa il 35 percento in più, a seconda del contenuto).
[`/v1/messages/count_tokens`](https://platform.claude.com/docs/it/build-with-claude/token-counting) restituisce un numero di token diverso per Claude Opus 5.5 rispetto a quello restituito per Claude Opus 4.6. L’efficienza dei token può variare in base alla forma del carico di lavoro.
Aggiorna i tuoi parametri `max_tokens` per dare un margine aggiuntivo, inclusi i trigger di compattazione, e ritesta qualsiasi percorso di codice che stima i token lato client o presuppone un rapporto fisso token/caratteri. Usa l’endpoint di [Conteggio dei token](https://platform.claude.com/docs/it/build-with-claude/token-counting) per verificare. Gli interventi sul prompting, [`task_budget`](https://platform.claude.com/docs/it/build-with-claude/task-budgets) ed [`effort`](https://platform.claude.com/docs/it/build-with-claude/effort) possono aiutare a controllare i costi; questi controlli potrebbero comportare un compromesso sull’intelligenza del modello.
5. **Rimozione del prefill (già in vigore su Claude Opus 4.6):** Il prefill dei messaggi dell’assistente restituisce un errore 400 su Claude Opus 4.6 e sui modelli Opus successivi, incluso Claude Opus 5.5, quindi si tratta di una modifica solo se provieni da Claude Opus 4.5 o precedenti. Usa invece gli [output strutturati](https://platform.claude.com/docs/it/build-with-claude/structured-outputs) o le istruzioni nel prompt di sistema.
### Modifiche di comportamento
Claude Opus 4.7 ha introdotto differenze comportamentali rispetto a Claude Opus 4.6 che non sono modifiche dell’API che causano interruzioni. Queste tre riguardano il codice o lo scaffolding:
1. **Aggiornamenti sui progressi integrati nelle tracce agentiche:** Claude Opus 4.7 fornisce all’utente aggiornamenti più regolari e di qualità superiore durante le lunghe tracce agentiche. Se hai aggiunto uno scaffolding per forzare messaggi di stato intermedi (“Dopo ogni 3 chiamate agli strumenti, riassumi i progressi”), prova a rimuoverlo. Su Claude Opus 5.5 questi aggiornamenti arrivano in blocchi `thinking`, che sono vuoti con il valore predefinito di `thinking.display`. Per riceverli, consulta [Il testo tra le chiamate agli strumenti viene restituito nei blocchi di ragionamento](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#text-between-tool-calls). Per definirne la lunghezza e il contenuto, consulta [Aggiornamenti sui progressi rivolti all’utente](https://platform.claude.com/docs/it/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#user-facing-progress-updates).
2. **Salvaguardie di cybersicurezza in tempo reale:** Queste salvaguardie sono nuove in Claude Opus 4.7: le richieste che riguardano argomenti vietati o ad alto rischio potrebbero portare a rifiuti. Per attività di sicurezza legittime come penetration testing, ricerca di vulnerabilità o red-teaming, fai domanda al [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude-opus-and-sonnet) per richiedere restrizioni ridotte. La modalità di richiesta dipende da come accedi a Claude.
3. **Supporto per immagini ad alta risoluzione:** Claude Opus 4.7 è il primo modello Claude con supporto per immagini ad alta risoluzione. La risoluzione massima delle immagini è di 2.576 pixel sul lato lungo, rispetto ai 1.568 pixel dei modelli precedenti. Questo consente miglioramenti nei carichi di lavoro con forte componente visiva ed è particolarmente prezioso per il computer use, la comprensione di screenshot e l’analisi di documenti.
Il supporto per l’alta risoluzione è automatico e non richiede alcun header beta né attivazione lato client. Due aspetti da pianificare:
* Le immagini a piena risoluzione possono usare fino a circa 3 volte più token immagine rispetto ai modelli precedenti (fino a 4.784 token per ogni immagine, rispetto al limite precedente di circa 1.600 token). Ricalcola il budget di `max_tokens` e le aspettative di costo per i carichi di lavoro con molte immagini, oppure riduci la risoluzione prima dell’invio se non hai bisogno della fedeltà aggiuntiva.
* Le coordinate di puntamento e dei riquadri di delimitazione restituite dal modello sono in rapporto 1:1 con i pixel effettivi dell’immagine su Claude Opus 4.7, quindi non è necessaria alcuna conversione con fattore di scala.
Consulta [Supporto per immagini ad alta risoluzione su Claude Opus 4.7](https://platform.claude.com/docs/it/build-with-claude/vision#high-resolution-image-support-on-claude-opus-4-7) per i dettagli.
Per le differenze lato prompt, consulta [Prompting di Claude Opus 5.5](https://platform.claude.com/docs/it/build-with-claude/prompt-engineering/prompting-claude-opus-5-5) e [Best practice per il prompting](https://platform.claude.com/docs/it/build-with-claude/prompt-engineering/claude-prompting-best-practices).
### Migrazione da Claude Opus 4.5 o precedenti
Se stai migrando direttamente a Claude Opus 5.5 da Claude Opus 4.5, Claude Opus 4.1 o un modello precedente, leggi questa pagina dall’inizio: per prima cosa esamina ogni sezione precedente, nell’ordine della pagina. Poi esamina le [modifiche che causano interruzioni per la migrazione da Claude Opus 4.6](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#opus-46-breaking-changes) più sopra in questa sezione. Quindi applica le seguenti modifiche cumulative, entrate in vigore tra Claude Opus 4.5 e Claude Opus 4.7. Se utilizzi Claude Opus 4.1 o precedenti, prosegui con [Migrazione da Claude 4.1 o precedenti](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#migrating-from-claude-4-1-or-earlier) dopo questa sottosezione.
#### Modifiche che causano interruzioni
1. La **rimozione del prefill** è trattata nelle [modifiche che causano interruzioni per la migrazione da Claude Opus 4.6](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#opus-46-breaking-changes).
2. **Quoting dei parametri degli strumenti:** Claude Opus 4.6 e i modelli successivi potrebbero produrre un escaping delle stringhe JSON leggermente diverso negli argomenti delle chiamate agli strumenti (ad esempio, una gestione diversa degli escape Unicode o dell’escaping della barra). Se analizzi l’`input` delle chiamate agli strumenti come stringa grezza invece di usare un parser JSON, controlla la tua logica di parsing. I parser JSON standard (come `json.loads()` o `JSON.parse()`) gestiscono automaticamente queste differenze.
#### Modifiche consigliate
Il primo punto è obbligatorio su Claude Opus 5.5; gli altri sono consigliati.
1. **Migra al ragionamento adattivo (obbligatorio):** `thinking: {"type": "enabled", "budget_tokens": N}` restituisce un errore 400 su Claude Opus 4.7 e sui modelli successivi. Il prima e dopo si trova al punto 1 delle [modifiche che causano interruzioni per la migrazione da Claude Opus 4.6](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#opus-46-breaking-changes). La migrazione passa inoltre da `client.beta.messages.create()` (csharp: `client.Beta.Messages.Create()`; go: `client.Beta.Messages.New()`; java: `client.beta().messages().create()`; php: `$client->beta->messages->create()`; cli: `ant beta:messages create`) a `client.messages.create()` (csharp: `client.Messages.Create()`; go: `client.Messages.New()`; java: `client.messages().create()`; php: `$client->messages->create()`; cli: `ant messages create`): il ragionamento adattivo e l’effort non richiedono il namespace beta dell’SDK né alcun header beta.
2. **Rimuovi l’header beta di effort:** Il parametro effort non richiede un header beta. Rimuovi la beta `effort-2025-11-24` dalle tue richieste.
3. **Rimuovi l’header beta dello streaming granulare degli strumenti:** Lo streaming granulare degli strumenti non richiede un header beta. Rimuovi la beta `fine-grained-tool-streaming-2025-05-14` dalle tue richieste.
4. **Rimuovi l’header beta del ragionamento interleaved:** Con il ragionamento adattivo, il ragionamento interleaved è automatico su ogni modello che supporta il ragionamento adattivo. Rimuovi la beta `interleaved-thinking-2025-05-14` dalle tue richieste.
5. **Migra a output\_config.format:** Se usi gli output strutturati, aggiorna `output_format={...}` a `output_config={"format": {...}}`. Il parametro `output_format` è deprecato e verrà rimosso in futuro. Per usarlo comunque, aggiungi l’header beta `structured-outputs-2025-11-13`. Senza di esso, l’API restituisce un errore 400. L’SDK Python (v1.0 e successive) non accetta `output_format={...}` su `client.beta.messages.create()` o `count_tokens()`. L’argomento `output_format=Model` degli helper `parse()` e `stream()` rimane invariato.
### Migrazione da Claude 4.1 o precedenti
Se stai migrando direttamente a Claude Opus 5.5 da Claude Opus 4.1 o modelli precedenti, applica prima tutto quanto indicato in [Migrazione da Claude Opus 4.5 o precedenti](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#migrating-from-claude-opus-45). Quella sottosezione inizia con ogni sezione precedente, quindi in pratica leggi questa pagina dall’inizio. Poi applica le modifiche aggiuntive di questa sottosezione.
#### Ulteriori modifiche che causano interruzioni
1. **Rimuovi i parametri di campionamento:** Trattato in [Parametri di campionamento rimossi](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#opus-46-breaking-changes).
2. **Aggiorna le versioni degli strumenti**
Questa è una modifica incompatibile durante la migrazione dai modelli Claude 3.x.
Aggiorna alle versioni attuali degli strumenti. Rimuovi qualsiasi codice che usa il comando `undo_edit`.
```python Python
# Prima
tools = [{"type": "text_editor_20250124", "name": "str_replace_editor"}]
# Dopo
tools = [{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]
```
```typescript TypeScript
// Prima
const legacyTools = [{ type: "text_editor_20250124", name: "str_replace_editor" }];
// Dopo
const tools = [{ type: "text_editor_20250728", name: "str_replace_based_edit_tool" }];
```
```csharp C#
var parameters = new MessageCreateParams
{
// Prima: {"type": "text_editor_20250124", "name": "str_replace_editor"}
// Dopo:
Tools = [new ToolTextEditor20250728()],
// ...
};
```
```go Go
params := anthropic.MessageNewParams{
// Prima: {"type": "text_editor_20250124", "name": "str_replace_editor"}
// Dopo:
Tools: []anthropic.ToolUnionParam{
{OfTextEditor20250728: &anthropic.ToolTextEditor20250728Param{}},
},
// ...
}
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
// Prima: {"type": "text_editor_20250124", "name": "str_replace_editor"}
// Dopo:
.addTool(ToolTextEditor20250728.builder().build())
// ...
.build();
```
```php PHP
$message = $client->messages->create(
// Prima: ['type' => 'text_editor_20250124', 'name' => 'str_replace_editor']
// Dopo:
tools: [new ToolTextEditor20250728()],
// ...
);
```
```ruby Ruby
# Prima
legacy_tools = [{type: "text_editor_20250124", name: "str_replace_editor"}]
# Dopo
tools = [{type: "text_editor_20250728", name: "str_replace_based_edit_tool"}]
```
* **Editor di testo:** Usa `text_editor_20250728` e `str_replace_based_edit_tool`. Consulta la documentazione dello [strumento editor di testo](https://platform.claude.com/docs/it/agents-and-tools/tool-use/text-editor-tool) per i dettagli.
* **Esecuzione del codice:** Aggiorna a `code_execution_20260521`. Consulta la documentazione dello [strumento di esecuzione del codice](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#upgrade-to-latest-tool-version) per le istruzioni di migrazione.
* **Computer use:** Usa il toolset `computer_toolset_20260801` al posto di `computer_20250124`, che Claude Opus 5.5 non accetta. Su Amazon Bedrock funziona anche `computer_20251124`. Consulta la [modifica incompatibile del computer use](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#computer-use-toolset).
3. **Gestisci il motivo di interruzione `refusal`**
Aggiorna la tua applicazione per [gestire i motivi di interruzione `refusal`](https://platform.claude.com/docs/it/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals):
```python Python
response = client.messages.create(...)
if response.stop_reason == "refusal":
# Gestisci il rifiuto in modo appropriato
pass
```
```typescript TypeScript
const response = await client.messages.create(/* ... */);
if (response.stop_reason === "refusal") {
// Gestisci il rifiuto in modo appropriato
}
```
```csharp C#
var response = await client.Messages.Create(...);
if (response.StopReason?.Value() == StopReason.Refusal)
{
// Gestisci il rifiuto in modo appropriato
}
```
```go Go
response, _ := client.Messages.New(ctx, params) // your existing request
if response.StopReason == anthropic.StopReasonRefusal {
// Gestisci il rifiuto in modo appropriato
}
```
```java Java
Message response = client.messages().create(...);
StopReason reason = response.stopReason().orElse(StopReason.END_TURN);
if (reason.equals(StopReason.REFUSAL)) {
// Gestisci il rifiuto in modo appropriato
}
```
```php PHP
$response = $client->messages->create(...);
if ($response->stopReason === 'refusal') {
// Gestisci il rifiuto in modo appropriato
}
```
```ruby Ruby
response = client.messages.create(...)
if response.stop_reason == :refusal
# Gestisci il rifiuto in modo appropriato
end
```
4. **Gestisci il motivo di interruzione `model_context_window_exceeded`**
I modelli Claude 4.5 e successivi restituiscono un motivo di interruzione `model_context_window_exceeded` quando la generazione si interrompe per aver raggiunto il limite della finestra di contesto, anziché il limite `max_tokens` richiesto. Aggiorna la tua applicazione per gestire questo nuovo motivo di interruzione:
```python Python
response = client.messages.create(...)
if response.stop_reason == "model_context_window_exceeded":
# Gestisci in modo appropriato il limite della finestra di contesto
pass
```
```typescript TypeScript
const response = await client.messages.create(/* ... */);
if (response.stop_reason === "model_context_window_exceeded") {
// Gestisci in modo appropriato il limite della finestra di contesto
}
```
```csharp C#
var response = await client.Messages.Create(...);
if (response.StopReason?.Raw() == "model_context_window_exceeded")
{
// Gestisci in modo appropriato il limite della finestra di contesto
}
```
```go Go
response, _ := client.Messages.New(ctx, params) // your existing request
if response.StopReason == "model_context_window_exceeded" {
// Gestisci in modo appropriato il limite della finestra di contesto
}
```
```java Java
Message response = client.messages().create(...);
StopReason reason = response.stopReason().orElse(StopReason.END_TURN);
if (reason.equals(StopReason.of("model_context_window_exceeded"))) {
// Gestisci in modo appropriato il limite della finestra di contesto
}
```
```php PHP
$response = $client->messages->create(...);
if ($response->stopReason === 'model_context_window_exceeded') {
// Gestisci in modo appropriato il limite della finestra di contesto
}
```
```ruby Ruby
response = client.messages.create(...)
if response.stop_reason == :model_context_window_exceeded
# Gestisci in modo appropriato il limite della finestra di contesto
end
```
5. **Verifica la gestione dei parametri degli strumenti (newline finali)**
I modelli Claude 4.5 e successivi preservano i newline finali nei parametri stringa delle chiamate agli strumenti, che in precedenza venivano rimossi. Se i tuoi strumenti si basano sulla corrispondenza esatta delle stringhe con i parametri delle chiamate agli strumenti, verifica che la tua logica gestisca correttamente i newline finali.
6. **Aggiorna i tuoi prompt per i cambiamenti comportamentali**
I modelli Claude 4 e successivi hanno uno stile di comunicazione più conciso e diretto e richiedono indicazioni esplicite. Consulta le [best practice per il prompting](https://platform.claude.com/docs/it/build-with-claude/prompt-engineering/claude-prompting-best-practices) per indicazioni sull’ottimizzazione.
#### Ulteriori modifiche consigliate
* **Header beta:** Rimuovi `token-efficient-tools-2025-02-19` e `output-128k-2025-02-19`. Tutti i modelli Claude 4 e successivi hanno l’uso degli strumenti efficiente in termini di token integrato, e questi header non hanno alcun effetto.
## Migrazione a Claude Opus 5.5 da Claude Sonnet 5
Esamina [Cosa deve soddisfare ogni richiesta a Claude Opus 5.5](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#request-requirements), [Gestire il ragionamento in ogni risposta](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#thinking-in-every-response) e [Migrazione a Claude Opus 5.5 da Claude Opus 5](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#migrating-from-claude-opus-5). Usa `claude-sonnet-5` come ID del modello da sostituire. Quest’ultima sezione si applica così come è scritta al codice su Claude Sonnet 5, perché Claude Sonnet 5, come Claude Opus 5:
* Viene eseguito con il ragionamento attivo per impostazione predefinita e accetta `thinking: {"type": "disabled"}`, nel suo caso a qualsiasi livello di effort.
* Accetta la scelta forzata dello strumento e lo strumento `computer_20251124`.
* Restituisce il testo tra le chiamate agli strumenti come blocchi `text`.
* Usa per impostazione predefinita l’effort `high`.
Il ragionamento esteso manuale, i parametri di campionamento e il prefill dell’assistente restituiscono un errore 400 su entrambi i modelli, quindi lì non cambia nulla. Nessuna delle modifiche obbligatorie nelle sezioni per Claude Opus 4.8, Claude Opus 4.7 e Claude Opus 4.6 si applica a te.
### Cosa è cambiato
1. **Messaggi di sistema a metà conversazione:** Su Claude API, Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) e Claude Models on Google Cloud (Google managed), Claude Opus 5.5 accetta messaggi `role: "system"` immediatamente dopo un turno utente nell’array `messages` (nel rispetto delle [regole di posizionamento](https://platform.claude.com/docs/it/build-with-claude/mid-conversation-system-messages#limitations)). Questa funzionalità non è disponibile su Claude Sonnet 5. Se mantieni percorsi di codice che ricostruiscono l’intera cronologia dei messaggi per aggiornare le istruzioni, puoi semplificarli e preservare gli hit della [cache dei prompt](https://platform.claude.com/docs/it/build-with-claude/prompt-caching) sui turni precedenti.
2. **Soglia minima della cache dei prompt ridotta:** La lunghezza minima del prompt memorizzabile nella cache su Claude Opus 5.5 è di 512 token, rispetto ai 1.024 token su Claude Sonnet 5. I prompt che erano troppo brevi per essere memorizzati nella cache su Claude Sonnet 5 possono creare voci nella cache, senza richiedere modifiche al codice. Consulta [Cache dei prompt](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#cache-limitations) per i valori minimi per modello.