---
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 di richiesta 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.
**Automatizza la tua migrazione con la skill Claude API.** In Claude Code, esegui `/claude-api migrate` per invocare la [skill Claude API](https://platform.claude.com/docs/it/agents-and-tools/agent-skills/claude-api-skill#migrating-to-a-newer-claude-model) inclusa. Funziona con qualsiasi modello Claude attuale come destinazione:
Lascia che Claude Code migri il tuo codice per te
```text
/claude-api migrate questo progetto a claude-opus-5-5
```
La skill applica la sostituzione dell'ID del modello e, se necessario, le modifiche incompatibili ai parametri, la sostituzione del prefill e la calibrazione dell'effort per il modello di destinazione in tutta la tua base di codice, quindi produce una checklist di elementi da verificare manualmente. Ti chiede di confermare l'ambito della migrazione (l'intera directory di lavoro, una sottodirectory o un elenco specifico di file) prima di modificare qualsiasi file. La skill rileva inoltre i client Amazon Bedrock e Claude Platform su AWS e adatta i formati degli ID dei modelli e le modifiche alle funzionalità per tali piattaforme.
Questa pagina elenca le modifiche al codice necessarie 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). Tutti i lettori devono consultare [Cosa deve soddisfare ogni richiesta a Claude Opus 5.5](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#request-requirements) e [Gestisci 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 ti riguardano. La [checklist di migrazione](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#migration-checklist) elenca ogni modifica per 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; 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 [Scrivere prompt per Claude Opus 5.5](https://platform.claude.com/docs/it/build-with-claude/prompt-engineering/prompting-claude-opus-5-5).
## Cosa deve soddisfare ogni richiesta a Claude Opus 5.5
Qualunque sia il modello di provenienza, una richiesta a `claude-opus-5-5` deve soddisfare i seguenti requisiti. 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, Google Cloud 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 [confronto prima/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 di 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) o `{"type": "none"}`. Le richieste che forzano una chiamata a uno strumento con `{"type": "any"}` o `{"type": "tool", "name": "..."}` vengono rifiutate. Consulta il [confronto prima/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`, oppure lasciali ai valori predefiniti: qualsiasi altro valore viene rifiutato. 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 [output strutturati](https://platform.claude.com/docs/it/build-with-claude/structured-outputs) o le istruzioni nel prompt di sistema. Su Amazon Bedrock, gli output strutturati non sono disponibili per Claude Opus 5.5, quindi lì usa le istruzioni nel prompt di sistema.
* **Computer use:** Sulla Claude API e su Google Cloud, dichiara il "computer use" (uso del computer) come toolset `computer_toolset_20260801`; lo strumento precedente `computer_20251124` lì viene rifiutato. 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 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 i modelli precedenti non ha alcun effetto.
La seguente richiesta soddisfa ogni elemento dell'elenco: l'effort è impostato e non c'è alcun campo `thinking`. Le schede degli SDK che stampano il testo lo selezionano in base al tipo di blocco, perché i blocchi `thinking` vengono per primi.
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-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 is Anthropic.TextBlock => block.type === "text"
);
console.log(textBlock?.text);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Messages = [
new() {
Role = Role.User,
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: "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
```
## Gestisci 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 viene già eseguito con il ragionamento attivo, i punti da 1 a 3 sono probabilmente già soddisfatti: verifica i punti 4 e 5. Se veniva eseguito senza ragionamento, su qualsiasi modello precedente, ogni punto è una modifica.
1. **`max_tokens` copre ragionamento più testo:** Su Claude Opus 4.8 e sui modelli Opus precedenti, le richieste senza 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 eseguiti 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 esegui con effort `xhigh` o `max`, imposta un `max_tokens` elevato in modo che il modello abbia spazio per pensare e agire; inizia da 64k token e regola da lì. Se i tuoi prompt erano ottimizzati per l'esecuzione 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 stream che tratta il primo evento `content_block_start` come testo, non funziona con queste risposte. Seleziona invece i blocchi di contenuto in base al loro campo `type`: leggi `text` dai blocchi il cui `type` è `"text"` e distingui i casi in base al tipo di blocco quando gestisci gli eventi di stream.
3. **Restituisci i blocchi di ragionamento senza modifiche nei loop di "tool use" (uso degli strumenti):** Se esegui un loop di uso degli strumenti, ripassa all'API i blocchi `thinking` di ogni risposta dell'assistente completi e non modificati 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, il valore predefinito appare come una lunga pausa prima dell'inizio dell'output; imposta `display: "summarized"` per ripristinare l'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 tornano 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
Procedi attraverso i gruppi dall'alto verso il basso e fermati dopo quello che nomina il tuo modello attuale: ogni elemento fino a quel punto ti riguarda. 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 o gli output strutturati, oppure con il solo `auto` su Amazon Bedrock.
* Se usi il computer use sulla Claude API o su Google Cloud, dichiara `computer_toolset_20260801` (senza header beta) invece di `computer_20251124` e aggiorna il tuo loop dell'agente per il toolset. Su Amazon Bedrock, mantieni `computer_20251124`; consulta la sezione [Compatibilità](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#compatibility) dello strumento computer use per le altre piattaforme.
* 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 mantengono). 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 Google Cloud, da Claude Sonnet 5.5 e Claude Haiku 5.5, ma non dai modelli Claude Fable o Claude Mythos.
* Leggi i blocchi di contenuto per `type` e ripassa i blocchi `thinking` senza modifiche nei loop di uso degli strumenti.
* Se la tua interfaccia visualizza il testo tra le chiamate agli strumenti, imposta `display: "updates"` (beta) o `"summarized"` e visualizza i blocchi `thinking` non vuoti.
* Se il tuo codice modifica 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 il 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 ragionamento più testo della risposta; con effort `xhigh` o `max`, inizia 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 eseguiti senza 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 vuoi 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 esegui con effort `xhigh` o `max`, aumenta `max_tokens` ad almeno 64k come punto di partenza.
* Per i carichi di lavoro agentici, considera i [task budget](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, valuta di passare a un messaggio di sistema a metà conversazione per preservare gli hit della cache dei prompt.
* Verifica che la tua gestione dei motivi di arresto legga `stop_details` in caso di rifiuto.
* Se vuoi la modalità veloce, che Claude Opus 4.7 rifiuta, imposta `speed: "fast"` nelle tue richieste alla Claude API. Claude Opus 5.5 non richiede 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 UI mostra 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 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 fornite dal modello, rimuovi qualsiasi conversione del 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 per il [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude-opus-and-sonnet) per ottenere accesso a restrizioni ridotte sui contenuti di sicurezza informatica.
### 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 usi 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 richiedono alcun 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 interlacciato).
* 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 legacy (`token-efficient-tools-2025-02-19`, `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, valuta di passare 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, completa [Cosa deve soddisfare ogni richiesta a Claude Opus 5.5](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#request-requirements) e [Gestisci 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 richiede le modifiche di questa sezione. Si tratta delle impostazioni di richiesta 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 di modello fisso senza suffisso di data, lo stesso schema di `claude-opus-5`. Su Amazon Bedrock, Claude Platform on AWS, Google Cloud 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 [Novità di Claude Opus 5.5](https://platform.claude.com/docs/it/models/opus-5-5/whats-new-opus-5-5#breaking-changes); 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.` oppure `"thinking.type.enabled" is not supported for this model.`). Rimuovi il campo `thinking` e scegli un livello di ["effort" (sforzo)](https://platform.claude.com/docs/it/build-with-claude/effort); dove disabilitavi il "thinking" (ragionamento) per risparmiare token, usa un livello più basso. Le risposte iniziano allora 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: 2023-06-01" \
-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() { Role = Role.User, 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; lo si regola con effort
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-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; lo si regola con 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() { Role = Role.User, 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 è 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 thinking è sempre attivo; il controllo è effort
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; lo si regola con 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). Su Amazon Bedrock, gli output strutturati, che includono l'uso rigoroso degli strumenti, non sono disponibili per Claude Opus 5.5. Lì, invia `auto` senza `strict`, indica nel prompt quando lo strumento si applica e convalida l'input dello strumento nel tuo codice. 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: 2023-06-01" \
-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() { Role = Role.User, 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 degli strumenti rigoroso: 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: 2023-06-01" \
-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,
// strict tool use (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()
{
Role = Role.User,
Content = "What's the weather in Paris? Use the get_weather tool.",
},
],
});
```
```go Go
// strict tool use (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 (strict tool use): 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,
// 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 da Claude Opus 5, dai modelli Opus, Sonnet e Haiku precedenti e, sulla Claude API e su Google Cloud, da Claude Sonnet 5.5 e Claude Haiku 5.5, ma non dai modelli Claude Fable o Claude Mythos. Mantieni la conversazione in sola aggiunta (nessuna modifica al prompt `system`, a `tools` o ai messaggi precedenti a metà conversazione) in modo che i blocchi rimangano validi; Claude Code, claude.ai, Claude Managed Agents e il Claude Agent SDK lo fanno già. L'applicazione delle regole corrisponde a quella di Claude Fable 5.1 su ogni piattaforma: per gli account creati a partire dal 31 agosto 2026, 00:00 UTC, riproporre un blocco di ragionamento dopo una tale modifica restituisce per impostazione predefinita un errore 400. Non è necessaria alcuna modifica al codice per le integrazioni in sola aggiunta. 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).
#### Lo strumento di computer use `computer_20251124` non è supportato sulla Claude API e su Google Cloud
Sulla Claude API e su Google Cloud, una voce di `tools` di tipo `computer_20251124` restituisce un errore 400 (`'claude-opus-5-5' does not support tool types: computer_20251124.`, seguito dai tipi di strumento accettati dal modello). Dichiara invece il toolset `computer_toolset_20260801`: rimuovi l'header beta e invia la voce senza `name` né dimensioni del display. Nel tuo ciclo dell'agente, gestisci i blocchi `tool_use` membri (l'azione è il `name` del blocco, non `input.action`), diversi per turno, e riporta `toolset_name` in ogni risultato. La modifica alla richiesta è mostrata di seguito; le modifiche al ciclo dell'agente sono elencate in [Migra da `computer_20251124`](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124). Su Amazon Bedrock, il precedente strumento `computer_20251124` continua a funzionare su Claude Opus 5.5 come su Claude Opus 5, quindi lì non è necessaria alcuna modifica; per le altre piattaforme, consulta la sezione [Compatibilità](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#compatibility) dello strumento di "computer use" (uso del computer). Consulta [Lo strumento di computer use `computer_20251124` non è supportato sulla Claude API e su Google Cloud](https://platform.claude.com/docs/it/models/opus-5-5/whats-new-opus-5-5#computer-20251124-is-not-supported).
Prima. Claude Opus 5 accetta questa richiesta e, sulla Claude API e su Google Cloud, 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: 2023-06-01" \
-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() { Role = Role.User, 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: 2023-06-01" \
-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 di visualizzazione
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 nome né dimensioni di visualizzazione
Tools = [new ComputerToolset20260801()],
Messages = [new() { Role = Role.User, 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 di 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 `"omitted"` di `thinking.display`, il loro campo `thinking` è vuoto. Nessuna richiesta fallisce, ma un'applicazione che trasmette in streaming quel testo ai propri utenti come aggiornamenti di avanzamento resta 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 di avanzamento mentre il ragionamento resta nascosto, e `"summarized"` restituisce entrambi, mescolati insieme. Quindi 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 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).
### Classificatori di sicurezza e fallback
Claude Opus 5.5 può restituire `stop_reason: "refusal"` con una categoria `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 ritenta 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 delle salvaguardie](https://platform.claude.com/docs/it/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#safeguard-refusals).
### Modifiche consigliate
1. **Ripeti la valutazione 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 di livello 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 calibrate sul comportamento di Claude Opus 5 potrebbero non essere più necessarie; consulta [Scrivere prompt per Claude Opus 5.5](https://platform.claude.com/docs/it/build-with-claude/prompt-engineering/prompting-claude-opus-5-5). Se eseguivi 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 i 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, completa [Cosa deve soddisfare ogni richiesta a Claude Opus 5.5](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#request-requirements), [Gestisci 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 così com'è al codice su Claude Opus 4.8, 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 di [Gestisci il ragionamento in ogni risposta](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#thinking-in-every-response) è una modifica per quel codice. Se il tuo codice non ha mai inviato un campo `thinking`, non c'è nulla da rimuovere secondo il [confronto prima/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 di un prompt memorizzabile nella cache su Claude Opus 5.5 è di 512 token, rispetto ai 1.024 token su Claude Opus 4.8. I prompt troppo brevi per essere memorizzati nella 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 per 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. **Considera i task budget (beta):** Per i carichi di lavoro agentici, i [task budget](https://platform.claude.com/docs/it/build-with-claude/task-budgets) indicano al modello quanti token ha a disposizione per un intero loop agentico. Richiedono l'header beta `task-budgets-2026-03-13`.
2. **Considera 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. Sulla Claude API, invia l'header beta `inline-tools-2026-09-15`. L'header precedente `mid-conversation-tool-changes-2026-07-01` funziona ancora per le modifiche che fanno riferimento a uno strumento per nome, sulla Claude API, su Amazon Bedrock e su Google Cloud.
## Migrazione a Claude Opus 5.5 da Claude Opus 4.7
Per prima cosa, completa [Cosa deve soddisfare ogni richiesta a Claude Opus 5.5](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#request-requirements), [Gestisci 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. Queste sezioni si applicano così come sono al codice su Claude Opus 4.7. 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 viene eseguito 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 punti aggiunge una modifica incompatibile a quelle delle sezioni precedenti; vale la pena verificarli dopo aver sostituito l'ID del modello.
1. **Livelli di effort ricalibrati:** L'allocazione dei token dietro ogni 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 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:** Sulla Claude API, su Amazon Bedrock e su Google Cloud, Claude Opus 5.5 accetta messaggi `role: "system"` immediatamente dopo un turno dell'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 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 arresto per i rifiuti:** 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 arresto `refusal`. Claude Opus 4.7 restituisce lo stesso oggetto, quindi questo conta solo se la tua gestione dei motivi di arresto non lo legge ancora. Non è richiesto alcun header beta e non è possibile disattivarlo. Se la tua gestione dei motivi di arresto non lo legge ancora, consulta [Gestione dei motivi di arresto](https://platform.claude.com/docs/it/build-with-claude/handling-stop-reasons). Claude Opus 5.5 rifiuta in più 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 [modalità veloce](https://platform.claude.com/docs/it/build-with-claude/fast-mode) sulla 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 computer use e strumento browser use:** Sulla Claude API e su Google Cloud, Claude Opus 5.5 supporta il [computer use](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool) come toolset `computer_toolset_20260801` e lo [strumento browser use](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool) per le attività all'interno delle pagine web. Claude Opus 4.7 non supporta nessuno dei due. Su quelle piattaforme Claude Opus 5.5 non accetta lo strumento precedente `computer_20251124`; consulta la [modifica incompatibile 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, completa tutte le sezioni precedenti, 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), [Gestisci il ragionamento in ogni risposta](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#thinking-in-every-response) e delle sezioni per [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). Queste sezioni si applicano così come sono 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` e viene 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 vengono eseguiti senza ragionamento a meno che tu non lo richieda, quindi queste 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 di allora, per chi usa [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 incompatibili
1. **"Extended thinking" (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: 2023-06-01" \
-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() { Role = Role.User, 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: 2023-06-01" \
-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() { Role = Role.User, 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: '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: "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 è orientabile 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 ragiona il modello. Esegui un'analisi dei livelli di effort sulle tue valutazioni anziché 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) tratta questo modello.
2. **Parametri di campionamento rimossi:** Impostare `temperature`, `top_p` o `top_k` su qualsiasi valore non predefinito su Claude Opus 4.7 e sui modelli successivi, incluso Claude Opus 5.5, restituisce un errore 400. L'SDK Python (v1.0 e successive) non li definisce, e passarli genera un `TypeError`. Il percorso di migrazione più sicuro è omettere completamente questi parametri dai payload delle richieste. Il prompting è il modo consigliato per guidare il comportamento del modello su Claude Opus 5.5. Se usavi `temperature = 0` per ottenere 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 della risposta su Claude Opus 4.7 e sui modelli successivi, ma il loro campo `thinking` è vuoto a meno che tu non scelga esplicitamente di riceverlo. Si tratta di una modifica silenziosa rispetto a Claude Opus 4.6, dove l'impostazione predefinita era restituire il testo del ragionamento riassunto. Per ripristinarlo, consulta il punto 4 di [Gestisci 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, usato anche dai modelli Opus successivi, incluso Claude Opus 5.5. Contribuisce a migliorare le prestazioni su un'ampia gamma di attività e può usare da circa 1x a 1,35x token nell'elaborazione del testo rispetto ai modelli precedenti a Claude Opus 4.7 (fino a \~35% in più, a seconda del contenuto).
[`/v1/messages/count_tokens`](https://platform.claude.com/docs/it/build-with-claude/token-counting) restituisce per Claude Opus 5.5 un numero di token diverso rispetto a Claude Opus 4.6. L'efficienza dei token può variare in base alla forma del carico di lavoro.
Aggiorna i parametri `max_tokens` per lasciare 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 tra token e caratteri. Usa l'[endpoint di conteggio dei token](https://platform.claude.com/docs/it/build-with-claude/token-counting) per verificare. Gli interventi sul prompt, [`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 possono andare a scapito dell'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 istruzioni nel prompt di sistema. Su Amazon Bedrock, gli output strutturati non sono disponibili per Claude Opus 5.5, quindi lì usa 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 incompatibili dell'API. 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 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 nei 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 lunghezza e 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. **Protezioni di cybersicurezza in tempo reale:** Novità introdotta in Claude Opus 4.7: le richieste che coinvolgono argomenti vietati o ad alto rischio possono 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 una forte componente visiva ed è particolarmente utile per il computer use, la comprensione degli screenshot e l'analisi dei documenti.
Il supporto per l'alta risoluzione è automatico e non richiede alcun header beta o attivazione lato client. Due cose 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 immagine, rispetto al limite precedente di circa 1.600 token per immagine). Ripianifica `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 bounding box restituite dal modello sono 1:1 con i pixel effettivi dell'immagine su Claude Opus 4.7, quindi non è richiesta alcuna conversione del fattore di scala.
Vedi [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 [Scrivere prompt per 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 da Claude Opus 4.5, Claude Opus 4.1 o un modello precedente direttamente a Claude Opus 5.5, leggi questa pagina dall'inizio: prima completa tutte le sezioni precedenti, nell'ordine della pagina. Poi completa le [modifiche incompatibili per la migrazione da Claude Opus 4.6](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#opus-46-breaking-changes) riportate in precedenza in questa sezione. Quindi applica le seguenti modifiche cumulative, entrate in vigore tra Claude Opus 4.5 e Claude Opus 4.7. Se usi 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 incompatibili
1. **La rimozione del prefill** è trattata nelle [modifiche incompatibili 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 modelli successivi possono 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 anziché usare un parser JSON, verifica la tua logica di parsing. I parser JSON standard (come `json.loads()` o `JSON.parse()`) gestiscono queste differenze automaticamente.
#### 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 confronto prima/dopo è il punto 1 delle [modifiche incompatibili 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 comporta anche il passaggio 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 dell'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 interlacciato:** Con il ragionamento adattivo, il ragionamento interlacciato è 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, sostituisci `output_format={...}` con `output_config={"format": {...}}`. Il parametro `output_format` è deprecato e verrà rimosso in futuro. Se vuoi continuare a usarlo, aggiungi l'header beta `structured-outputs-2025-11-13`, altrimenti l'API restituisce un errore 400. L'SDK Python (v1.0 e successive) non accetta `output_format={...}` in `client.beta.messages.create()` né in `count_tokens()`. L'argomento `output_format=Model` degli helper `parse()` e `stream()` non cambia.
### Migrazione da Claude 4.1 o precedenti
Se stai migrando da Claude Opus 4.1 o da modelli precedenti direttamente a Claude Opus 5.5, 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 tutte le sezioni precedenti, quindi in pratica leggi questa pagina dall'inizio. Poi applica le modifiche aggiuntive di questa sottosezione.
#### Modifiche aggiuntive incompatibili
1. **Rimuovi i parametri di campionamento:** Consulta [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 quando si migra 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:** Esegui l'upgrade 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:** Sulla Claude API e su Google Cloud, Claude Opus 5.5 accetta il computer use solo come toolset `computer_toolset_20260801`: gli strumenti precedenti `computer_20250124` e `computer_20251124` vengono rifiutati su queste piattaforme. 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 arresto `refusal`**
Aggiorna la tua applicazione per [gestire i motivi di arresto `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 arresto `model_context_window_exceeded`**
Claude 4.5 e i modelli successivi restituiscono un motivo di arresto `model_context_window_exceeded` quando la generazione si interrompe per il raggiungimento del limite della finestra di contesto, anziché del limite `max_tokens` richiesto. Aggiorna la tua applicazione per gestire questo nuovo motivo di arresto:
```python Python
response = client.messages.create(...)
if response.stop_reason == "model_context_window_exceeded":
# Gestisci adeguatamente il limite della finestra di contesto
pass
```
```typescript TypeScript
const response = await client.messages.create(/* ... */);
if (response.stop_reason === "model_context_window_exceeded") {
// Gestisci adeguatamente il limite della finestra di contesto
}
```
```csharp C#
var response = await client.Messages.Create(...);
if (response.StopReason?.Raw() == "model_context_window_exceeded")
{
// Gestisci il limite della finestra di contesto in modo appropriato
}
```
```go Go
response, _ := client.Messages.New(ctx, params) // your existing request
if response.StopReason == "model_context_window_exceeded" {
// Gestisci adeguatamente 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 il limite della finestra di contesto in modo appropriato
}
```
```php PHP
$response = $client->messages->create(...);
if ($response->stopReason === 'model_context_window_exceeded') {
// Gestisci il limite della finestra di contesto in modo appropriato
}
```
```ruby Ruby
response = client.messages.create(...)
if response.stop_reason == :model_context_window_exceeded
# Gestisci adeguatamente il limite della finestra di contesto
end
```
5. **Verifica la gestione dei parametri degli strumenti (newline finali)**
Claude 4.5 e i modelli 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 le modifiche comportamentali**
Claude 4 e i modelli 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.
#### Modifiche aggiuntive consigliate
* **Rimuovi gli header beta legacy:** 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
Completa [Cosa deve soddisfare ogni richiesta a Claude Opus 5.5](https://platform.claude.com/docs/it/models/opus-5-5/migration-guide#request-requirements), [Gestisci 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 al codice su Claude Sonnet 5 così com'è scritto, perché Claude Sonnet 5, come Claude Opus 5:
* Funziona 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 non predefiniti e il prefill dell'assistente restituiscono un errore 400 su entrambi i modelli, quindi su questi aspetti 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 al tuo caso.
### Cosa è cambiato
1. **Messaggi di sistema a metà conversazione:** Sulla Claude API, su Amazon Bedrock e su Google Cloud, 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. **Minimo più basso per la cache dei prompt:** La lunghezza minima di un prompt memorizzabile nella cache su Claude Opus 5.5 è di 512 token, rispetto ai 1.024 token di Claude Sonnet 5. I prompt che erano troppo brevi per essere memorizzati nella cache su Claude Sonnet 5 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 per modello.