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

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) e mantiene la "context window" (finestra di contesto) da 1M token e i 128k token di output massimi di Claude Opus 5. Ci sono quattro "breaking changes" (modifiche incompatibili) per il codice già in esecuzione su Claude Opus 5, trattate in Modifiche incompatibili. Per il supporto delle funzionalità, consulta Novità di Claude Opus 5.5.

Migrazione a Claude Opus 5.5 da Claude Opus 5

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 pensiero 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" (pensiero) 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 pensiero non può essere disabilitato.

Prima (accettato su Claude Opus 5, rifiutato su Claude Opus 5.5):

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 any e tool di tool_choice 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 "structured outputs" (output strutturati), e indica nel prompt quando lo strumento è applicabile. Consulta L'uso forzato degli strumenti non è supportato.

Prima:

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 pensiero sono legati al modello e alla conversazione

Sulla Claude API, Claude Fable 5.1 e Claude Mythos 5.1 leggono i blocchi di pensiero 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 pensiero di Claude Opus 5 e dei precedenti modelli Opus, Sonnet e Haiku, ma non quelli dei modelli Claude Fable o Claude Mythos. Mantieni la conversazione "append-only" (solo in aggiunta), senza modifiche al prompt di sistema system, a tools o ai messaggi precedenti a metà conversazione, in modo che i blocchi restino validi; Claude Code, claude.ai, Claude Managed Agents e il Claude Agent SDK lo fanno già. L'applicazione di questa regola 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 pensiero dopo una tale modifica restituisce per impostazione predefinita un errore 400. Non è necessaria alcuna modifica al codice per le integrazioni append-only. Consulta I blocchi di pensiero sono legati al modello e alla conversazione e Pensiero 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:

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 pensiero

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" e "reasoning_extraction" oltre a "cyber"; 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 viene restituito a te); consulta Rifiuti e fallback e Rifiuti delle salvaguardie.

Modifiche consigliate

1. Ripeti la valutazione dei livelli di effort. L'effort è l'unico controllo del pensiero 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 pensiero disabilitato, consulta anche Prompt scritti per il pensiero disabilitato.
3. Esegui i test in un ambiente di sviluppo prima di spostare il traffico di produzione.

Checklist di migrazione

• 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 any e tool di tool_choice con auto più l'uso rigoroso degli strumenti o gli output strutturati.
• 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 ciclo dell'agente per il toolset. Su Amazon Bedrock, mantieni computer_20251124; per le altre piattaforme, controlla la sezione Compatibilità dello strumento di computer use.
• 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 pensiero 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 pensiero di Claude Opus 5 e dei precedenti modelli Opus, Sonnet e Haiku, ma non quello dei modelli Claude Fable o Claude Mythos.
• Leggi i blocchi di contenuto in base a type e restituisci i blocchi thinking senza modifiche nei cicli 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 i turni precedenti, il prompt di sistema system o tools a metà conversazione, segui Pensiero preservato.
• Gestisci stop_reason: "refusal" e configura il fallback.
• Ridefinisci i valori di riferimento di costo e "latency" (latenza) al livello di effort scelto.

Migrazione a Claude Opus 5.5 da Claude Opus 4.8

Segui prima Migrazione a Claude Opus 5 da Claude Opus 4.8: tratta il pensiero attivo per impostazione predefinita e le modifiche alla struttura della risposta che ne derivano. Quindi applica Migrazione da Claude Opus 5. La seconda modifica incompatibile di Claude Opus 5 descritta lì (il pensiero può essere disabilitato solo con effort high o inferiore) non si applica: su Claude Opus 5.5 il pensiero non può essere disabilitato in alcun modo.

Checklist di migrazione

• Tutto ciò che è presente nella checklist Claude Opus 4.8 → Claude Opus 5, tranne il fatto che thinking: {"type": "disabled"} non è un'opzione.
• Tutto ciò che è presente nella checklist Claude Opus 5 → Claude Opus 5.5.

Migrazione a Claude Opus 5.5 da Claude Opus 4.7 e modelli Opus precedenti

La guida alla migrazione a Claude Opus 5 tratta le modifiche incompatibili tra il tuo modello attuale e Claude Opus 5: parametri di campionamento rifiutati, pensiero esteso manuale rifiutato, prefill rimosso e il tokenizer più recente. Segui lì la sezione relativa al tuo modello, usando come destinazione claude-opus-5-5 invece di claude-opus-5, quindi applica Migrazione da Claude Opus 5. Dove quella guida indica che il pensiero può essere disabilitato con effort high o inferiore, su Claude Opus 5.5 non è possibile; e dove afferma che le integrazioni esistenti con computer_20251124 continuano a funzionare, sulla Claude API e su Google Cloud non funzionano con Claude Opus 5.5, che lì accetta il computer use solo come toolset computer_toolset_20260801 (consulta la modifica incompatibile); su Amazon Bedrock continuano a funzionare.

Migrazione a Claude Opus 5.5 da Claude Sonnet 5

Consulta Migrazione a Claude Opus 5 da Claude Sonnet 5 per sapere cosa cambia passando a una classe di modello superiore, quindi applica Migrazione da Claude Opus 5.