Guida alla migrazione a Claude Sonnet 5.5

Questa guida elenca le modifiche al codice necessarie per passare a Claude Sonnet 5.5 da Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Sonnet 4, Claude 3.7 Sonnet o Claude Haiku 4.5. Leggi le prime due sezioni, poi prosegui fino alla sezione relativa al tuo modello attuale. La checklist di migrazione elenca ogni modifica in base al modello di partenza.

Claude Sonnet 5.5 ha gli stessi prezzi di Claude Sonnet 5, tranne per le letture dalla cache dei prompt, che costano $0,10 USD per milione di token, la metà della tariffa di Claude Sonnet 5. Consulta Prezzi. Per la “context window” (finestra di contesto) e i limiti di output, consulta la pagina del modello Claude Sonnet 5.5. Per funzionalità e prompting, consulta Novità di Claude Sonnet 5.5 e Prompting con Claude Sonnet 5.5.

Inviare una richiesta a Claude Sonnet 5.5

Questa richiesta funziona su Claude Sonnet 5.5 così com’è scritta. Imposta un livello di effort e omette cinque impostazioni che restituiscono un errore 400: budget di ragionamento, parametri di campionamento, prefill dell’assistente, scelta forzata dello strumento e thinking: {"type": "disabled"}.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Analyze the trade-offs between microservices and monolithic architectures",
        }
    ],
    output_config={"effort": "medium"},
)

print(f"Stop reason: {response.stop_reason}")
for block in response.content:
    if block.type == "text":
        print(block.text)

Il ragionamento è attivo per impostazione predefinita

Su Claude Sonnet 5.5, una richiesta senza il campo thinking viene eseguita con l’“adaptive thinking” (ragionamento adattivo), così come thinking: {"type": "adaptive"}. Su Claude Sonnet 4.6 e modelli precedenti e su Claude Haiku 4.5, quella richiesta veniva eseguita senza ragionamento. Per continuare a eseguire senza ragionamento anticipato, consulta Disattivare il ragionamento anticipato.

Gestire il ragionamento nelle risposte

Il codice che veniva eseguito senza ragionamento necessita di tutti e tre gli elementi. Il codice proveniente da Claude Sonnet 5 probabilmente ha già i primi due.

• Leggi i blocchi di contenuto in base al type. Una risposta può iniziare con blocchi thinking, quindi il codice che legge content[0].text smette di funzionare.
• Restituisci i blocchi thinking invariati nei cicli di uso degli strumenti, inclusi quelli vuoti. Consulta Preservare i blocchi di ragionamento.
• Rivedi max_tokens. Copre ragionamento più testo, e i token di ragionamento vengono fatturati come token di output. Consulta Controllo dei costi.

Il testo del ragionamento è omesso per impostazione predefinita. I blocchi thinking arrivano con un campo thinking vuoto e una signature. Per ottenere riepiloghi leggibili, imposta display: "summarized", il valore predefinito su Claude Sonnet 4.6 e modelli precedenti e su Claude Haiku 4.5. Consulta Controllare la visualizzazione del ragionamento.

Disattivare il ragionamento anticipato

Per disattivare il ragionamento anticipato su Claude Sonnet 5.5, invia thinking: {"type": "between_tools"}. È l’impostazione di ragionamento più bassa. I suoi aggiornamenti sui progressi tra le chiamate agli strumenti vengono comunque restituiti come blocchi thinking con il relativo testo di riepilogo. Senza strumenti, la risposta contiene solo testo. Claude Sonnet 5 disattiva invece il ragionamento con thinking: {"type": "disabled"}, e i modelli precedenti vengono eseguiti senza ragionamento per impostazione predefinita. Su Claude Sonnet 5.5, disabled restituisce un errore 400 invalid_request_error:

To turn thinking off on this model, send "thinking": {"type": "between_tools"} instead of {"type": "disabled"}. The model does not think before responding. The short updates it writes between tool calls come back as thinking blocks.

between_tools funziona su ogni piattaforma che offre Claude Sonnet 5.5. È accettato con effort low, medium e high. Con xhigh o max, restituisce un errore 400. Per eseguire a quei livelli, usa il ragionamento adattivo: ometti il campo thinking o invia thinking: {"type": "adaptive"}. between_tools non accetta altri campi: display, budget_tokens o block_binding inviati insieme a esso restituiscono un errore 400. Con il fallback lato server, una richiesta between_tools che ricade su Claude Sonnet 5 viene eseguita lì con thinking: {"type": "disabled"}.

Con between_tools, l’effort non può cambiare a metà conversazione: un output_config.effort per singolo messaggio diverso dal livello in vigore restituisce un errore 400. Per variare l’effort a ogni turno, usa il ragionamento adattivo. Per indicazioni sul prompting, consulta Eseguire senza ragionamento anticipato.

Prima (Claude Sonnet 5):

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

Dopo (Claude Sonnet 5.5):

client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=16000,
    thinking={"type": "between_tools"},
    output_config={"effort": "high"},
    messages=[{"role": "user", "content": "..."}],
)

Checklist di migrazione per modello di partenza

Procedi attraverso i gruppi e fermati dopo quello che nomina il tuo modello. Su Claude Haiku 4.5, applica ogni gruppo tranne “Claude Sonnet 4 o precedenti”, terminando con “Solo Claude Haiku 4.5”.

Ogni modello di partenza

• Cambia l’ID del modello in claude-sonnet-5-5.
• Leggi i blocchi di contenuto in base al type e restituisci i blocchi thinking senza modifiche.
• Per continuare a eseguire senza ragionamento anticipato, invia l’impostazione di ragionamento più bassa con effort high o inferiore.
• Sostituisci l’uso forzato degli strumenti con auto e strumenti rigorosi.
• Mantieni le conversazioni append-only (solo in aggiunta).
• Sposta il computer use al toolset, senza l’header beta fine-grained-tool-streaming-2025-05-14. Su Amazon Bedrock, funziona anche computer_20251124.
• Abbina lo strumento advisor a un advisor supportato e aspettati consigli crittografati.
• Leggi il testo tra le chiamate agli strumenti dai blocchi thinking.
• Gestisci i rifiuti e configura il fallback.
• Esegui di nuovo la tua analisi dell’effort e ristabilisci la baseline dei costi.

Claude Sonnet 4.6 o precedenti

• Aspettati il ragionamento sulle richieste senza campo thinking e rivedi max_tokens.
• Sostituisci i budget di ragionamento con un livello di effort.
• Rimuovi temperature, top_p e top_k.
• Se mostri il testo del ragionamento, imposta display: "summarized".
• Riconta i token e ricalcola il budget dei token per le immagini.

Claude Sonnet 4.5 o precedenti

• Sostituisci i prefill dell’assistente.
• Analizza l’input delle chiamate agli strumenti con un parser JSON standard.
• Imposta output_config.effort in modo esplicito.
• Rimuovi qualsiasi header beta relativo alla finestra di contesto.
• Rimuovi interleaved-thinking-2025-05-14 e sostituisci fine-grained-tool-streaming-2025-05-14 con eager_input_streaming.
• Sposta output_format in output_config.format.

Claude Sonnet 4 o precedenti

• Aggiorna le versioni degli strumenti a text_editor_20250728 e code_execution_20260521.
• Gestisci i motivi di arresto refusal e model_context_window_exceeded.
• Controlla i parametri stringa degli strumenti per i ritorni a capo finali.
• Rimuovi token-efficient-tools-2025-02-19 e output-128k-2025-02-19.
• Rivedi i tuoi prompt.

Solo Claude Haiku 4.5

• Sostituisci claude-haiku-4-5-20251001 o il suo alias.
• Ricalcola la baseline dei costi con il prezzo per token più alto.
• Rivedi i prompt che erano troppo brevi per essere memorizzati nella cache su Claude Haiku 4.5.

Migrazione a Claude Sonnet 5.5 da Claude Sonnet 5

Ogni modello di partenza richiede le modifiche di questa sezione. Sostituisci l’ID del modello con claude-sonnet-5-5, che non ha suffisso di data. Sulle altre piattaforme, usa l’ID elencato in Disponibilità.

L’uso forzato degli strumenti non è supportato

Ogni modello precedente in questa pagina accetta un tool_choice di tipo any o tool. Claude Sonnet 5.5 li rifiuta entrambi con un errore 400, anche sull’endpoint di conteggio dei token:

tool_choice: type "tool" and "any" are not supported for this model.

Invia tool_choice: {"type": "auto"} e contrassegna lo strumento con strict: true in modo che il suo input corrisponda allo schema. Il modello può quindi rispondere senza chiamare lo strumento, perciò indica nel prompt quando usarlo. L’uso rigoroso degli strumenti supporta un sottoinsieme di JSON Schema e richiede additionalProperties: false su ogni oggetto. Consulta Limitazioni di JSON Schema.

Prima (Claude Sonnet 5):

client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)

Dopo (Claude Sonnet 5.5):

client.messages.create(
    model="claude-sonnet-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.",
        }
    ],
)

L’esempio contrassegna come rigoroso ogni strumento dell’elenco. Una richiesta può avere al massimo 20 strumenti rigorosi, e le voci dei toolset MCP, computer use e browser use non accettano strict. In un elenco di strumenti più lungo, contrassegna solo gli strumenti che ne hanno bisogno.

I blocchi di ragionamento sono legati al modello e alla conversazione

Claude Sonnet 5.5 legge i blocchi di ragionamento di Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5 e modelli precedenti. Sulla Claude API e su Claude Models on Google Cloud (Google managed), li legge anche da Claude Haiku 5.5. Non legge i blocchi di Claude Opus 5, Claude Opus 5.5 o di qualsiasi modello Claude Fable o Claude Mythos.

L’API scarta i blocchi che il modello non può leggere. La richiesta restituisce 200, e i blocchi scartati non vengono fatturati. Consulta Cambiare modello e tornare indietro.

Mantieni le conversazioni solo in aggiunta, in modo che i blocchi di ragionamento superino il “prefix check” (controllo del prefisso). Per modificare istruzioni o strumenti, consulta Messaggi di sistema e modifiche agli strumenti a metà conversazione.

Non superare il “prefix check” (controllo del prefisso) potrebbe causare oppure no un errore 400. Per identificare e gestire entrambi i casi, consulta Controlli del prefisso sui blocchi di ragionamento.

Il controllo del prefisso viene eseguito sulla Claude API e su alcune piattaforme cloud.

I blocchi di ragionamento di Claude Sonnet 5.5 funzionano solo nell’account che li ha prodotti o in un account a esso collegato. Consulta Ragionamento preservato.

Alcune versioni dello strumento computer use non sono supportate

Claude Sonnet 5.5 supporta il computer use tramite il toolset computer_toolset_20260801. Su Amazon Bedrock, Claude Sonnet 5.5 accetta anche lo strumento computer_20251124 con l’header beta computer-use-2025-11-24. Claude Sonnet 5.5 restituisce un errore 400 per qualsiasi versione dello strumento computer use che non accetta, come computer_20251124 sulla Claude API. Non accetta computer_20250124 su nessuna piattaforma.

Le integrazioni che usano il toolset non richiedono modifiche. Per passare al toolset, sostituisci computer_20251124 o computer_20250124 con computer_toolset_20260801 e rimuovi l’header beta di quella versione. Per le modifiche alla richiesta e al ciclo dell’agente, consulta Migrare da computer_20251124.

Se invii l’header beta fine-grained-tool-streaming-2025-05-14, rimuovilo quando passi al toolset. Insieme a una voce di toolset, restituisce un errore 400. Imposta invece eager_input_streaming: true su ogni strumento che ne ha bisogno.

Lo strumento advisor accetta meno advisor

Con lo strumento advisor, un executor Claude Sonnet 5.5 richiede uno di questi advisor: Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5, Claude Fable 5.1, Claude Fable 5.2, Claude Mythos 5, Claude Mythos 5.1 o Claude Mythos 5.2. Gli advisor Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5, Claude Sonnet 4.6 e Claude Haiku 5.5 restituiscono un errore 400. Il consiglio viene restituito cifrato come blocco advisor_redacted_result, quindi il suo testo non è leggibile nella risposta. Consulta Compatibilità dei modelli.

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

Su Claude Sonnet 5.5, le note più lunghe di una o due frasi che il modello scrive tra le chiamate agli strumenti vengono restituite come blocchi thinking di aggiornamento sui progressi, vuoti con il display predefinito. Le osservazioni più brevi restano text. Su Claude Sonnet 5 e modelli precedenti, tutto il testo tra le chiamate agli strumenti viene restituito come blocchi text. Nessuna richiesta fallisce, ma un’interfaccia che mostra quelle note smette di mostrarle.

Con il ragionamento adattivo, imposta display su "updates" (beta, header thinking-display-updates-2026-08-18) per ottenere solo gli aggiornamenti, oppure su "summarized" per ottenerli mescolati al ragionamento. Visualizza ogni blocco thinking non vuoto prima del blocco tool_use che lo segue. Con between_tools, il testo viene restituito senza display. Consulta Aggiornamenti sui progressi rivolti all’utente.

Classificatori di sicurezza e fallback

Claude Sonnet 5.5 rifiuta in più categorie rispetto a Claude Sonnet 5. Un rifiuto restituisce stop_reason: "refusal", e il suo stop_details può indicare una di queste categorie:

• "cyber": La richiesta potrebbe favorire danni informatici, come lo sviluppo di malware o exploit.
• "bio": La richiesta potrebbe favorire danni biologici, come metodi di laboratorio pericolosi.
• "frontier_llm": La richiesta potrebbe aiutare lo sviluppo di modelli di IA concorrenti.
• "reasoning_extraction": La richiesta chiede al modello di riprodurre il proprio ragionamento interno nel testo della risposta.
• "general_harms": La richiesta rientra in un’altra area della policy di utilizzo. Anche un lavoro innocuo può attivare questa categoria.

Il fallback lato server (fallbacks: "default"), in beta sulla Claude API e su Claude Models on Google Cloud (Anthropic managed), ritenta i rifiuti "cyber" e "frontier_llm" su Claude Sonnet 5. Non ritenta i rifiuti "bio", "reasoning_extraction" o "general_harms". Consulta Rifiuti e fallback e Come vengono fatturati i rifiuti.

Le protezioni informatiche in tempo reale sono una novità per il codice proveniente da Claude Sonnet 4.6, Claude Sonnet 4.5 e Claude Haiku 4.5. Per attività di sicurezza legittime, candidati al Cyber Verification Program.

Altre modifiche

• “Prompt caching” (cache dei prompt): Il prompt minimo memorizzabile nella cache è di 512 token, in calo rispetto ai 1.024 di Claude Sonnet 5, Claude Sonnet 4.6 e Claude Sonnet 4.5. Consulta Cache dei prompt.
• Nuove funzionalità: Per i messaggi di sistema a metà conversazione, le modifiche agli strumenti a metà conversazione e l’effort per singolo messaggio, consulta Novità di Claude Sonnet 5.5. Con between_tools, l’effort non può cambiare a metà conversazione.

Modifiche consigliate

Ripeti la tua analisi dell’effort. Claude Sonnet 5.5 ha cinque livelli di effort: low, medium, high, xhigh e max. Il valore predefinito sulla Claude API è high. I livelli sono stati ricalibrati, quindi un livello non produce la stessa quantità di ragionamento di Claude Sonnet 5. Inizia con high a meno che il tuo carico di lavoro non sia agentico o sensibile alla latenza. Per il coding agentico e l’uso degli strumenti in più passaggi, inizia con medium per attività ben specificate e passa a high per quelle più difficili o più lunghe. Per la chat e altri lavori sensibili alla latenza, inizia con medium o low. Imposta il livello in output_config.effort. Consulta Livelli di effort consigliati per Claude Sonnet 5.5. Quindi rivaluta le istruzioni dei prompt specifiche per il modello in base a Prompting con Claude Sonnet 5.5.

Migrazione a Claude Sonnet 5.5 da Claude Sonnet 4.6 e modelli Sonnet precedenti

Applica prima tutte le sezioni precedenti, sostituendo claude-sonnet-4-6. Poi apporta queste modifiche. Su Claude Sonnet 4.5 o precedenti, prosegui con le sottosezioni che seguono.

Modifiche che causano incompatibilità

Il ragionamento viene eseguito sulle richieste che lo omettevano. Consulta Il ragionamento è attivo per impostazione predefinita e Disattivare il ragionamento anticipato.

I budget di ragionamento restituiscono un errore. Claude Sonnet 4.6 accetta thinking: {"type": "enabled", "budget_tokens": N} come impostazione deprecata. Claude Sonnet 4.5 e Claude Haiku 4.5 lo usano per tutto il ragionamento. Claude Sonnet 5.5 restituisce un errore 400:

"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

Rimuovi il budget e imposta un livello di effort. Non esiste una corrispondenza fissa tra un budget e un livello di effort, quindi esegui le tue valutazioni su due o tre livelli.

Prima (Claude Sonnet 4.6):

client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[{"role": "user", "content": "..."}],
)

Dopo (Claude Sonnet 5.5):

client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # or "max", "xhigh", "medium", "low"
    messages=[{"role": "user", "content": "..."}],
)

I parametri di campionamento restituiscono un errore. Rimuovi temperature, top_p e top_k.

Il testo del ragionamento è omesso per impostazione predefinita. Consulta Gestire il ragionamento nelle risposte.

Altre modifiche

• Circa il 30 percento di token in più: Claude Sonnet 5.5 usa il tokenizer di Claude Sonnet 5. Rispetto a Claude Sonnet 4.6, Claude Sonnet 4.5 e Claude Haiku 4.5, lo stesso testo produce circa il 30 percento di token in più, a seconda del contenuto. Riconta con il conteggio dei token e rivedi max_tokens e i costi.
• Effort: Claude Sonnet 5.5 supporta xhigh, e i livelli sono stati ricalibrati. Consulta Modifiche consigliate.
• Immagini: Claude Sonnet 5.5 usa il livello di immagini ad alta risoluzione, fino a 2.576 pixel sul lato lungo e fino a 4.784 token visivi per immagine. Claude Sonnet 4.6, Claude Sonnet 4.5 e Claude Haiku 4.5 si fermano a 1.568 pixel e 1.568 token. Un’immagine 2000×1500 costa circa 2,5 volte più token su Claude Sonnet 5.5. Consulta Risoluzione e costo in token.

Migrazione da Claude Sonnet 4.5 o precedenti

Su Claude Sonnet 4.5, Claude Sonnet 4 o Claude 3.7 Sonnet, applica prima tutte le sezioni precedenti, poi queste modifiche.

Il prefill restituisce un errore. Claude Sonnet 5.5 rifiuta un ultimo turno dell’assistente precompilato con un errore 400, come fanno Claude Sonnet 4.6 e Claude Sonnet 5. Claude Sonnet 4.5, Claude Haiku 4.5 e i modelli più vecchi lo accettano. L’errore riporta:

This model does not support assistant message prefill. The conversation must end with a user message.

Sostituisci ogni prefill in base al suo scopo:

• Formato di output: usa gli output strutturati, oppure strumenti con campi enum per la classificazione.
• Preamboli: chiedi nel prompt di sistema una risposta diretta.
• Rifiuti indesiderati: di solito bastano istruzioni chiare nel messaggio dell’utente.
• Continuazioni: spostale nel messaggio dell’utente, ad esempio “La tua risposta precedente è stata interrotta e terminava con [previous_response]. Continua da dove avevi interrotto.”
• Promemoria di contesto: inseriscili nel turno dell’utente.

Escaping dell’input degli strumenti. L’escaping negli argomenti delle chiamate agli strumenti può differire. Analizza input con un parser JSON standard.

Computer use. Claude Sonnet 5.5 non accetta computer_20250124. Consulta Alcune versioni dello strumento computer use non sono supportate.

Effort. Claude Sonnet 4.5 non ha un parametro effort. Imposta esplicitamente un livello di effort (consulta Modifiche consigliate).

Contesto e output. Claude Sonnet 5.5 ha una finestra di contesto più ampia e un limite di output più alto. Consulta la pagina del modello Claude Sonnet 5.5. Rimuovi qualsiasi header beta relativo alla finestra di contesto.

Beta header. Rimuovi interleaved-thinking-2025-05-14, perché il ragionamento adattivo si interfoglia automaticamente. Sostituisci fine-grained-tool-streaming-2025-05-14 con eager_input_streaming: true su ogni strumento che ne ha bisogno. Quell’header restituisce un errore 400 insieme a una voce di toolset computer use o browser use. Consulta Streaming granulare degli strumenti.

Output strutturati. Il parametro output_format è deprecato. Per usarlo comunque, aggiungi l’header beta structured-outputs-2025-11-13. Senza di esso, l’API restituisce un errore 400. Usa invece output_config.format.

Migrazione da Claude Sonnet 4 o precedenti

Claude Sonnet 4 è stato ritirato sulla Claude API ma è disponibile su Claude Models on Google Cloud (Google managed) e su Amazon Bedrock. Claude 3.7 Sonnet è stato ritirato. Da uno qualsiasi dei due modelli, applica prima tutte le sezioni precedenti, poi queste modifiche:

• Versioni degli strumenti: Usa text_editor_20250728, con il nome dello strumento str_replace_based_edit_tool e senza il comando undo_edit. Usa code_execution_20260521. Consulta lo strumento di modifica del testo e lo strumento di esecuzione del codice.
• Motivi di arresto: Gestisci refusal. Claude 4.5 e i modelli successivi si fermano anche con model_context_window_exceeded al raggiungimento del limite della finestra di contesto. Consulta Motivi di arresto e fallback.
• Ritorni a capo finali: Claude 4.5 e i modelli successivi li mantengono nei parametri stringa delle chiamate agli strumenti.
• Beta header: Rimuovi token-efficient-tools-2025-02-19 e output-128k-2025-02-19.
• Prompt: Rivedili in base alle best practice di prompting.

Migrazione a Claude Sonnet 5.5 da Claude Haiku 4.5

Applica prima tutte le sezioni fino a Migrazione da Claude Sonnet 4.5 o precedenti inclusa, saltando la sottosezione su Claude Sonnet 4. Poi apporta queste modifiche:

• ID del modello: Sostituisci claude-haiku-4-5-20251001, o l’alias claude-haiku-4-5, con claude-sonnet-5-5.
• Costo: Il prezzo per token è più alto, e lo stesso testo produce più token. Riconta i token e ricalcola la baseline dei costi. Consulta Prezzi.
• Cache dei prompt: Il prompt minimo memorizzabile nella cache scende da 4.096 token al minimo di Claude Sonnet 5.5.
• Ragionamento interfogliato: Il ragionamento adattivo viene eseguito automaticamente tra le chiamate agli strumenti.
• Instradamento: Claude Sonnet 5.5 legge i blocchi di ragionamento di Claude Haiku 4.5. Una conversazione che passa al modello superiore mantiene il proprio ragionamento. Una che torna a Claude Haiku 4.5 scarta i blocchi di Claude Sonnet 5.5.