Guida alla migrazione a Claude Haiku 5.5

Questa guida spiega come spostare il codice che chiama Claude Haiku 4.5 a Claude Haiku 5.5. Per passare invece a un modello Sonnet o Opus, consulta Aggiornare tra versioni del modello. Per sapere per quanto tempo Claude Haiku 4.5 resterà disponibile, consulta Deprecazioni dei modelli.

Checklist di migrazione

Ogni voce è una modifica da apportare al codice che chiama Claude Haiku 4.5.

1. Sostituisci l'ID del modello con l'ID di Claude Haiku 5.5 per la tua piattaforma. Consulta Usa l'ID del modello Claude Haiku 5.5.
2. Riconta i token dei tuoi prompt e rivedi i limiti di max_tokens e le stime dei costi, perché lo stesso testo corrisponde a più token. Consulta Riconta i token.
3. Se le tue richieste inviano thinking: {"type": "enabled", "budget_tokens": N}, cambia thinking in {"type": "adaptive"}. Consulta Configura il ragionamento.
4. Se il tuo codice legge il primo blocco di contenuto come risposta, seleziona invece i blocchi in base al type. Consulta Configura il ragionamento.
5. Rimuovi temperature, top_p e top_k dalle tue richieste. Consulta Rimuovi i parametri di campionamento.
6. Se le tue richieste terminano messages con un turno dell'assistente che il modello deve continuare, terminale invece con un turno dell'utente. Consulta Sostituisci il prefill dell'assistente.
7. Se usi il computer use sulla Claude API o su Google Cloud, passa da computer_20250124 al toolset computer_toolset_20260801. Consulta Sposta il computer use sul toolset.
8. Se riproduci conversazioni memorizzate tramite un account diverso, riproduci ciascuna tramite l'account che l'ha prodotta. Consulta Riproduci i blocchi di ragionamento tramite l'account che li ha prodotti.
9. Se il tuo codice modifica system, tools o i messages precedenti tra le richieste di una conversazione e rinvia i blocchi di ragionamento, mantieni la conversazione in sola aggiunta. Consulta Mantieni invariati i turni precedenti.
10. Gestisci stop_reason: "refusal". Claude Haiku 5.5 esegue "safety classifiers" (classificatori di sicurezza) che possono rifiutare una richiesta, e non dispone di un fallback lato server. Consulta Rifiuti delle salvaguardie.

Se la tua organizzazione ha un impegno Priority Tier su Claude Haiku 4.5, pianifica la capacità separatamente: il Priority Tier non è supportato su Claude Haiku 5.5.

Usa l'ID del modello Claude Haiku 5.5

Sostituisci l'ID del modello Claude Haiku 4.5 con l'ID di Claude Haiku 5.5 per la tua piattaforma.

claude-haiku-5-5 è un ID del modello fisso, senza suffisso di data e senza un alias separato.

Riconta i token

Claude Haiku 5.5 usa lo stesso "tokenizer" (tokenizzatore) più recente di Claude 4.7 e dei modelli successivi. Come per tutti i modelli che usano questo tokenizer, lo stesso testo di input produce circa il 30% di token in più su Claude Haiku 5.5 rispetto a Claude Haiku 4.5. L'aumento esatto dipende dal contenuto. Richieste, risposte ed eventi di streaming mantengono la stessa struttura. Ciò che cambia è tutto ciò che misuri o pianifichi in token:

• I campi usage e i risultati del conteggio dei token sono più alti per lo stesso testo.
• Un dato numero di token contiene meno testo.
• Un limite di max_tokens calibrato per Claude Haiku 4.5 potrebbe troncare un output equivalente.
• Le stime dei costi basate sui conteggi dei token di Claude Haiku 4.5 devono essere ricalcolate con i conteggi e i prezzi di Claude Haiku 5.5.

Conta i token dei tuoi prompt con model impostato su claude-haiku-5-5 invece di riutilizzare i conteggi misurati su Claude Haiku 4.5.

Configura il ragionamento

Claude Haiku 5.5 configura il "thinking" (ragionamento) in modo diverso da Claude Haiku 4.5. Un valore di thinking pari a {"type": "enabled", "budget_tokens": N} restituisce un errore 400, quindi una richiesta che lo invia necessita di un nuovo valore di thinking.

Prima, una richiesta a Claude Haiku 4.5 impostava thinking su enabled con un budget di token:

{
  "model": "claude-haiku-4-5",
  "max_tokens": 16000,
  "thinking": { "type": "enabled", "budget_tokens": 8000 },
  "messages": [{ "role": "user", "content": "..." }]
}

Dopo, la stessa richiesta a Claude Haiku 5.5 usa l'"adaptive thinking" (ragionamento adattivo). Il valore di thinking cambia e output_config.effort stabilisce quanto ragiona il modello:

{
  "model": "claude-haiku-5-5",
  "max_tokens": 16000,
  "thinking": { "type": "adaptive" },
  "output_config": { "effort": "medium" },
  "messages": [{ "role": "user", "content": "..." }]
}

Il ragionamento adattivo è attivo per impostazione predefinita, quindi una risposta può iniziare con uno o più blocchi thinking anche quando la richiesta non imposta thinking. Lascia thinking non impostato o impostalo su {"type": "adaptive"}, e usa l'effort come leva: dove Claude Haiku 4.5 funzionava senza ragionamento, o con un budget ridotto per risparmiare token, scegli un livello di effort più basso. A un livello più basso il modello ragiona meno e può saltare del tutto il ragionamento nelle richieste più semplici. Per indicazioni sui prompt, consulta Usa l'effort per controllare il ragionamento. Seleziona i blocchi di contenuto in base al loro campo type anziché in base alla posizione, e rinvia i blocchi thinking senza modifiche insieme ai risultati degli strumenti.

I token di ragionamento contano ai fini di max_tokens, quindi una richiesta con un max_tokens ridotto può fermarsi con stop_reason: "max_tokens" dopo un blocco thinking e prima di qualsiasi testo. Se hai impostato un max_tokens ridotto per Claude Haiku 4.5, aumentalo per lasciare spazio al ragionamento, oppure scegli un livello di effort più basso.

Per impostazione predefinita, Claude Haiku 5.5 restituisce ogni blocco thinking con un campo thinking vuoto e solo una signature, mentre Claude Haiku 4.5 restituiva il ragionamento riassunto. Per ricevere il ragionamento riassunto, imposta thinking: {"type": "adaptive", "display": "summarized"}.

Claude Haiku 5.5 accetta un tool_choice forzato (any o uno strumento specifico), ma la risposta inizia con la chiamata allo strumento e non contiene alcun blocco thinking. Per consentire al modello di ragionare prima di chiamare uno strumento, usa tool_choice: {"type": "auto"} e indica nel prompt quando usare lo strumento.

Rimuovi i parametri di campionamento

Claude Haiku 4.5 accetta temperature, top_p e top_k. Su Claude Haiku 5.5, ometti tutti e tre e usa invece il prompt per guidare il comportamento del modello. Se una richiesta include temperature, deve essere 1. Se include top_p, deve essere 0.99, il suo valore predefinito. Qualsiasi altro valore di temperature o top_p restituisce un errore 400, incluso un top_p pari a 1. Lo stesso vale per qualsiasi valore di top_k e per una richiesta che include sia temperature sia top_p.

Sostituisci il prefill dell'assistente

Un "prefill" (precompilazione) è un turno finale dell'assistente in messages che il modello continua. Claude Haiku 4.5 lo accetta quando il ragionamento è disattivato. Claude Haiku 5.5 lo rifiuta con un errore 400, anche con il ragionamento disattivato. Termina messages con un turno dell'utente e sostituisci ogni prefill in base al suo scopo:

• Formato dell'output: usa gli output strutturati, oppure strumenti con campi enum per la classificazione. Su Claude in Amazon Bedrock, che non supporta gli output strutturati, usa gli strumenti.
• Preamboli: chiedi nel prompt di sistema una risposta diretta.
• 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.

Sposta il computer use sul toolset

Claude Haiku 4.5 supporta il computer use tramite lo strumento computer_20250124, con l'header beta computer-use-2025-01-24. Sulla Claude API e su Google Cloud, Claude Haiku 5.5 supporta il computer use solo tramite il "toolset" (set di strumenti) computer_toolset_20260801, e una richiesta che dichiara computer_20250124 restituisce un errore 400.

Per spostare un'integrazione, elimina l'header beta computer-use-2025-01-24 e sostituisci la voce tools con {"type": "computer_toolset_20260801"}. Quindi apporta le altre modifiche alla richiesta e al ciclo dell'agente descritte in Migrare da computer_20251124: smista in base a name e toolset_name di ciascun blocco tool_use membro anziché in base a input.action, gestisci ogni blocco di questo tipo in un turno e riporta toolset_name nei risultati. Lo zoom è attivo per impostazione predefinita nel toolset; se il tuo ambiente non lo implementa, aggiungi "configs": {"zoom": {"enabled": false}}. Se invii l'header beta fine-grained-tool-streaming-2025-05-14, rimuovilo. Insieme a una voce di toolset, restituisce un errore 400. Per le altre piattaforme, consulta la sezione Compatibilità dello strumento di computer use.

Sulla Claude API e su Google Cloud, Claude Haiku 5.5 supporta anche lo strumento browser use (browser_toolset_20260801) per le attività all'interno delle pagine web. Claude Haiku 4.5 non lo supporta.

Riproduci i blocchi di ragionamento tramite l'account che li ha prodotti

I blocchi di ragionamento di Claude Haiku 5.5 funzionano solo nell'account che li ha prodotti o in un account collegato a esso. Quando un altro account invia uno di questi blocchi, l'API scarta il blocco prima che il modello lo veda e la richiesta va a buon fine senza quel ragionamento. Ciò riguarda il codice che memorizza le conversazioni e le riproduce tramite un account diverso, ad esempio un servizio che serve più clienti da un unico archivio di conversazioni. Riproduci ogni conversazione tramite l'account che l'ha prodotta. Consulta I blocchi di ragionamento restano con l'account che li ha prodotti.

Mantieni invariati i turni precedenti

Un blocco di ragionamento di Claude Haiku 5.5 resta valido solo finché tutto ciò che è stato inviato prima di esso rimane invariato: una richiesta che rinvia un blocco di ragionamento dopo una modifica a system, tools o ai messages precedenti restituisce un errore 400. Claude Haiku 4.5 non esegue questo controllo. Mantieni le conversazioni in sola aggiunta. Sugli account creati prima del 31 agosto 2026, 00:00 UTC, l'errore si verifica solo nelle richieste che impostano thinking.block_binding.prefix_mismatch_behavior. Per le modifiche che attivano l'errore e cosa fare invece, consulta Chi deve modificare qualcosa.