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 di richiesta che restituiscono errori, i blocchi di ragionamento in ogni risposta e una checklist per ciascun modello di partenza.

Questa pagina elenca le modifiche al codice necessarie 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. Tutti i lettori devono consultare Cosa deve soddisfare ogni richiesta a Claude Opus 5.5 e Gestisci il ragionamento in ogni risposta. Poi vai alla sezione relativa al tuo modello attuale: la sua prima frase indica le altre sezioni che ti riguardano. La checklist di migrazione 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). 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 Scrivere prompt per 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à.
  • 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 confronto prima/dopo per il ragionamento.
  • Effort: Controlla la profondità del ragionamento con il parametro 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.
  • 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.
  • 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 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.
  • Finestra di contesto: Non è necessario alcun header beta per la finestra di contesto. La finestra di contesto da 1M token è 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.

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)

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. 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. Per spendere meno token nel ragionamento, abbassa il livello di 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.

  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.

  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, 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.

  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.

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à 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.
  • 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.

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, 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 (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, 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, 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 (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 iniziate con Claude Opus 4.7.
  • Se il tuo prodotto svolge attività di sicurezza legittime, fai domanda per il Cyber Verification Program 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() a client.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.

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 e Gestisci il ragionamento in ogni risposta. 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.

Aggiorna il nome del modello

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à.

Modifiche incompatibili

Ogni modifica è spiegata 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. oppure "thinking.type.enabled" is not supported for this model.). Rimuovi il campo thinking e scegli un livello di "effort" (sforzo); 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.

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. 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.

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 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 e Ragionamento preservato.

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. 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à 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.

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:

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 di avanzamento, 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.

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. Gestisci i rifiuti e configura il fallback lato server 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 e Rifiuti delle salvaguardie.

  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.
  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. Se eseguivi con il ragionamento disabilitato, consulta anche Prompt scritti per il ragionamento disabilitato.
  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, Gestisci 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 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.

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 è 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.

  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 per i minimi per 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. Considera i task budget (beta): Per i carichi di lavoro agentici, i task budget 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 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, Gestisci 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. 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 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 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.

  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 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). 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 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. Claude Opus 5.5 rifiuta in più categorie; consulta Classificatori di sicurezza e fallback.

  5. Modalità veloce: Claude Opus 5.5 supporta la modalità veloce 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 come toolset computer_toolset_20260801 e lo strumento browser use 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.

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, Gestisci il ragionamento in ogni risposta e delle sezioni per Claude Opus 5, Claude Opus 4.8 e Claude Opus 4.7. 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 e Claude 4.1 o precedenti. Per una checklist, consulta la checklist di migrazione 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) (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 è orientabile tramite il prompting e il parametro 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 descrive quando usare ciascun livello, e Livelli di effort consigliati per 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.

  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 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 per verificare. Gli interventi sul prompt, task_budget ed 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 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. Per definirne lunghezza e contenuto, consulta Aggiornamenti sui progressi rivolti all'utente.

  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 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 per i dettagli.

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

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 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 dopo questa sottosezione.

Modifiche incompatibili

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

  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.

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. La migrazione comporta anche il passaggio 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 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. 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.

  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: Esegui l'upgrade a code_execution_20260521. Consulta la documentazione dello strumento di esecuzione del codice 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.

  3. Gestisci il motivo di arresto refusal

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

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

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

  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:

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

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

  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 per indicazioni sull'ottimizzazione.

  • 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, Gestisci 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 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). 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. 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 per i minimi per modello.

Was this page helpful?