Claude Platform Docs
Modelli e prezziClaude Opus 5.5

Guida alla migrazione a Claude Opus 5.5

Passa a Claude Opus 5.5 dai modelli Opus precedenti o da Claude Sonnet 5 con questa guida alla migrazione. Le indicazioni per abilitare Claude Opus 5.5 includono le impostazioni delle richieste che restituiscono errori, i blocchi di ragionamento in ogni risposta e una checklist per ciascun modello di partenza.

Claude Code

Lascia che Claude Code migri il tuo codice per te

/claude-api migrate questo progetto a claude-opus-5-5

Questa pagina elenca le modifiche al codice per passare a Claude Opus 5.5 da Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 e modelli Opus precedenti o Claude Sonnet 5. Ogni lettore ha bisogno di Requisiti che ogni richiesta a Claude Opus 5.5 deve soddisfare e Gestire il ragionamento in ogni risposta. Poi vai alla sezione relativa al tuo modello attuale: la sua prima frase indica le altre sezioni che si applicano al tuo caso. La checklist di migrazione elenca ogni modifica in base al modello di partenza.

Claude Opus 5.5 costa meno di Claude Opus 5 ($4 / $20 USD per milione di token di input / output, rispetto a $5 / $25 USD; consulta Prezzi di Claude). Per il supporto delle funzionalità, consulta Novità di Claude Opus 5.5. Per le differenze di comportamento e i pattern di prompting specifici del modello, consulta Prompting per Claude Opus 5.5.

Requisiti che ogni richiesta a Claude Opus 5.5 deve soddisfare

Qualunque sia il modello da cui provieni, una richiesta a claude-opus-5-5 deve soddisfare quanto segue. Quando un elemento indica che un’impostazione viene rifiutata, l’API restituisce un errore 400.

  • ID del modello: Usa claude-opus-5-5, un ID del modello fisso senza suffisso di data. Su Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), Claude Models on Google Cloud (Google managed) e Microsoft Foundry, usa l’ID del modello di quella piattaforma; consulta Disponibilità.
  • Ragionamento: Non inviare alcun campo thinking, oppure invia thinking: {"type": "adaptive"}, che è equivalente: l’“adaptive thinking” (ragionamento adattivo) è sempre attivo. thinking: {"type": "disabled"} e i budget di ragionamento manuali (thinking: {"type": "enabled", "budget_tokens": N}) vengono rifiutati. Consulta il prima e dopo per il ragionamento.
  • Effort: Controlla la profondità del ragionamento con il parametro effort, l’unico parametro della richiesta che la controlla. Tutti e cinque i livelli (low, medium, high, xhigh, max) sono supportati e il valore predefinito è medium. Consulta Livelli di effort consigliati per Claude Opus 5.5.
  • Scelta dello strumento: Usa tool_choice {"type": "auto"} (il valore predefinito) oppure {"type": "none"}. Forzare una chiamata a uno strumento con {"type": "any"} o {"type": "tool", "name": "..."} viene rifiutato. Consulta il prima e dopo per la scelta dello strumento.
  • Parametri di campionamento: Ometti temperature, top_p e top_k. Usa il prompting per guidare il comportamento del modello.
  • Prefill: Non terminare messages con un turno dell’assistente precompilato (“prefill”): viene rifiutato. Usa invece gli “structured outputs” (output strutturati) o istruzioni nel prompt di sistema.
  • Computer use: Dichiara il “computer use” (uso del computer) come toolset computer_toolset_20260801. Su Amazon Bedrock funziona anche computer_20251124. Consulta la modifica incompatibile del computer use.
  • Finestra di contesto: Non è necessario alcun header beta per la “context window” (finestra di contesto). La finestra di contesto da 1M token è quella predefinita, e un header inviato per modelli precedenti non ha alcun effetto.

La seguente richiesta soddisfa ogni elemento dell’elenco: l’effort è impostato e non c’è alcun campo thinking. Dove l’esempio stampa del testo, individua il blocco di testo in base al suo tipo, perché i blocchi thinking vengono prima.

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)

Gestire il ragionamento in ogni risposta

Il ragionamento viene eseguito su ogni richiesta a Claude Opus 5.5, quindi ogni risposta può iniziare con blocchi thinking, e max_tokens copre ragionamento più testo. Se il tuo codice funziona già con il ragionamento attivo, i punti da 1 a 3 sono probabilmente già soddisfatti: controlla i punti 4 e 5. Se funzionava senza ragionamento, su qualsiasi modello precedente, ogni punto rappresenta una modifica.

  1. max_tokens copre ragionamento più testo: Su Claude Opus 4.8 e sui modelli Opus precedenti, le richieste senza un campo thinking vengono eseguite senza ragionamento. Claude Opus 5 e Claude Sonnet 5 accettano thinking: {"type": "disabled"}. Su Claude Opus 5.5, ogni richiesta viene eseguita con il ragionamento adattivo. max_tokens rimane un limite rigido sull’output totale, ragionamento più testo della risposta, quindi rivedilo per i carichi di lavoro che funzionavano senza ragionamento. I token di ragionamento vengono fatturati come token di output anche quando il testo del ragionamento non ti viene restituito, quindi un carico di lavoro di questo tipo può produrre più token di output per richiesta. Consulta Controllo dei costi. Per spendere meno token nel ragionamento, abbassa il livello di effort. Se lavori con effort xhigh o max, imposta un max_tokens elevato in modo che il modello abbia spazio per ragionare e agire; parti da 64k token e regola da lì. Se i tuoi prompt erano ottimizzati per funzionare senza ragionamento, consulta Prompt scritti per il ragionamento disabilitato.

  2. Le risposte iniziano con blocchi di ragionamento: Una risposta può iniziare con uno o più blocchi thinking prima del primo blocco text. Il codice che legge la risposta per posizione, come content[0].text o un gestore di streaming che tratta il primo evento content_block_start come testo, si interrompe con queste risposte. Seleziona invece i blocchi di contenuto in base al loro campo type: leggi text dai blocchi il cui type è "text" e ramifica in base al tipo di blocco quando gestisci gli eventi di streaming.

  3. Restituisci i blocchi di ragionamento senza modifiche nei cicli di uso degli strumenti: Se esegui un ciclo di “tool use” (uso degli strumenti), passa i blocchi thinking di ogni risposta dell’assistente all’API completi e senza modifiche quando restituisci i risultati degli strumenti, inclusi i blocchi il cui campo thinking è vuoto. Rimanda il messaggio dell’assistente così come ricevuto, invece di filtrarne i blocchi di contenuto per tipo o ricostruirlo: l’API rifiuta i blocchi di ragionamento modificati, riordinati o parzialmente rimossi con un errore 400. Consulta Preservare i blocchi di ragionamento.

  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":

    thinking = {
    "type": "adaptive",
    "display": "summarized",
}

    Se il tuo prodotto trasmette in streaming il ragionamento agli utenti, l’impostazione predefinita appare come una lunga pausa prima dell’inizio dell’output; imposta display: "summarized" per ripristinare un avanzamento visibile durante il ragionamento. Consulta Controllare la visualizzazione del ragionamento.

  5. Il testo tra le chiamate agli strumenti arriva nei blocchi di ragionamento: Le brevi note che il modello scrive tra le chiamate agli strumenti vengono restituite come blocchi thinking, che sono vuoti con la visualizzazione predefinita. Consulta Il testo tra le chiamate agli strumenti viene restituito nei blocchi di ragionamento.

Checklist di migrazione per modello di partenza

Scorri i gruppi e fermati dopo quello che indica il tuo modello attuale: ogni elemento fino a quel punto si applica al tuo caso. Se usi Claude Opus 5, il primo gruppo è l’intero elenco. Se usi Claude Sonnet 5, applica il primo gruppo e l’ultimo.

Ogni modello di partenza

  • Aggiorna l’ID del modello a claude-opus-5-5.
  • Rimuovi thinking: {"type": "disabled"} e thinking: {"type": "enabled", ...}; scegli invece un livello di effort.
  • Imposta effort esplicitamente: il valore predefinito è medium, mentre quello di Claude Opus 5 è high.
  • Sostituisci i tipi di tool_choice any e tool con auto più l’uso rigoroso degli strumenti (“strict tool use”) o gli output strutturati.
  • Se usi una versione precedente dello strumento di computer use, dichiara invece computer_toolset_20260801 (senza header beta) e aggiorna il tuo ciclo dell’agente per il toolset. Su Amazon Bedrock funziona anche computer_20251124.
  • Se un router o un fallback può spostare una conversazione da Claude Opus 5.5 a un altro modello, aspettati che quel modello venga eseguito senza i blocchi di ragionamento di Claude Opus 5.5 (Claude Fable 5.1 e Claude Mythos 5.1 sulla Claude API sono l’eccezione e li conservano). Claude Opus 5.5 stesso legge il ragionamento da Claude Opus 5, dai modelli Opus, Sonnet e Haiku precedenti e, sulla Claude API e su Claude Models on Google Cloud (Google managed), da Claude Sonnet 5.5 e Claude Haiku 5.5, ma non dai modelli Claude Fable o Claude Mythos.
  • Leggi i blocchi di contenuto in base al type e restituisci i blocchi thinking senza modifiche nei cicli di uso degli strumenti.
  • Se la tua interfaccia mostra il testo tra le chiamate agli strumenti, imposta display: "updates" (beta) o "summarized" e mostra i blocchi thinking non vuoti.
  • Se il tuo codice modifica i turni precedenti, il prompt system o tools a metà conversazione, segui Ragionamento preservato.
  • Gestisci stop_reason: "refusal" e configura un fallback.
  • Ristabilisci la baseline di costi e latenza al livello di effort scelto.
  • Se il tuo codice disabilitava il ragionamento, rivedi max_tokens, che copre il ragionamento più il testo della risposta; con effort xhigh o max, parti da 64k. Consulta Gestisci il ragionamento in ogni risposta.

Claude Opus 4.8 o precedenti

  • Rivedi i carichi di lavoro che funzionavano senza un campo thinking: su Claude Opus 5.5 vengono eseguiti con il ragionamento, e il ragionamento non può essere disabilitato. Rivedi max_tokens, che rimane un limite rigido sull’output totale (ragionamento più testo della risposta), e abbassa effort dove desideri meno ragionamento. I token di ragionamento vengono fatturati come token di output, quindi questi carichi di lavoro possono produrre più token di output per richiesta.
  • Verifica che qualsiasi codice che analizza il campo thinking lo tratti solo come testo da visualizzare. Imposta display: "summarized" per ricevere riepiloghi leggibili.
  • Rivedi i prompt vicini al minimo per la cache: i prompt di 512 token o più possono creare voci di cache.
  • Se la tua organizzazione ha un impegno Priority Tier, pianifica la capacità separatamente: Priority Tier non è supportato su Claude Opus 5.5.
  • Se lavori con effort xhigh o max, aumenta max_tokens ad almeno 64k come punto di partenza.
  • Per i carichi di lavoro agentici, considera i budget delle attività (beta) e le modifiche agli strumenti a metà conversazione (beta).

Claude Opus 4.7 o precedenti

  • Esegui una nuova analisi dei livelli di effort sulle tue valutazioni invece di riportare un’impostazione ottimizzata per un modello precedente.
  • Rimuovi qualsiasi header beta per la finestra di contesto.
  • Se ricostruisci la cronologia della conversazione per aggiornare le istruzioni, considera il passaggio a un messaggio di sistema a metà conversazione per preservare gli hit della cache dei prompt.
  • Verifica che la gestione dei motivi di arresto legga stop_details in caso di rifiuto.
  • Se desideri la modalità veloce, che Claude Opus 4.7 rifiuta, imposta speed: "fast" nelle tue richieste alla Claude API. Claude Opus 5.5 non necessita di un header beta.

Claude Opus 4.6 o precedenti

  • Rimuovi temperature, top_p e top_k dai payload delle richieste.
  • Sostituisci thinking: {"type": "enabled", "budget_tokens": N} con thinking: {"type": "adaptive"} più il parametro effort, oppure rimuovi completamente il campo thinking; il ragionamento adattivo è sempre attivo.
  • Se la tua interfaccia utente visualizza il contenuto del ragionamento, attiva esplicitamente il riepilogo del ragionamento.
  • Esegui nuovamente il benchmark di costi e latenza end-to-end con la tokenizzazione aggiornata.
  • Regola nuovamente max_tokens per tenere conto della tokenizzazione aggiornata, inclusi i trigger di compattazione.
  • Testa nuovamente qualsiasi stima del conteggio dei token lato client.
  • Se la tua applicazione invia immagini, ricalcola il budget per il supporto delle immagini ad alta risoluzione (fino a circa 3 volte più token immagine per ogni immagine a piena risoluzione). Riduci la risoluzione prima dell’invio se non ti serve la fedeltà aggiuntiva.
  • Se utilizzi coordinate di puntamento o di bounding box dal modello, rimuovi qualsiasi conversione con fattore di scala; le coordinate sono 1:1 con i pixel effettivi dell’immagine su Claude Opus 4.7 e sui modelli successivi.
  • Rivedi le modifiche di comportamento iniziate con Claude Opus 4.7.
  • Se il tuo prodotto svolge attività di sicurezza legittime, fai domanda al Cyber Verification Program per ottenere restrizioni ridotte sui contenuti informatici.

Claude Opus 4.5 o precedenti

  • Rimuovi qualsiasi prefill dei messaggi dell’assistente; Claude Opus 4.6 li rifiuta già.
  • Verifica che l’analisi del JSON delle chiamate agli strumenti utilizzi un parser JSON standard.
  • Passa da client.beta.messages.create() a client.messages.create(): il ragionamento adattivo e l’effort non necessitano di un namespace beta.
  • Rimuovi l’header beta effort-2025-11-24 (il parametro effort non lo richiede).
  • Rimuovi l’header beta fine-grained-tool-streaming-2025-05-14.
  • Rimuovi l’header beta interleaved-thinking-2025-05-14 (il ragionamento adattivo abilita automaticamente il ragionamento interleaved).
  • Migra output_format a output_config.format (se applicabile).

Claude 4.1 o precedenti

  • Aggiorna le versioni degli strumenti (text_editor_20250728, code_execution_20260521).
  • Gestisci il motivo di arresto refusal.
  • Gestisci il motivo di arresto model_context_window_exceeded.
  • Verifica la gestione dei parametri stringa degli strumenti per i caratteri di nuova riga finali.
  • Rimuovi gli header beta token-efficient-tools-2025-02-19 e output-128k-2025-02-19.
  • Rivedi e aggiorna i prompt seguendo le best practice di prompting.

Solo Claude Sonnet 5

  • Se ricostruisci la cronologia della conversazione per aggiornare le istruzioni, considera il passaggio a un messaggio di sistema a metà conversazione per preservare gli hit della cache dei prompt.
  • Rivedi i prompt vicini al minimo per la cache: i prompt di 512 token o più possono creare voci di cache.

Migrazione a Claude Opus 5.5 da Claude Opus 5

Per prima cosa, segui Requisiti che ogni richiesta a Claude Opus 5.5 deve soddisfare e Gestire il ragionamento in ogni risposta. Ogni modello di partenza necessita delle modifiche in questa sezione. Si tratta delle impostazioni delle richieste che Claude Opus 5.5 rifiuta e delle modifiche alle risposte che lo accompagnano. La checklist per questa sezione è il primo gruppo della checklist di migrazione.

Aggiorna il nome del modello

model = "claude-opus-5"  # Before
model = "claude-opus-5-5"  # After

claude-opus-5-5 è un ID del modello fisso senza suffisso di data, lo stesso schema di claude-opus-5. Su Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), Claude Models on Google Cloud (Google managed) e Microsoft Foundry, usa l’ID del modello di quella piattaforma; consulta Disponibilità.

Modifiche incompatibili

Ogni modifica è spiegata in Modifiche incompatibili in Novità di Claude Opus 5.5; questa sezione fornisce la modifica al codice per ciascuna.

Il ragionamento non può essere disabilitato

thinking: {"type": "disabled"} e thinking: {"type": "enabled", "budget_tokens": N} restituiscono entrambi un errore 400 ("thinking.type.disabled" is not supported for this model. o "thinking.type.enabled" is not supported for this model.). Rimuovi il campo thinking e scegli un livello di effort; dove disabilitavi il ragionamento per risparmiare token, usane uno più basso. Le risposte iniziano quindi con blocchi thinking, perciò seleziona i blocchi di contenuto in base a type e restituisci i blocchi thinking senza modifiche insieme ai risultati degli strumenti. Consulta Il ragionamento non può essere disabilitato.

Prima. Claude Opus 5 accetta questa richiesta, mentre Claude Opus 5.5 la rifiuta con un errore 400:

client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "disabled"},
    messages=[{"role": "user", "content": "..."}],
)

Dopo:

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": "..."}],
)

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 o gli output strutturati, 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. Consulta L’uso forzato degli strumenti non è supportato.

Prima. Claude Opus 5 accetta questa richiesta, mentre Claude Opus 5.5 la rifiuta con un errore 400:

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?"}],
)

Dopo:

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.",
        }
    ],
)

I blocchi di ragionamento sono legati al modello e alla conversazione

Sulla Claude API, Claude Fable 5.1 e Claude Mythos 5.1 leggono i blocchi di ragionamento di Claude Opus 5.5; nessun altro modello lo fa. Un router o un fallback che sposta una conversazione da Claude Opus 5.5 a qualsiasi altro modello esegue quei turni senza di essi. Nella direzione opposta, Claude Opus 5.5 legge i blocchi di ragionamento di Claude Opus 5, dei modelli Opus, Sonnet e Haiku precedenti e, sulla Claude API e su Claude Models on Google Cloud (Google managed), di Claude Sonnet 5.5 e Claude Haiku 5.5, ma non dei modelli Claude Fable o Claude Mythos. Mantieni la conversazione in modalità append-only (nessuna modifica al prompt system, ai tools o ai messaggi precedenti a metà conversazione) affinché i blocchi rimangano validi; Claude Code, claude.ai, Claude Managed Agents e il Claude Agent SDK lo fanno già. Sugli account creati a partire dal 31 agosto 2026, 00:00 UTC, sulla Claude API e sulle piattaforme cloud, una richiesta che riproduce un blocco di ragionamento dopo una tale modifica e lascia thinking.block_binding.prefix_mismatch_behavior non impostato riceve un errore 400. Non è necessaria alcuna modifica al codice per le integrazioni append-only. Consulta I blocchi di ragionamento sono legati al modello e alla conversazione e Ragionamento preservato.

Alcune versioni dello strumento di computer use non sono supportate

Claude Opus 5.5 supporta il computer use tramite il toolset computer_toolset_20260801. Su Amazon Bedrock, Claude Opus 5.5 accetta anche lo strumento computer_20251124 con l’header beta computer-use-2025-11-24. Claude Opus 5.5 restituisce un errore 400 per qualsiasi versione dello strumento di computer use che non accetta, come computer_20251124 sulla Claude API. Non accetta computer_20250124 su nessuna piattaforma. Sulla Claude API, il messaggio di errore inizia con 'claude-opus-5-5' does not support tool types: computer_20251124. e poi elenca i tipi di strumento che il modello accetta.

Le integrazioni che usano il toolset non richiedono modifiche. Per spostare un’integrazione computer_20251124 al toolset, rimuovi l’header beta e invia la voce computer_toolset_20260801 senza name né dimensioni del display. Nel tuo ciclo dell’agente, gestisci ogni blocco tool_use membro in un turno e riporta toolset_name in ogni risultato. Leggi l’azione dal name di ciascun blocco, non da input.action. Migrare da computer_20251124 elenca le modifiche al ciclo dell’agente.

Prima. Claude Opus 5 accetta questa richiesta, mentre Claude Opus 5.5 la rifiuta con un errore 400 sulla Claude API:

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."}],
)

Dopo:

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."}],
)

Il testo tra le chiamate agli strumenti viene restituito nei blocchi di ragionamento

Su Claude Opus 5, il testo che il modello scrive tra le chiamate agli strumenti viene restituito come blocchi text. Su Claude Opus 5.5, come su Claude Fable 5.1, quella narrazione viene restituita come blocchi thinking di aggiornamento sull’avanzamento, al massimo uno prima di ogni chiamata a uno strumento. Con il valore predefinito di thinking.display, ovvero "omitted", il loro campo thinking è vuoto. Nessuna richiesta fallisce, ma un’applicazione che trasmette in streaming quel testo ai propri utenti come aggiornamenti sull’avanzamento diventa silenziosa tra le chiamate agli strumenti. Per ripristinare gli aggiornamenti, leggili dai blocchi thinking e imposta un valore di display che restituisca il loro testo: "updates" (beta, header thinking-display-updates-2026-08-18) restituisce gli aggiornamenti sull’avanzamento mantenendo nascosto il ragionamento, mentre "summarized" restituisce entrambi, mescolati insieme. Poi visualizza ogni blocco thinking non vuoto prima del blocco tool_use che lo segue, e restituisci i blocchi senza modifiche insieme al resto del turno dell’assistente. Consulta Aggiornamenti sull’avanzamento rivolti agli utenti.

Classificatori di sicurezza e fallback

Claude Opus 5.5 può restituire stop_reason: "refusal" con una categoria in stop_details. I suoi classificatori coprono un insieme di categorie più ampio rispetto a quelli di Claude Opus 5, quindi aspettati valori di stop_details.category come "bio" oltre a "cyber" e "reasoning_extraction"; consulta la tabella delle categorie di rifiuto. Gestisci i rifiuti e configura il fallback lato server o un tuo meccanismo di nuovo tentativo (il fallback lato server non ripete le richieste rifiutate con "reasoning_extraction"; quel rifiuto ti viene restituito); consulta Rifiuti e fallback e Rifiuti di salvaguardia.

  1. Esegui di nuovo l’analisi dei livelli di effort. L’effort è l’unico controllo del ragionamento su Claude Opus 5.5, e il suo valore predefinito è medium, mentre quello di Claude Opus 5 è high, quindi una richiesta che omette effort ora viene eseguita a medium. Scendi di livello dove la qualità regge e sali per il lavoro più impegnativo. Consulta Effort.
  2. Rivaluta le istruzioni del prompt specifiche del modello. Le istruzioni ottimizzate per il comportamento di Claude Opus 5 potrebbero non essere più necessarie; consulta Prompting per Claude Opus 5.5. Se lavoravi con il ragionamento disabilitato, consulta anche Prompt scritti per il ragionamento disabilitato.
  3. Esegui test in un ambiente di sviluppo prima di spostare il traffico di produzione.

Migrazione a Claude Opus 5.5 da Claude Opus 4.8

Per prima cosa, segui Requisiti che ogni richiesta a Claude Opus 5.5 deve soddisfare, Gestire il ragionamento in ogni risposta e Migrazione a Claude Opus 5.5 da Claude Opus 5. Usa claude-opus-4-8 come ID del modello da sostituire. Quest’ultima sezione si applica al codice su Claude Opus 4.8 così com’è scritta, perché Claude Opus 4.8, come Claude Opus 5:

  • Accetta thinking: {"type": "disabled"}, la scelta forzata dello strumento e lo strumento computer_20251124.
  • Restituisce il testo tra le chiamate agli strumenti come blocchi text.
  • Usa per impostazione predefinita l’effort high.

Questa sezione aggiunge ciò che è cambiato tra Claude Opus 4.8 e Claude Opus 5. Per una checklist, consulta i primi due gruppi della checklist di migrazione.

Cosa è cambiato

  1. Il ragionamento viene eseguito sulle richieste che lo omettevano: Su Claude Opus 4.8, il ragionamento è disattivato a meno che tu non lo richieda. Su Claude Opus 5.5, una richiesta senza campo thinking viene eseguita con il ragionamento, quindi ogni punto in Gestire il ragionamento in ogni risposta rappresenta una modifica per quel codice. Se il tuo codice non ha mai inviato un campo thinking, non c’è nulla da rimuovere secondo il prima e dopo per il ragionamento.

  2. Minimo più basso per la cache dei prompt: La lunghezza minima del prompt memorizzabile nella cache su Claude Opus 5.5 è di 512 token, rispetto ai 1.024 token di Claude Opus 4.8. I prompt che erano troppo brevi per la cache su Claude Opus 4.8 possono creare voci di cache, senza alcuna modifica al codice. Consulta Cache dei prompt per i minimi di ciascun modello.

  3. Priority Tier non è supportato: Priority Tier 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.

Queste modifiche non sono obbligatorie, ma miglioreranno la tua esperienza:

  1. Valuta i budget delle attività (beta): Per i carichi di lavoro agentici, i “task budget” (budget delle attività) indicano al modello quanti token ha a disposizione per un intero ciclo agentico. Richiedono l’header beta task-budgets-2026-03-13.

  2. Valuta le modifiche agli strumenti a metà conversazione (beta): Le modifiche agli strumenti a metà conversazione ti consentono di aggiungere o rimuovere strumenti tra i turni di una conversazione senza invalidare gli hit della cache dei prompt sui turni precedenti. Modificare l’array tools stesso invalida il prefisso memorizzato nella cache. Su Claude API, Claude Platform on AWS e Claude Models on Google Cloud (Anthropic managed), invia l’header beta inline-tools-2026-09-15. L’header mid-conversation-tool-changes-2026-07-01 funziona per le modifiche che indicano uno strumento per riferimento, su Claude API, Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) e Claude Models on Google Cloud (Google managed).

Migrazione a Claude Opus 5.5 da Claude Opus 4.7

Per prima cosa, segui Requisiti che ogni richiesta a Claude Opus 5.5 deve soddisfare, Gestire il ragionamento in ogni risposta, Migrazione a Claude Opus 5.5 da Claude Opus 5 e Migrazione a Claude Opus 5.5 da Claude Opus 4.8. Usa claude-opus-4-7 come ID del modello da sostituire. Quelle sezioni si applicano al codice su Claude Opus 4.7 così come sono scritte. Come Claude Opus 4.8, accetta thinking: {"type": "disabled"}, la scelta forzata dello strumento e lo strumento computer_20251124. Usa per impostazione predefinita l’effort high e funziona senza ragionamento a meno che tu non lo richieda.

Questa sezione aggiunge ciò che è cambiato dopo Claude Opus 4.7. Se il tuo codice è su Claude Opus 4.6 o precedenti, prosegui con Migrazione a Claude Opus 5.5 da Claude Opus 4.6 e modelli Opus precedenti 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.

Cosa è cambiato

Nessuno di questi elementi aggiunge una modifica incompatibile a quelle delle sezioni precedenti; vale la pena verificarli dopo aver cambiato l’ID del modello.

  1. Livelli di effort ricalibrati: L’allocazione di token alla base di ciascun livello di effort cambia su Claude Opus 5.5 rispetto a Claude Opus 4.7. Il valore predefinito è medium, mentre quello di Claude Opus 4.7 è high. Esegui una nuova analisi dei livelli di effort sulle tue valutazioni invece di riportare un’impostazione ottimizzata per Claude Opus 4.7. Consulta Effort.

  2. La finestra di contesto da 1M è quella predefinita: Claude Opus 5.5 offre per impostazione predefinita l’intera finestra di contesto da 1M token senza alcun header beta. Se il tuo client passa un header beta per la finestra di contesto per compatibilità con modelli precedenti, rimuovilo.

  3. Messaggi di sistema a metà conversazione: Su Claude API, Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) e Claude Models on Google Cloud (Google managed), Claude Opus 5.5 accetta messaggi role: "system" immediatamente dopo un turno utente nell’array messages (nel rispetto delle regole di posizionamento). Usa il campo system di primo livello per le istruzioni che si applicano fin dall’inizio. Claude Opus 4.7 rifiuta role: "system" in messages con un errore 400. Se mantieni percorsi di codice che ricostruiscono l’intera cronologia dei messaggi per aggiornare le istruzioni, puoi semplificarli e preservare gli hit della cache dei prompt sui turni precedenti.

  4. Dettagli di interruzione per rifiuto: Quando il modello rifiuta una richiesta, Claude Opus 5.5 restituisce un oggetto stop_details che indica la categoria del rifiuto, insieme al motivo di interruzione refusal. Claude Opus 4.7 restituisce lo stesso oggetto, quindi questo è rilevante solo se la tua gestione dei motivi di interruzione non lo legge ancora. Non è richiesto alcun header beta e non è possibile disattivarlo. Se la tua gestione dei motivi di interruzione non lo legge ancora, consulta Gestione dei motivi di interruzione. Claude Opus 5.5 rifiuta in un numero maggiore di categorie; consulta Classificatori di sicurezza e fallback.

  5. Modalità veloce: Claude Opus 5.5 supporta la “fast mode” (modalità veloce) su Claude API. La modalità veloce non è disponibile su Claude Opus 4.7, dove le richieste con speed: "fast" restituiscono un errore. Imposta speed: "fast" nelle tue richieste. Claude Opus 5.5 non richiede un header beta.

  6. Toolset di computer use e strumento di browser use: Claude Opus 5.5 supporta il “computer use” (uso del computer) come toolset computer_toolset_20260801 e lo strumento di “browser use” (uso del browser) per le attività all’interno delle pagine web. Claude Opus 4.7 non supporta nessuno dei due. Per migrare un’integrazione computer_20251124 al toolset, consulta la modifica non retrocompatibile del computer use.

Migrazione a Claude Opus 5.5 da Claude Opus 4.6 e modelli Opus precedenti

Per prima cosa, esamina ogni sezione precedente, nell’ordine della pagina. Si tratta di Cosa deve soddisfare ogni richiesta a Claude Opus 5.5, Gestire il ragionamento in ogni risposta e delle sezioni relative a Claude Opus 5, Claude Opus 4.8 e Claude Opus 4.7. Tali sezioni si applicano così come sono scritte al codice su Claude Opus 4.6. Come Claude Opus 4.7, accetta thinking: {"type": "disabled"}, la scelta forzata dello strumento e lo strumento computer_20251124. Usa per impostazione predefinita l’effort high ed è eseguito senza ragionamento a meno che tu non lo richieda. Anche Claude Opus 4.5 e i modelli Opus precedenti accettano thinking: {"type": "disabled"} e la scelta forzata dello strumento, e sono eseguiti senza ragionamento a meno che tu non lo richieda, quindi quelle sezioni si applicano anche a loro.

Questa sezione aggiunge ciò che è cambiato in Claude Opus 4.7, con claude-opus-4-6 come ID del modello da sostituire. Le sue due sottosezioni aggiungono ciò che è cambiato prima, per chi utilizza Claude Opus 4.5 o precedenti e Claude 4.1 o precedenti. Per una checklist, consulta la checklist di migrazione fino al gruppo che nomina il tuo modello.

Modifiche che causano interruzioni

  1. Ragionamento esteso rimosso: thinking: {"type": "enabled", "budget_tokens": N} non è più supportato su Claude Opus 4.7 e sui modelli successivi e restituisce un errore 400. Passa all’“adaptive thinking” (ragionamento adattivo) (thinking: {"type": "adaptive"}) e usa il parametro 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):

    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:

    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 può essere orientato tramite il prompting e il parametro effort, che sostituisce il budget di ragionamento come modo per controllare quanto il modello ragiona. Esegui una serie di test sui livelli di effort con le tue valutazioni invece di convertire un valore di budget_tokens. La tabella dei livelli di effort descrive quando usare ciascun livello, e Livelli di effort consigliati per Claude Opus 5.5 copre questo modello.

  2. Parametri di campionamento rimossi: Ometti temperature, top_p e top_k. Il prompting è il modo consigliato per guidare il comportamento del modello su Claude Opus 5.5. Se usavi temperature = 0 per il determinismo, tieni presente che non ha mai garantito output identici sui modelli precedenti.

  3. Contenuto del ragionamento omesso per impostazione predefinita: I blocchi di ragionamento compaiono ancora nello stream di risposta su Claude Opus 4.7 e sui modelli successivi, ma il loro campo thinking è vuoto a meno che tu non scelga esplicitamente di attivarlo. Si tratta di una modifica silenziosa rispetto a Claude Opus 4.6, dove l’impostazione predefinita era restituire il testo di ragionamento riassunto. Per ripristinarlo, consulta il punto 4 di Gestire il ragionamento in ogni risposta.

  4. Conteggio dei token aggiornato: Claude Opus 4.7 ha introdotto un nuovo tokenizer, utilizzato anche dai modelli Opus successivi, incluso Claude Opus 5.5. Contribuisce a migliorare le prestazioni su un’ampia gamma di attività e potrebbe usare da circa 1x a 1,35x token nell’elaborazione del testo rispetto ai modelli precedenti a Claude Opus 4.7 (fino a circa il 35 percento in più, a seconda del contenuto).

    /v1/messages/count_tokens restituisce un numero di token diverso per Claude Opus 5.5 rispetto a quello restituito per Claude Opus 4.6. L’efficienza dei token può variare in base alla forma del carico di lavoro.

    Aggiorna i tuoi parametri max_tokens per dare un margine aggiuntivo, inclusi i trigger di compattazione, e ritesta qualsiasi percorso di codice che stima i token lato client o presuppone un rapporto fisso token/caratteri. Usa l’endpoint di Conteggio dei token per verificare. Gli interventi sul prompting, task_budget ed effort possono aiutare a controllare i costi; questi controlli potrebbero comportare un compromesso sull’intelligenza del modello.

  5. Rimozione del prefill (già in vigore su Claude Opus 4.6): Il prefill dei messaggi dell’assistente restituisce un errore 400 su Claude Opus 4.6 e sui modelli Opus successivi, incluso Claude Opus 5.5, quindi si tratta di una modifica solo se provieni da Claude Opus 4.5 o precedenti. Usa invece gli output strutturati o le istruzioni nel prompt di sistema.

Modifiche di comportamento

Claude Opus 4.7 ha introdotto differenze comportamentali rispetto a Claude Opus 4.6 che non sono modifiche dell’API che causano interruzioni. Queste tre riguardano il codice o lo scaffolding:

  1. Aggiornamenti sui progressi integrati nelle tracce agentiche: Claude Opus 4.7 fornisce all’utente aggiornamenti più regolari e di qualità superiore durante le lunghe tracce agentiche. Se hai aggiunto uno scaffolding per forzare messaggi di stato intermedi (“Dopo ogni 3 chiamate agli strumenti, riassumi i progressi”), prova a rimuoverlo. Su Claude Opus 5.5 questi aggiornamenti arrivano in blocchi thinking, che sono vuoti con il valore predefinito di thinking.display. Per riceverli, consulta Il testo tra le chiamate agli strumenti viene restituito nei blocchi di ragionamento. Per definirne la lunghezza e il contenuto, consulta Aggiornamenti sui progressi rivolti all’utente.

  2. Salvaguardie di cybersicurezza in tempo reale: Queste salvaguardie sono nuove in Claude Opus 4.7: le richieste che riguardano argomenti vietati o ad alto rischio potrebbero portare a rifiuti. Per attività di sicurezza legittime come penetration testing, ricerca di vulnerabilità o red-teaming, fai domanda al Cyber Verification Program per richiedere restrizioni ridotte. La modalità di richiesta dipende da come accedi a Claude.

  3. Supporto per immagini ad alta risoluzione: Claude Opus 4.7 è il primo modello Claude con supporto per immagini ad alta risoluzione. La risoluzione massima delle immagini è di 2.576 pixel sul lato lungo, rispetto ai 1.568 pixel dei modelli precedenti. Questo consente miglioramenti nei carichi di lavoro con forte componente visiva ed è particolarmente prezioso per il computer use, la comprensione di screenshot e l’analisi di documenti.

    Il supporto per l’alta risoluzione è automatico e non richiede alcun header beta né attivazione lato client. Due aspetti da pianificare:

    • Le immagini a piena risoluzione possono usare fino a circa 3 volte più token immagine rispetto ai modelli precedenti (fino a 4.784 token per ogni immagine, rispetto al limite precedente di circa 1.600 token). Ricalcola il budget di max_tokens e le aspettative di costo per i carichi di lavoro con molte immagini, oppure riduci la risoluzione prima dell’invio se non hai bisogno della fedeltà aggiuntiva.
    • Le coordinate di puntamento e dei riquadri di delimitazione restituite dal modello sono in rapporto 1:1 con i pixel effettivi dell’immagine su Claude Opus 4.7, quindi non è necessaria alcuna conversione con fattore di scala.

    Consulta Supporto per immagini ad alta risoluzione su Claude Opus 4.7 per i dettagli.

Per le differenze lato prompt, consulta Prompting di Claude Opus 5.5 e Best practice per il prompting.

Migrazione da Claude Opus 4.5 o precedenti

Se stai migrando direttamente a Claude Opus 5.5 da Claude Opus 4.5, Claude Opus 4.1 o un modello precedente, leggi questa pagina dall’inizio: per prima cosa esamina ogni sezione precedente, nell’ordine della pagina. Poi esamina le modifiche che causano interruzioni per la migrazione da Claude Opus 4.6 più sopra in questa sezione. Quindi applica le seguenti modifiche cumulative, entrate in vigore tra Claude Opus 4.5 e Claude Opus 4.7. Se utilizzi Claude Opus 4.1 o precedenti, prosegui con Migrazione da Claude 4.1 o precedenti dopo questa sottosezione.

Modifiche che causano interruzioni

  1. La rimozione del prefill è trattata nelle modifiche che causano interruzioni per la migrazione da Claude Opus 4.6.

  2. Quoting dei parametri degli strumenti: Claude Opus 4.6 e i modelli successivi potrebbero produrre un escaping delle stringhe JSON leggermente diverso negli argomenti delle chiamate agli strumenti (ad esempio, una gestione diversa degli escape Unicode o dell’escaping della barra). Se analizzi l’input delle chiamate agli strumenti come stringa grezza invece di usare un parser JSON, controlla la tua logica di parsing. I parser JSON standard (come json.loads() o JSON.parse()) gestiscono automaticamente queste differenze.

Il primo punto è obbligatorio su Claude Opus 5.5; gli altri sono consigliati.

  1. Migra al ragionamento adattivo (obbligatorio): thinking: {"type": "enabled", "budget_tokens": N} restituisce un errore 400 su Claude Opus 4.7 e sui modelli successivi. Il prima e dopo si trova al punto 1 delle modifiche che causano interruzioni per la migrazione da Claude Opus 4.6. La migrazione passa inoltre da client.beta.messages.create() a client.messages.create(): il ragionamento adattivo e l’effort non richiedono il namespace beta dell’SDK né alcun header beta.

  2. Rimuovi l’header beta di effort: Il parametro effort non richiede un header beta. Rimuovi la beta effort-2025-11-24 dalle tue richieste.

  3. Rimuovi l’header beta dello streaming granulare degli strumenti: Lo streaming granulare degli strumenti non richiede un header beta. Rimuovi la beta fine-grained-tool-streaming-2025-05-14 dalle tue richieste.

  4. Rimuovi l’header beta del ragionamento interleaved: Con il ragionamento adattivo, il ragionamento interleaved è automatico su ogni modello che supporta il ragionamento adattivo. Rimuovi la beta interleaved-thinking-2025-05-14 dalle tue richieste.

  5. Migra a output_config.format: Se usi gli output strutturati, aggiorna output_format={...} a output_config={"format": {...}}. Il parametro output_format è deprecato e verrà rimosso in futuro. Per usarlo comunque, aggiungi l’header beta structured-outputs-2025-11-13. Senza di esso, l’API restituisce un errore 400. L’SDK Python (v1.0 e successive) non accetta output_format={...} su client.beta.messages.create() o count_tokens(). L’argomento output_format=Model degli helper parse() e stream() rimane invariato.

Migrazione da Claude 4.1 o precedenti

Se stai migrando direttamente a Claude Opus 5.5 da Claude Opus 4.1 o modelli precedenti, applica prima tutto quanto indicato in Migrazione da Claude Opus 4.5 o precedenti. Quella sottosezione inizia con ogni sezione precedente, quindi in pratica leggi questa pagina dall’inizio. Poi applica le modifiche aggiuntive di questa sottosezione.

Ulteriori modifiche che causano interruzioni

  1. Rimuovi i parametri di campionamento: Trattato in Parametri di campionamento rimossi.

  2. Aggiorna le versioni degli strumenti

    Aggiorna alle versioni attuali degli strumenti. Rimuovi qualsiasi codice che usa il comando undo_edit.

    # Prima
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 per i dettagli.
    • Esecuzione del codice: Aggiorna a code_execution_20260521. Consulta la documentazione dello strumento di esecuzione del codice per le istruzioni di migrazione.
    • Computer use: Usa il toolset computer_toolset_20260801 al posto di computer_20250124, che Claude Opus 5.5 non accetta. Su Amazon Bedrock funziona anche computer_20251124. Consulta la modifica incompatibile del computer use.

  3. Gestisci il motivo di interruzione refusal

    Aggiorna la tua applicazione per gestire i motivi di interruzione refusal:

    response = client.messages.create(...)

if response.stop_reason == "refusal":
    # Gestisci il rifiuto in modo appropriato
    pass

  4. Gestisci il motivo di interruzione model_context_window_exceeded

    I modelli Claude 4.5 e successivi restituiscono un motivo di interruzione model_context_window_exceeded quando la generazione si interrompe per aver raggiunto il limite della finestra di contesto, anziché il limite max_tokens richiesto. Aggiorna la tua applicazione per gestire questo nuovo motivo di interruzione:

    response = client.messages.create(...)

if response.stop_reason == "model_context_window_exceeded":
    # Gestisci in modo appropriato il limite della finestra di contesto
    pass

  5. Verifica la gestione dei parametri degli strumenti (newline finali)

    I modelli Claude 4.5 e successivi preservano i newline finali nei parametri stringa delle chiamate agli strumenti, che in precedenza venivano rimossi. Se i tuoi strumenti si basano sulla corrispondenza esatta delle stringhe con i parametri delle chiamate agli strumenti, verifica che la tua logica gestisca correttamente i newline finali.

  6. Aggiorna i tuoi prompt per i cambiamenti comportamentali

    I modelli Claude 4 e successivi hanno uno stile di comunicazione più conciso e diretto e richiedono indicazioni esplicite. Consulta le best practice per il prompting per indicazioni sull’ottimizzazione.

  • Header beta: Rimuovi token-efficient-tools-2025-02-19 e output-128k-2025-02-19. Tutti i modelli Claude 4 e successivi hanno l’uso degli strumenti efficiente in termini di token integrato, e questi header non hanno alcun effetto.

Migrazione a Claude Opus 5.5 da Claude Sonnet 5

Esamina Cosa deve soddisfare ogni richiesta a Claude Opus 5.5, Gestire il ragionamento in ogni risposta e Migrazione a Claude Opus 5.5 da Claude Opus 5. Usa claude-sonnet-5 come ID del modello da sostituire. Quest’ultima sezione si applica così come è scritta al codice su Claude Sonnet 5, perché Claude Sonnet 5, come Claude Opus 5:

  • Viene eseguito con il ragionamento attivo per impostazione predefinita e accetta thinking: {"type": "disabled"}, nel suo caso a qualsiasi livello di effort.
  • Accetta la scelta forzata dello strumento e lo strumento computer_20251124.
  • Restituisce il testo tra le chiamate agli strumenti come blocchi text.
  • Usa per impostazione predefinita l’effort high.

Il ragionamento esteso manuale, i parametri di campionamento e il prefill dell’assistente restituiscono un errore 400 su entrambi i modelli, quindi lì non cambia nulla. Nessuna delle modifiche obbligatorie nelle sezioni per Claude Opus 4.8, Claude Opus 4.7 e Claude Opus 4.6 si applica a te.

Cosa è cambiato

  1. Messaggi di sistema a metà conversazione: Su Claude API, Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) e Claude Models on Google Cloud (Google managed), Claude Opus 5.5 accetta messaggi role: "system" immediatamente dopo un turno utente nell’array messages (nel rispetto delle regole di posizionamento). 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 sui turni precedenti.

  2. Soglia minima della cache dei prompt ridotta: La lunghezza minima del prompt memorizzabile nella cache su Claude Opus 5.5 è di 512 token, rispetto ai 1.024 token su Claude Sonnet 5. I prompt che erano troppo brevi per essere memorizzati nella cache su Claude Sonnet 5 possono creare voci nella cache, senza richiedere modifiche al codice. Consulta Cache dei prompt per i valori minimi per modello.

Questa pagina ti è stata utile?