Claude Platform Docs
Modelli e prezziClaude Opus 5

Migrazione a Claude Opus 5

Migra a Claude Opus 5 dai modelli Claude precedenti: ID dei modelli, modifiche di rilievo, modifiche consigliate e checklist di migrazione.

Claude Opus 5 rappresenta un miglioramento radicale rispetto a Claude Opus 4.8, forte nel ragionamento profondo, nelle attività agentiche e a lungo orizzonte e nello scaling del calcolo in fase di test. Per le differenze comportamentali e i pattern di prompting specifici del modello, consulta Prompting di Claude Opus 5.

Claude Opus 5 è un aggiornamento diretto (drop-in) per Claude Opus 4.8 allo stesso prezzo di $5 USD per milione di token di input e $25 USD per milione di token di output; consulta Prezzi di Claude. Ci sono due modifiche di rilievo (breaking changes) per il codice già in esecuzione su Claude Opus 4.8, trattate in Modifiche di rilievo. Claude Opus 5 supporta lo stesso insieme di funzionalità di Claude Opus 4.8, tra cui la "context window" (finestra di contesto) da 1M di token (predefinita, senza header beta), 128k token di output massimi, il pensiero adattivo, la "prompt caching" (cache dei prompt), l'elaborazione batch, la Files API, il supporto PDF, la visione e gli strumenti lato server e lato client, con due eccezioni: web fetch non è disponibile su Claude Opus 5 e Priority Tier non è supportato su Claude Opus 5. Consulta la pagina di ciascuno strumento per la disponibilità per modello.

Migrazione a Claude Opus 5 da Claude Opus 4.8

Aggiorna il nome del modello

# Migrazione a Opus
model = "claude-opus-4-8"  # Before
model = "claude-opus-5"  # After

claude-opus-5 è un ID di modello fisso senza suffisso di data, lo stesso schema di claude-opus-4-8 e claude-sonnet-5.

Modifiche di rilievo

  1. Pensiero attivo per impostazione predefinita: Su Claude Opus 4.8, le richieste senza un campo thinking vengono eseguite senza pensiero; su Claude Opus 5, le stesse richieste vengono eseguite con il pensiero adattivo. max_tokens rimane un limite rigido sull'output totale, pensiero più testo della risposta, quindi rivedilo per i carichi di lavoro che venivano eseguiti senza pensiero su Claude Opus 4.8. I token di pensiero vengono fatturati come token di output anche quando il testo del pensiero non ti viene restituito, quindi, sebbene il prezzo per token sia invariato, un carico di lavoro che veniva eseguito senza pensiero su Claude Opus 4.8 può produrre più token di output per richiesta su Claude Opus 5; consulta Controllo dei costi. Per preservare il vecchio comportamento, passa thinking: {type: "disabled"}, soggetto al limite di effort descritto nel punto successivo; nota che con il pensiero disabilitato il modello può occasionalmente emettere chiamate agli strumenti come testo semplice o includere tag XML interni nel suo output visibile, quindi preferisci livelli di effort più bassi con il pensiero abilitato dove puoi, e consulta Esecuzione con il pensiero disabilitato per le mitigazioni dove non puoi.

    La forma della risposta cambia di conseguenza. Con il pensiero attivo, una risposta può iniziare con uno o più blocchi thinking prima del primo blocco text e, poiché thinking.display ha come valore predefinito "omitted" su Claude Opus 5, questi blocchi arrivano con un campo thinking vuoto insieme alla loro signature. 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, si rompe su queste risposte. Seleziona invece i blocchi di contenuto in base al loro campo type: leggi text dai blocchi il cui type è "text" e dirama in base al tipo di blocco quando gestisci gli eventi dello stream. Per ricevere riepiloghi leggibili del pensiero invece di un campo thinking vuoto, imposta display: "summarized"; consulta Controllo della visualizzazione del pensiero.

    Se esegui un ciclo 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. Ritrasmetti il messaggio dell'assistente così come ricevuto invece di filtrarne i blocchi di contenuto per tipo o ricostruirlo: l'API rifiuta con un errore 400 i blocchi di pensiero modificati, riordinati o parzialmente eliminati. Consulta Preservare i blocchi di pensiero.

  2. La disabilitazione del pensiero è limitata all'effort high: Puoi ancora disattivare il pensiero con thinking: {type: "disabled"}, ma solo a un livello di effort pari a high o inferiore. Una richiesta che combina thinking: {type: "disabled"} con effort xhigh o max restituisce un errore 400. Claude Opus 4.8 accetta questa combinazione, quindi verifica le richieste che disabilitano il pensiero prima di migrare.

    Il controllo viene applicato a ogni richiesta: la configurazione di effort e pensiero di ogni richiesta viene validata in modo indipendente, quindi una richiesta che alza l'effort a xhigh o max mentre il pensiero è disabilitato viene rifiutata anche se le richieste precedenti nella conversazione erano state accettate.

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

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

    Dopo (Claude Opus 5), rimuovi il campo thinking per riabilitare il pensiero:

    client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    output_config={"effort": "xhigh"},  # thinking is on by default
    messages=[{"role": "user", "content": "..."}],
)

    oppure mantieni il pensiero disabilitato e abbassa l'effort:

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

Queste non sono obbligatorie ma miglioreranno la tua esperienza:

  1. Testa l'effort max per il lavoro in cui le capacità sono critiche: Claude Opus 5 supporta l'insieme completo dei livelli di effort (low, medium, high, xhigh, max). Dove la capacità massima conta più della spesa in token, testa l'effort max. Può offrire miglioramenti nelle attività più impegnative, ma può mostrare rendimenti decrescenti a fronte di un maggiore utilizzo di token e può essere incline a pensare troppo su quelle più semplici. Se esegui con effort xhigh o max, imposta un max_tokens ampio in modo che il modello abbia spazio per pensare e agire; inizia da 64k token e regola da lì.

  2. Considera i fallback automatici: Claude Opus 5 viene fornito con classificatori di sicurezza per la cybersecurity i cui rifiuti nella categoria cyber possono ricadere su Claude Opus 4.8. Per rieseguire automaticamente le richieste rifiutate su un altro modello, considera il parametro fallbacks con la modalità "default" (fallbacks: "default"), che seleziona un modello di fallback consigliato in base alla categoria del rifiuto invece di un elenco di modelli mantenuto manualmente. Il fallback lato server è in beta; la modalità "default" richiede l'header beta server-side-fallback-2026-07-01. Consulta Rifiuti e fallback.

  3. Metti in cache prompt più brevi: La lunghezza minima del prompt memorizzabile in cache su Claude Opus 5 è di 512 token, in calo rispetto ai 1.024 token di Claude Opus 4.8. I prompt che erano troppo brevi per essere messi in cache su Claude Opus 4.8 possono ora creare voci di cache, senza modifiche al codice. Consulta Cache dei prompt per i minimi per modello.

  4. Cambia gli strumenti a metà conversazione (beta): Puoi aggiungere o rimuovere strumenti tra i turni di una conversazione senza invalidare gli hit della cache dei prompt sui turni precedenti. Invia l'header beta mid-conversation-tool-changes-2026-07-01. Questo è utile per i carichi di lavoro agentici che espongono gli strumenti progressivamente o li ritirano man mano che un'attività avanza; senza di esso, un elenco di strumenti modificato invalida il prefisso in cache.

  5. Ricalibra i prompt su lunghezza e verbosità: Le risposte visibili predefinite e i deliverable scritti risultano più lunghi su Claude Opus 5 rispetto a Claude Opus 4.8, e abbassare l'effort riduce il volume di pensiero senza accorciare in modo affidabile la risposta visibile. Richiedi invece esplicitamente concisione o una lunghezza target. Consulta Lunghezza e verbosità delle risposte e Lunghezza dei deliverable scritti.

  6. Rimuovi le istruzioni di verifica ereditate e limita l'ambito: Claude Opus 5 verifica il proprio lavoro senza che gli venga detto, quindi rimuovi le istruzioni esplicite di verifica o autocontrollo ereditate da prompt calibrati per modelli precedenti; lasciarle causa un eccesso di verifica. Per attività circoscritte, limita esplicitamente l'ambito dell'attività. Nei framework multi-agente, fornisci indicazioni esplicite su quali scenari giustificano la delega oppure limita il numero di subagenti, perché Claude Opus 5 delega più facilmente rispetto ai modelli precedenti. Consulta Ambito dell'attività ed eccesso di verifica e Controllo della generazione di subagenti.

Checklist di migrazione

  • Aggiorna il nome del modello da claude-opus-4-8 a claude-opus-5.
  • Rivedi i carichi di lavoro che venivano eseguiti senza un campo thinking: su Claude Opus 5 vengono eseguiti con il pensiero. Rivedi max_tokens, che rimane un limite rigido sull'output totale (pensiero più testo della risposta), oppure passa thinking: {type: "disabled"} con effort high o inferiore per preservare il vecchio comportamento. Se disabiliti il pensiero, consulta Esecuzione con il pensiero disabilitato per gli artefatti di output che possono comparire e le relative mitigazioni tramite prompting.
  • Aggiorna il parsing delle risposte che legge il contenuto per posizione, come content[0].text o un gestore di stream che presume che il primo blocco di contenuto sia testo: con il pensiero attivo, i blocchi thinking arrivano prima dei blocchi text. Seleziona invece i blocchi di contenuto per type.
  • Se esegui un ciclo di uso degli strumenti, ripassa i blocchi thinking completi e non modificati quando restituisci i risultati degli strumenti; i blocchi modificati restituiscono un errore 400. Consulta Preservare i blocchi di pensiero.
  • Verifica che qualsiasi codice che analizza il campo thinking lo tratti solo come testo di visualizzazione. thinking.display ha come valore predefinito "omitted" su Claude Opus 5, come su Claude Opus 4.8, quindi i blocchi di pensiero arrivano con un campo thinking vuoto; imposta display: "summarized" per ricevere riepiloghi leggibili. Consulta Controllo della visualizzazione del pensiero.
  • Verifica le richieste che disabilitano il pensiero: thinking: {type: "disabled"} con effort xhigh o max restituisce un errore 400, applicato a ogni richiesta. Riabilita il pensiero o abbassa l'effort a high o inferiore.
  • Rivaluta la tua impostazione di effort: esegui una nuova esplorazione dei livelli di effort sulle tue eval invece di riportare un'impostazione calibrata per un modello precedente. Vale la pena testare gli effort low e medium come controlli di costo e latenza, e testa l'effort max dove la capacità massima conta più della spesa in token. Se esegui con effort xhigh o max, alza max_tokens ad almeno 64k come punto di partenza.
  • Rivedi i prompt vicini al minimo per la cache: i prompt di 512 token o più possono ora creare voci di cache, in calo rispetto ai 1.024 token di Claude Opus 4.8.
  • Gestisci stop_reason: "refusal" e considera fallbacks: "default" (beta) per rieseguire automaticamente le richieste rifiutate su un modello di fallback consigliato.
  • Se la tua organizzazione ha un impegno Priority Tier, pianifica la capacità separatamente: Priority Tier non è supportato su Claude Opus 5, mentre Claude Opus 4.8 lo mantiene.
  • Per i carichi di lavoro agentici, considera i budget di attività (beta) e le modifiche degli strumenti a metà conversazione (beta).
  • Ricalibra i prompt su lunghezza e verbosità: le risposte visibili predefinite e i deliverable scritti risultano più lunghi su Claude Opus 5, e abbassare l'effort riduce il volume di pensiero senza accorciare in modo affidabile la risposta visibile. Richiedi esplicitamente concisione o una lunghezza target. Consulta Lunghezza e verbosità delle risposte e Lunghezza dei deliverable scritti.
  • Rimuovi le istruzioni di verifica e autocontrollo ereditate da prompt calibrati per modelli precedenti (causano un eccesso di verifica su Claude Opus 5), limita esplicitamente l'ambito dell'attività per attività circoscritte e, nei framework multi-agente, orienta o limita la delega ai subagenti. Consulta Ambito dell'attività ed eccesso di verifica e Controllo della generazione di subagenti.
  • Ristabilisci la baseline di costo e latenza sui tuoi carichi di lavoro. Il prezzo per token è invariato rispetto a Claude Opus 4.8, ma i token di pensiero vengono fatturati come token di output, quindi i carichi di lavoro che venivano eseguiti senza pensiero possono produrre più token di output per richiesta.

Migrazione a Claude Opus 5 da Claude Opus 4.7

Claude Opus 5 dovrebbe avere ottime prestazioni immediate sui prompt e sulle eval esistenti di Claude Opus 4.7, allo stesso prezzo di $5 USD per milione di token di input e $25 USD per milione di token di output. Supporta lo stesso insieme di funzionalità di Claude Opus 4.7, tra cui la finestra di contesto da 1M di token, 128k token di output massimi, il pensiero adattivo, la cache dei prompt, l'elaborazione batch, la Files API, il supporto PDF, la visione e gli strumenti lato server e lato client, con due eccezioni: web fetch non è disponibile su Claude Opus 5 e Priority Tier non è supportato su Claude Opus 5. Aggiunge inoltre i messaggi di sistema a metà conversazione e documenta pubblicamente i dettagli di arresto per rifiuto. Sulla Claude API e su Google Cloud, Claude Opus 5 supporta anche il computer use come toolset stabile computer_toolset_20260801 e lo strumento browser use per attività all'interno di pagine web, nessuno dei quali è supportato da Claude Opus 4.7; le integrazioni esistenti sulla versione precedente computer_20251124 continuano a funzionare invariate su entrambi i modelli. Per aggiornare un'integrazione esistente, consulta Migrare da computer_20251124.

Aggiorna il nome del modello

# Migrazione a Opus
model = "claude-opus-4-7"  # Before
model = "claude-opus-5"  # After

Modifiche di rilievo

  1. Pensiero attivo per impostazione predefinita: Su Claude Opus 4.7, le richieste senza un campo thinking vengono eseguite senza pensiero; su Claude Opus 5, le stesse richieste vengono eseguite con il pensiero adattivo. max_tokens rimane un limite rigido sull'output totale, pensiero più testo della risposta, quindi rivedilo per i carichi di lavoro che venivano eseguiti senza pensiero su Claude Opus 4.7. I token di pensiero vengono fatturati come token di output anche quando il testo del pensiero non ti viene restituito, quindi, sebbene il prezzo per token sia invariato, un carico di lavoro che veniva eseguito senza pensiero su Claude Opus 4.7 può produrre più token di output per richiesta su Claude Opus 5; consulta Controllo dei costi. Per preservare il vecchio comportamento, passa thinking: {type: "disabled"}, soggetto al limite di effort descritto nel punto successivo; nota che con il pensiero disabilitato il modello può occasionalmente emettere chiamate agli strumenti come testo semplice o includere tag XML interni nel suo output visibile, quindi preferisci livelli di effort più bassi con il pensiero abilitato dove puoi, e consulta Esecuzione con il pensiero disabilitato per le mitigazioni dove non puoi.

    La forma della risposta cambia di conseguenza. Con il pensiero attivo, una risposta può iniziare con uno o più blocchi thinking prima del primo blocco text e, poiché thinking.display ha come valore predefinito "omitted" su Claude Opus 5, questi blocchi arrivano con un campo thinking vuoto insieme alla loro signature. 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, si rompe su queste risposte. Seleziona invece i blocchi di contenuto in base al loro campo type: leggi text dai blocchi il cui type è "text" e dirama in base al tipo di blocco quando gestisci gli eventi dello stream. Per ricevere riepiloghi leggibili del pensiero invece di un campo thinking vuoto, imposta display: "summarized"; consulta Controllo della visualizzazione del pensiero.

    Se esegui un ciclo 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. Ritrasmetti il messaggio dell'assistente così come ricevuto invece di filtrarne i blocchi di contenuto per tipo o ricostruirlo: l'API rifiuta con un errore 400 i blocchi di pensiero modificati, riordinati o parzialmente eliminati. Consulta Preservare i blocchi di pensiero.

  2. La disabilitazione del pensiero è limitata all'effort high: Puoi disattivare il pensiero con thinking: {type: "disabled"}, ma solo a un livello di effort pari a high o inferiore. Una richiesta che combina thinking: {type: "disabled"} con effort xhigh o max restituisce un errore 400. Claude Opus 4.7 accetta questa combinazione, quindi verifica le richieste che disabilitano il pensiero prima di migrare.

    Il controllo viene applicato a ogni richiesta: la configurazione di effort e pensiero di ogni richiesta viene validata in modo indipendente, quindi una richiesta che alza l'effort a xhigh o max mentre il pensiero è disabilitato viene rifiutata anche se le richieste precedenti nella conversazione erano state accettate.

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

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

    Dopo (Claude Opus 5), rimuovi il campo thinking per eseguire con il pensiero:

    client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    output_config={"effort": "xhigh"},  # thinking is on by default
    messages=[{"role": "user", "content": "..."}],
)

    oppure mantieni il pensiero disabilitato e abbassa l'effort:

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

Cosa è cambiato

I seguenti punti non sono modifiche di rilievo; descrivono differenze di comportamento che vale la pena verificare dopo aver sostituito l'ID del modello.

  1. Parametri di campionamento (invariati): Impostare temperature, top_p o top_k su un valore non predefinito restituisce un errore 400 su Claude Opus 5, come su Claude Opus 4.7. La maggior parte degli SDK definisce ancora questi campi per compatibilità con i modelli precedenti, quindi il codice che li imposta supera il controllo dei tipi anche se l'API rifiuta la richiesta. L'SDK Python (v1.0 e successive) non li definisce e passarli genera un TypeError. Se hai rimosso questi parametri durante la migrazione a Opus 4.7, non sono necessarie ulteriori modifiche.

  2. Il valore predefinito di effort è high: Il valore predefinito del parametro effort su Claude Opus 5 è high sulla Claude API e in Claude Code. Se imposti già l'effort esplicitamente, la tua impostazione resta invariata.

  3. Livelli di effort ricalibrati: L'allocazione di token dietro ciascun livello di effort cambia su Claude Opus 5 rispetto a Claude Opus 4.7, e Claude Opus 5 supporta l'insieme completo dei livelli di effort (low, medium, high, xhigh, max). Esegui una nuova esplorazione dei livelli di effort sulle tue eval invece di riportare un'impostazione calibrata per Claude Opus 4.7. Vale la pena testare gli effort low e medium come controlli di costo e latenza, e testa l'effort max dove la capacità massima conta più della spesa in token. Se esegui con effort xhigh o max, imposta un max_tokens ampio in modo che il modello abbia spazio per pensare e agire; inizia da 64k token e regola da lì. Consulta Effort.

  4. La finestra di contesto da 1M è predefinita: Claude Opus 5 serve l'intera finestra di contesto da 1M di token per impostazione predefinita, senza header beta e senza sovrapprezzo per il contesto lungo. Se il tuo client passa un header beta per la finestra di contesto per compatibilità con modelli più vecchi, puoi rimuoverlo su Claude Opus 5.

  5. Messaggi di sistema a metà conversazione: Claude Opus 5 accetta messaggi role: "system" immediatamente dopo un turno utente nell'array messages (soggetti alle 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.

  6. Dettagli di arresto per rifiuto: L'oggetto stop_details nelle risposte di rifiuto (disponibile da Claude Opus 4.7) è ora documentato pubblicamente. Quando il modello declina una richiesta, identifica la categoria del rifiuto, in aggiunta allo stop reason refusal esistente. Non è richiesto alcun header beta e non è possibile disattivarlo. Consulta Gestione degli stop reason.

  7. Minimo per la cache dei prompt più basso: La lunghezza minima del prompt memorizzabile in cache su Claude Opus 5 è di 512 token, inferiore a quella di Claude Opus 4.7. I prompt che erano troppo brevi per essere messi in cache su Claude Opus 4.7 possono ora creare voci di cache, senza modifiche al codice. Consulta Cache dei prompt per i minimi per modello.

  8. Modalità veloce: Claude Opus 5 supporta la modalità veloce (anteprima di ricerca); la modalità veloce non è disponibile su Claude Opus 4.7, dove le richieste con speed: "fast" restituiscono un errore. Il parametro speed: "fast" e l'header beta fast-mode-2026-02-01 funzionano invariati su Claude Opus 5.

Queste non sono obbligatorie ma miglioreranno la tua esperienza:

  1. Considera i fallback automatici: Claude Opus 5 viene fornito con classificatori di sicurezza per la cybersecurity i cui rifiuti nella categoria cyber possono ricadere su Claude Opus 4.8. Per rieseguire automaticamente le richieste rifiutate su un altro modello, considera il parametro fallbacks con la modalità "default" (fallbacks: "default"), che seleziona un modello di fallback consigliato in base alla categoria del rifiuto invece di un elenco di modelli mantenuto manualmente. Il fallback lato server è in beta; la modalità "default" richiede l'header beta server-side-fallback-2026-07-01. Consulta Rifiuti e fallback.

  2. Cambia gli strumenti a metà conversazione (beta): Puoi aggiungere o rimuovere strumenti tra i turni di una conversazione senza invalidare gli hit della cache dei prompt sui turni precedenti. Invia l'header beta mid-conversation-tool-changes-2026-07-01. Questo è utile per i carichi di lavoro agentici che espongono gli strumenti progressivamente o li ritirano man mano che un'attività avanza; senza di esso, un elenco di strumenti modificato invalida il prefisso in cache.

  3. Ricalibra i prompt su lunghezza e verbosità: Le risposte visibili predefinite e i deliverable scritti risultano più lunghi su Claude Opus 5 rispetto ai modelli Opus precedenti, e abbassare l'effort riduce il volume di pensiero senza accorciare in modo affidabile la risposta visibile. Richiedi invece esplicitamente concisione o una lunghezza target. Consulta Lunghezza e verbosità delle risposte e Lunghezza dei deliverable scritti.

  4. Rimuovi le istruzioni di verifica ereditate e limita l'ambito: Claude Opus 5 verifica il proprio lavoro senza che gli venga detto, quindi rimuovi le istruzioni esplicite di verifica o autocontrollo ereditate da prompt calibrati per modelli precedenti; lasciarle causa un eccesso di verifica. Per attività circoscritte, limita esplicitamente l'ambito dell'attività. Nei framework multi-agente, fornisci indicazioni esplicite su quali scenari giustificano la delega oppure limita il numero di subagenti, perché Claude Opus 5 delega più facilmente rispetto ai modelli precedenti. Consulta Ambito dell'attività ed eccesso di verifica e Controllo della generazione di subagenti.

Checklist di migrazione

  • Aggiorna il nome del modello da claude-opus-4-7 a claude-opus-5 (o aggiorna gli alias).
  • Rivedi i carichi di lavoro che venivano eseguiti senza un campo thinking: su Claude Opus 5 vengono eseguiti con il pensiero. Rivedi max_tokens, che rimane un limite rigido sull'output totale (pensiero più testo della risposta), oppure passa thinking: {type: "disabled"} con effort high o inferiore per preservare il vecchio comportamento. Se disabiliti il pensiero, consulta Esecuzione con il pensiero disabilitato per gli artefatti di output che possono comparire e le relative mitigazioni tramite prompting.
  • Aggiorna il parsing delle risposte che legge il contenuto per posizione, come content[0].text o un gestore di stream che presume che il primo blocco di contenuto sia testo: con il pensiero attivo, i blocchi thinking arrivano prima dei blocchi text. Seleziona invece i blocchi di contenuto per type.
  • Se esegui un ciclo di uso degli strumenti, ripassa i blocchi thinking completi e non modificati quando restituisci i risultati degli strumenti; i blocchi modificati restituiscono un errore 400. Consulta Preservare i blocchi di pensiero.
  • Verifica che qualsiasi codice che analizza il campo thinking lo tratti solo come testo di visualizzazione. thinking.display ha come valore predefinito "omitted" su Claude Opus 5, come su Claude Opus 4.7, quindi i blocchi di pensiero arrivano con un campo thinking vuoto; imposta display: "summarized" per ricevere riepiloghi leggibili. Consulta Controllo della visualizzazione del pensiero.
  • Verifica le richieste che disabilitano il pensiero: thinking: {type: "disabled"} con effort xhigh o max restituisce un errore 400, applicato a ogni richiesta. Riabilita il pensiero o abbassa l'effort a high o inferiore.
  • Se hai rimosso i parametri di campionamento durante la migrazione a Opus 4.7, non è necessaria alcuna azione. Se li hai aggiunti di nuovo con un percorso di retry su 400, rimuovi quel percorso di retry.
  • Rivaluta la tua impostazione di effort: esegui una nuova esplorazione dei livelli di effort sulle tue eval invece di riportare un'impostazione calibrata per Claude Opus 4.7. Testa gli effort low e medium come controlli di costo e latenza, e l'effort max dove la capacità massima conta più della spesa in token. Se esegui con effort xhigh o max, alza max_tokens ad almeno 64k come punto di partenza.
  • Rimuovi qualsiasi header beta per la finestra di contesto. La finestra di contesto da 1M è predefinita sulla Claude API, su Amazon Bedrock, Google Cloud e Microsoft Foundry.
  • Se ricostruisci la cronologia della conversazione per aggiornare le istruzioni, considera di passare a un messaggio di sistema a metà conversazione per preservare gli hit della cache dei prompt.
  • Verifica che la tua gestione degli stop reason legga stop_details sui rifiuti (disponibile da Claude Opus 4.7; ora documentato pubblicamente) e considera fallbacks: "default" (beta) per rieseguire automaticamente le richieste rifiutate su un modello di fallback consigliato.
  • Rivedi i prompt vicini al minimo per la cache: i prompt di 512 token o più possono ora creare voci di cache.
  • Se usi web fetch, pianifica un'alternativa: non è disponibile su Claude Opus 5.
  • Se la tua organizzazione ha un impegno Priority Tier, nota che Priority Tier non è supportato su Claude Opus 5.
  • Se usavi la modalità veloce su Claude Opus 4.7, non sono necessarie modifiche alle richieste oltre all'ID del modello: speed: "fast" e l'header beta fast-mode-2026-02-01 funzionano invariati su Claude Opus 5.
  • Per i carichi di lavoro agentici, considera i budget di attività (beta) e le modifiche degli strumenti a metà conversazione (beta).
  • Ricalibra i prompt su lunghezza e verbosità e rimuovi le istruzioni di verifica e autocontrollo ereditate da prompt calibrati per modelli precedenti.
  • Ristabilisci la baseline di costo e latenza al livello di effort scelto. Il prezzo per token è invariato rispetto a Claude Opus 4.7, ma i token di pensiero vengono fatturati come token di output, quindi i carichi di lavoro che venivano eseguiti senza pensiero possono produrre più token di output per richiesta.

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

Claude Opus 5 dovrebbe avere ottime prestazioni immediate sui prompt e sulle eval esistenti di Claude Opus 4.6 allo stesso prezzo, ma ci sono alcune modifiche comportamentali e dell'API che vale la pena conoscere durante la migrazione. La maggior parte di queste modifiche è entrata in vigore con Claude Opus 4.7; altre due, il pensiero attivo per impostazione predefinita e un limite di effort sulla disabilitazione del pensiero, entrano in vigore con Claude Opus 5. Tutte sono trattate in questa sezione, che è quindi completa per il codice proveniente direttamente da Claude Opus 4.6. Claude Opus 5 supporta lo stesso insieme di funzionalità di Claude Opus 4.6, tra cui:

Due eccezioni: web fetch non è disponibile su Claude Opus 5 e Priority Tier non è supportato su Claude Opus 5. Sulla Claude API e su Google Cloud, Claude Opus 5 supporta anche il computer use come toolset stabile computer_toolset_20260801 e lo strumento browser use per attività all'interno di pagine web, nessuno dei quali è supportato da Claude Opus 4.6 o dai modelli Opus precedenti; le integrazioni esistenti sulla versione precedente computer_20251124 continuano a funzionare invariate su Claude Opus 5. Per aggiornare un'integrazione esistente, consulta Migrare da computer_20251124.

Aggiorna il nome del modello

# Migrazione a Opus
model = "claude-opus-4-6"  # Before
model = "claude-opus-5"  # After

Modifiche che causano interruzioni

  1. Pensiero esteso rimosso: thinking: {type: "enabled", budget_tokens: N} non è più supportato su Claude Opus 4.7 o modelli successivi e restituisce un errore 400. Passa all'adaptive thinking (pensiero adattivo) (thinking: {type: "adaptive"}) e usa il parametro effort per controllare la profondità del pensiero. Su Claude Opus 5, il pensiero adattivo è attivo per impostazione predefinita: thinking: {type: "adaptive"} è valido ed equivalente a omettere del tutto il campo thinking (vedi il punto successivo).

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

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

    Il pensiero adattivo è orientabile tramite il prompting e il parametro effort; vedi Scegliere un livello di effort.

  2. Pensiero attivo per impostazione predefinita: Su Claude Opus 4.6 e Claude Opus 4.7, le richieste senza un campo thinking vengono eseguite senza pensiero; su Claude Opus 5, le stesse richieste vengono eseguite con pensiero adattivo. max_tokens rimane un limite rigido sull'output totale, pensiero più testo della risposta, quindi rivedilo per i carichi di lavoro che venivano eseguiti senza pensiero. I token di pensiero vengono fatturati come token di output anche quando il testo del pensiero non ti viene restituito, quindi, sebbene il prezzo per token sia invariato, un carico di lavoro che veniva eseguito senza pensiero può produrre più token di output per richiesta su Claude Opus 5; vedi Controllo dei costi. Per preservare il vecchio comportamento, passa thinking: {type: "disabled"}, soggetto al limite di effort del punto successivo; nota che con il pensiero disabilitato il modello può occasionalmente emettere chiamate agli strumenti come testo semplice o includere tag XML interni nel suo output visibile, quindi preferisci livelli di effort più bassi con il pensiero abilitato dove puoi, e vedi Esecuzione con il pensiero disabilitato per le mitigazioni dove non puoi.

    La forma della risposta cambia di conseguenza. Con il pensiero attivo, una risposta può iniziare con uno o più blocchi thinking prima del primo blocco text, e poiché il contenuto del pensiero è omesso per impostazione predefinita su Claude Opus 5 (punto 5 di questo elenco), quei blocchi arrivano con un campo thinking vuoto insieme alla loro signature. 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, si rompe su queste risposte. Seleziona invece i blocchi di contenuto in base al loro campo type: leggi text dai blocchi il cui type è "text", e dirama in base al tipo di blocco quando gestisci gli eventi dello stream.

    Se esegui un ciclo 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 anziché filtrarne i blocchi di contenuto per tipo o ricostruirlo: l'API rifiuta i blocchi di pensiero modificati, riordinati o parzialmente eliminati con un errore 400. Vedi Preservare i blocchi di pensiero.

  3. La disabilitazione del pensiero è limitata all'effort high: Puoi disattivare il pensiero con thinking: {type: "disabled"}, ma solo a un livello di effort pari a high o inferiore. Una richiesta che combina thinking: {type: "disabled"} con effort xhigh o max restituisce un errore 400 su Claude Opus 5, applicato a ogni richiesta. Verifica le richieste che disabilitano il pensiero prima di migrare: riabilita il pensiero o abbassa l'effort a high o inferiore.

  4. Parametri di campionamento rimossi: Impostare temperature, top_p o top_k su qualsiasi valore non predefinito su Claude Opus 4.7 o modelli successivi, incluso Claude Opus 5, restituisce un errore 400. Il Python SDK (v1.0 e successive) non li definisce, e passarli genera un TypeError. Il percorso di migrazione più sicuro è omettere del tutto questi parametri dai payload delle richieste. Il prompting è il modo consigliato per guidare il comportamento del modello su Claude Opus 5. Se usavi temperature = 0 per il determinismo, nota che non ha mai garantito output identici sui modelli precedenti.

  5. Contenuto del pensiero omesso per impostazione predefinita: I blocchi di pensiero appaiono ancora nello stream della risposta su Claude Opus 4.7 e modelli successivi, ma il loro campo thinking è vuoto a meno che tu non lo richieda esplicitamente. Si tratta di una modifica silenziosa rispetto a Claude Opus 4.6, dove l'impostazione predefinita era restituire il testo del pensiero riassunto. Per ripristinare il contenuto del pensiero riassunto, imposta thinking.display su "summarized":

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

    L'impostazione predefinita è "omitted" su Claude Opus 4.7 e modelli successivi. Se il tuo prodotto trasmette in streaming il ragionamento agli utenti, la nuova impostazione predefinita appare come una lunga pausa prima che inizi l'output; imposta display: "summarized" per ripristinare l'avanzamento visibile durante il pensiero. Vedi Controllare la visualizzazione del pensiero per i dettagli.

  6. Conteggio dei token aggiornato: Claude Opus 4.7 ha introdotto un nuovo tokenizer, che anche i modelli Opus successivi, incluso Claude Opus 5, utilizzano. Contribuisce a prestazioni migliorate su un'ampia gamma di attività, e può usare all'incirca da 1x a 1,35x token in più nell'elaborazione del testo rispetto ai modelli precedenti a Claude Opus 4.7 (fino a ~35% in più, variabile in base al contenuto).

    /v1/messages/count_tokens restituisce un numero di token diverso per Claude Opus 5 rispetto a quanto faceva per Claude Opus 4.6. L'efficienza dei token può variare in base alla forma del carico di lavoro.

    Gli interventi di prompting, task_budget ed effort possono aiutare a controllare i costi e garantire un uso appropriato dei token. Questi controlli possono comportare un compromesso con l'intelligenza del modello. Aggiorna i tuoi parametri max_tokens per dare margine aggiuntivo, inclusi i trigger di compattazione. Claude Opus 5 fornisce una "context window" (finestra di contesto) da 1M al prezzo API standard senza sovrapprezzo per il contesto lungo.

  7. Rimozione del prefill (ereditata da Opus 4.6): Il prefill dei messaggi dell'assistente restituisce un errore 400 su Claude Opus 4.7 e modelli successivi, incluso Claude Opus 5. Usa invece gli output strutturati, le istruzioni nel prompt di sistema o output_config.format.

Scegliere un livello di effort

Il parametro effort ti consente di regolare l'intelligenza di Claude rispetto alla spesa in token, scambiando capacità per maggiore velocità e costi inferiori. Claude Opus 5 supporta l'intero insieme di livelli di effort e ha come impostazione predefinita high. Esegui una nuova esplorazione dei livelli di effort sulle tue valutazioni anziché riportare un'impostazione calibrata per un modello precedente:

  • max: Può offrire vantaggi sulle attività più impegnative ma può mostrare rendimenti decrescenti dall'aumento dell'uso di token e può essere incline a pensare troppo su quelle più semplici. Testalo dove la massima capacità conta più della spesa in token.
  • xhigh: Capacità estesa per lavori agentici e di programmazione di lunga durata che richiedono più profondità rispetto all'impostazione predefinita.
  • high: L'impostazione predefinita. Bilancia uso dei token e intelligenza per la maggior parte delle attività.
  • medium: Riduzione rispetto all'impostazione predefinita per risparmiare sui costi, vale la pena testarla come controllo di costi e latenza.
  • low: Il più efficiente. Riservalo per attività brevi e circoscritte e carichi di lavoro sensibili alla latenza.

Se esegui con effort xhigh o max, imposta un max_tokens ampio in modo che il modello abbia spazio per pensare e agire; inizia da 64k token e regola da lì. L'effort è più importante per questo modello che per qualsiasi Opus precedente. Sperimentalo attivamente quando esegui l'aggiornamento.

Modifiche di comportamento

Claude Opus 4.7 ha introdotto diverse differenze comportamentali rispetto a Claude Opus 4.6 che non sono modifiche che causano interruzioni dell'API ma possono richiedere aggiornamenti dei prompt o la rimozione di scaffolding. Si trasferiscono a Claude Opus 5, con gli aggiustamenti indicati in questo elenco.

  1. La lunghezza della risposta varia in base al caso d'uso: Claude Opus 4.7 calibra la lunghezza della risposta in base a quanto giudica complessa l'attività, anziché adottare per impostazione predefinita una verbosità fissa. Questo di solito significa risposte più brevi su semplici ricerche e molto più lunghe su analisi aperte.

    Se il tuo prodotto dipende da un certo stile o verbosità dell'output, potresti dover regolare i tuoi prompt. Ad esempio, per diminuire la verbosità, aggiungi: "Fornisci risposte concise e mirate. Salta il contesto non essenziale e mantieni gli esempi al minimo." Se noti tipi specifici di spiegazioni eccessive, aggiungi istruzioni mirate nel tuo prompt per prevenirle.

    Gli esempi positivi che mostrano come Claude può comunicare con il livello appropriato di concisione tendono a essere più efficaci degli esempi negativi o delle istruzioni che dicono al modello cosa non fare. Su Claude Opus 5, le risposte visibili predefinite e i documenti scritti prodotti sono più lunghi rispetto ai modelli Opus precedenti, e abbassare l'effort riduce il volume del pensiero senza accorciare in modo affidabile la risposta visibile; richiedi esplicitamente nel prompt la concisione o una lunghezza target. Vedi Lunghezza della risposta e verbosità.

  2. Esecuzione delle istruzioni più letterale: Claude Opus 4.7 interpreta i prompt in modo più letterale ed esplicito rispetto a Claude Opus 4.6, in particolare ai livelli di effort più bassi. Non generalizza silenziosamente un'istruzione da un elemento a un altro, e non deduce richieste che non hai fatto. Il vantaggio di questa letteralità è la precisione e meno dispersione. In generale funziona meglio per i casi d'uso API con prompt accuratamente calibrati, estrazione strutturata e pipeline in cui desideri un comportamento prevedibile. Una revisione dei prompt e dell'harness può essere particolarmente utile per la migrazione a Claude Opus 5.

  3. Tono più diretto: Come con qualsiasi nuovo modello, lo stile della prosa nella scrittura di lunga forma può cambiare. Claude Opus 4.7 è più diretto e deciso nelle opinioni, con meno formulazioni orientate alla validazione e meno emoji rispetto allo stile più caloroso di Claude Opus 4.6. Se il tuo prodotto si basa su una voce specifica, rivaluta i prompt di stile rispetto alla nuova baseline.

  4. Aggiornamenti di avanzamento integrati nelle tracce agentiche: Claude Opus 4.7 fornisce aggiornamenti più regolari e di qualità superiore all'utente durante le lunghe tracce agentiche. Se hai aggiunto scaffolding per forzare messaggi di stato intermedi ("Dopo ogni 3 chiamate agli strumenti, riassumi l'avanzamento"), prova a rimuoverlo. Se trovi che la lunghezza o i contenuti degli aggiornamenti rivolti all'utente di Claude Opus 4.7 non sono ben calibrati per il tuo caso d'uso, descrivi esplicitamente nel prompt come dovrebbero essere questi aggiornamenti e fornisci esempi.

  5. Generazione di subagenti modificata: Claude Opus 4.7 tende a generare meno subagenti per impostazione predefinita rispetto a Claude Opus 4.6, mentre Claude Opus 5 delega ai subagenti più prontamente rispetto ai modelli precedenti. Il comportamento è orientabile tramite il prompting in entrambe le direzioni; fornisci indicazioni esplicite su quando i subagenti sono desiderabili, o limita il numero di subagenti. Vedi Controllare la generazione di subagenti.

  6. Calibrazione dell'effort più rigorosa: Cambiando in modo significativo rispetto a Claude Opus 4.6, Claude Opus 4.7 rispetta rigorosamente i livelli di effort, specialmente nella fascia bassa. A low e medium, il modello circoscrive il suo lavoro a ciò che è stato chiesto anziché fare più di quanto richiesto.

    Questo è positivo per latenza e costi, ma su attività moderatamente complesse eseguite con effort low c'è un certo rischio di pensare troppo poco. Se osservi un ragionamento superficiale su problemi complessi, alza l'effort a high o xhigh anziché aggirare il problema con il prompting.

    Se devi mantenere l'effort a low per la latenza, aggiungi indicazioni mirate: "Questa attività comporta un ragionamento in più passaggi. Rifletti attentamente sul problema prima di rispondere." Vedi Livelli di effort consigliati per Claude Opus 4.7.

  7. Meno chiamate agli strumenti per impostazione predefinita: Claude Opus 4.7 ha la tendenza a usare gli strumenti meno spesso rispetto a Claude Opus 4.6 e a usare di più il ragionamento. Questo produce risultati migliori nella maggior parte dei casi.

    Per aumentare l'uso degli strumenti, alza l'impostazione di effort. Le impostazioni di effort high o xhigh mostrano un uso degli strumenti sostanzialmente maggiore nella ricerca agentica e nella programmazione. Puoi anche modificare il tuo prompt per istruire esplicitamente il modello su quando e come usare correttamente i suoi strumenti.

  8. Salvaguardie di cybersecurity in tempo reale: Novità aggiunta in Claude Opus 4.7, le richieste che coinvolgono argomenti proibiti o ad alto rischio possono portare a rifiuti. Per lavori di sicurezza legittimi come penetration testing, ricerca di vulnerabilità o red-teaming, fai domanda al Cyber Verification Program per richiedere restrizioni ridotte. Il percorso di candidatura dipende da come accedi a Claude.

  9. 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 sblocca vantaggi sui carichi di lavoro ad alta intensità visiva ed è particolarmente prezioso per computer use, comprensione di screenshot e analisi di 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.

Queste non sono obbligatorie ma miglioreranno la tua esperienza:

  1. Rivaluta max_tokens: Poiché lo stesso testo produce un conteggio di token più alto su Claude Opus 4.7 e modelli successivi, aggiorna i tuoi parametri max_tokens per dare margine aggiuntivo, inclusi i trigger di compattazione. Gli interventi di prompting, task_budget ed effort possono aiutare a controllare i costi e garantire un uso appropriato dei token.

  2. Verifica le aspettative sul conteggio dei token: Qualsiasi percorso di codice che stima i token lato client o presuppone un rapporto fisso token-caratteri dovrebbe essere ritestato rispetto a Claude Opus 5. Usa l'endpoint di conteggio dei token per verificare.

  3. Adotta i task budget (beta): Claude Opus 4.7 introduce i task budget. Questi budget ti consentono di informare Claude su quanti token ha a disposizione per un intero ciclo agentico, inclusi pensiero, chiamate agli strumenti, risultati degli strumenti e output finale. Il modello vede un conto alla rovescia progressivo e lo usa per dare priorità al lavoro e completare l'attività in modo ordinato man mano che il budget viene consumato. Per usarli, imposta l'header beta task-budgets-2026-03-13 e aggiungi quanto segue alla tua configurazione di output:

    output_config = {
    "effort": "high",
    "task_budget": {"type": "tokens", "total": 128000},
}

    Potresti dover sperimentare con diversi task budget per il tuo caso d'uso. Se al modello viene assegnato un task budget troppo restrittivo, potrebbe completare l'attività in modo meno approfondito, citando il suo budget come vincolo.

    Per attività agentiche aperte in cui la qualità conta più della velocità, non impostare un task budget. Riserva i task budget per i carichi di lavoro in cui hai bisogno che il modello circoscriva il suo lavoro a una dotazione di token. Il valore minimo per un task budget è 20k token.

    Un task budget non è un limite rigido; è un suggerimento di cui il modello è consapevole. Differisce da max_tokens:

    • task_budget: un limite indicativo sull'intero ciclo agentico. Il modello lo vede e lo usa per regolare il proprio ritmo.
    • max_tokens: un tetto rigido per richiesta sui token generati. Non viene passato al modello, quindi il modello non ne è consapevole.

    Usa task_budget quando vuoi che il modello si automoderi, e max_tokens come tetto rigido per limitare l'uso.

  4. Imposta un max_tokens ampio con effort max o xhigh: Se esegui Claude Opus 4.7 o un modello successivo con effort max o xhigh, imposta un budget massimo di token di output ampio in modo che il modello abbia spazio per pensare e agire attraverso i suoi subagenti e le chiamate agli strumenti. Inizia da 64k token e regola da lì.

  5. Riduci la risoluzione delle immagini se l'alta risoluzione non è necessaria: Claude Opus 4.7 e modelli successivi supportano immagini fino a 2576px / 3,75MP. Le immagini ad alta risoluzione usano più token. Se la fedeltà aggiuntiva dell'immagine non è necessaria, riduci la risoluzione delle immagini prima di inviarle a Claude per evitare aumenti nell'uso dei token. Vedi Immagini e visione.

  6. Considera i fallback automatici: Claude Opus 5 viene fornito con classificatori di sicurezza per la cybersecurity i cui rifiuti nella categoria cyber possono ricadere su Claude Opus 4.8. Per rieseguire automaticamente le richieste rifiutate su un altro modello, considera il parametro fallbacks con la modalità "default" (fallbacks: "default"), che seleziona un modello di fallback consigliato in base alla categoria del rifiuto anziché un elenco di modelli mantenuto manualmente. Il fallback lato server è in beta; la modalità "default" richiede l'header beta server-side-fallback-2026-07-01. Vedi Rifiuti e fallback.

  7. Metti in cache prompt più brevi: La lunghezza minima del prompt memorizzabile in cache su Claude Opus 5 è di 512 token, inferiore rispetto ai modelli Opus precedenti. I prompt che erano troppo brevi per essere messi in cache possono ora creare voci di cache, senza modifiche al codice richieste. Vedi Cache dei prompt per i minimi per modello.

  8. Cambia gli strumenti a metà conversazione (beta): Puoi aggiungere o rimuovere strumenti tra i turni di una conversazione senza invalidare gli hit della cache dei prompt sui turni precedenti. Invia l'header beta mid-conversation-tool-changes-2026-07-01. Questo è utile per i carichi di lavoro agentici che espongono gli strumenti progressivamente o li ritirano man mano che un'attività avanza; senza di esso, un elenco di strumenti modificato invalida il prefisso in cache.

  9. Rimuovi le istruzioni di verifica ereditate e vincola l'ambito: Claude Opus 5 verifica il proprio lavoro senza che gli venga detto, quindi rimuovi le istruzioni esplicite di verifica o autocontrollo ereditate da prompt calibrati per modelli precedenti; lasciarle causa una verifica eccessiva. Per attività ristrette, vincola esplicitamente l'ambito dell'attività. Vedi Ambito dell'attività e verifica eccessiva.

Checklist di migrazione

  • Aggiorna il nome del modello da claude-opus-4-6 a claude-opus-5 (o aggiorna gli alias).
  • 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 del tutto il campo thinking; il pensiero adattivo è attivo per impostazione predefinita su Claude Opus 5.
  • Rivedi i carichi di lavoro che venivano eseguiti senza un campo thinking: vengono eseguiti con il pensiero su Claude Opus 5. Rivedi max_tokens, che rimane un limite rigido sull'output totale (pensiero più testo della risposta), oppure passa thinking: {type: "disabled"} con effort high o inferiore per preservare il vecchio comportamento.
  • Aggiorna il parsing delle risposte che legge il contenuto per posizione, come content[0].text o un gestore di stream che presuppone che il primo blocco di contenuto sia testo: con il pensiero attivo, i blocchi thinking arrivano prima dei blocchi text. Seleziona invece i blocchi di contenuto per type.
  • Se esegui un ciclo di uso degli strumenti, ripassa i blocchi thinking completi e non modificati quando restituisci i risultati degli strumenti; i blocchi modificati restituiscono un errore 400. Vedi Preservare i blocchi di pensiero.
  • Verifica le richieste che disabilitano il pensiero: thinking: {type: "disabled"} con effort xhigh o max restituisce un errore 400, applicato a ogni richiesta. Riabilita il pensiero o abbassa l'effort a high o inferiore.
  • Rimuovi eventuali prefill dei messaggi dell'assistente.
  • Se la tua UI visualizza il contenuto del pensiero, attiva esplicitamente il riassunto del pensiero.
  • Riesegui i benchmark di costo e latenza end-to-end con la tokenizzazione aggiornata; i token di pensiero vengono fatturati come token di output, quindi i carichi di lavoro che venivano eseguiti senza pensiero possono anche produrre più token di output per richiesta.
  • Ricalibra max_tokens per tenere conto della tokenizzazione aggiornata.
  • Ritesta eventuali stime del conteggio dei token lato client.
  • Se la tua applicazione invia immagini, ripianifica il budget per il supporto per 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 hai bisogno della fedeltà aggiuntiva.
  • Se utilizzi coordinate di puntamento o di bounding box 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 modelli successivi.
  • Rivedi i prompt per le modifiche di comportamento (lunghezza della risposta, letteralità, tono, aggiornamenti di avanzamento, subagenti, calibrazione dell'effort, attivazione degli strumenti, salvaguardie cyber, gestione delle immagini ad alta risoluzione).
  • Ristabilisci la baseline della lunghezza della risposta con i prompt di controllo della lunghezza esistenti rimossi, quindi calibra esplicitamente.
  • Se usi effort xhigh o max, alza max_tokens ad almeno 64k come punto di partenza.
  • Considera l'adozione dei task budget (beta) e delle modifiche degli strumenti a metà conversazione (beta) per i flussi di lavoro agentici.
  • Gestisci stop_reason: "refusal", e considera fallbacks: "default" (beta) per rieseguire automaticamente le richieste rifiutate su un modello di fallback consigliato.
  • Rivedi i prompt vicini al minimo per la cache: i prompt di 512 token o più possono ora creare voci di cache su Claude Opus 5.
  • Se usi web fetch, pianifica un'alternativa: non è disponibile su Claude Opus 5.
  • Se la tua organizzazione ha un impegno Priority Tier, nota che Priority Tier non è supportato su Claude Opus 5.
  • Rimuovi le istruzioni di verifica e autocontrollo ereditate da prompt calibrati per modelli precedenti; causano una verifica eccessiva su Claude Opus 5.
  • Se il tuo prodotto svolge lavori di sicurezza legittimi, fai domanda al Cyber Verification Program per accedere a restrizioni inferiori sui contenuti cyber.

Migrazione da Claude Opus 4.5 o precedenti

Se stai migrando da Claude Opus 4.5, Opus 4.1 o un modello precedente direttamente a Claude Opus 5, applica tutte le modifiche precedenti in questa sezione più le seguenti modifiche cumulative, entrate in vigore tra Opus 4.5 e Opus 4.7. Se stai migrando da Opus 4.6, le modifiche precedenti in questa sezione sono tutto ciò di cui hai bisogno.

Aggiorna il nome del modello

# Migrazione a Opus
model = "claude-opus-4-5"  # Before
model = "claude-opus-5"  # After

Modifiche che causano interruzioni

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

  2. Quoting dei parametri degli strumenti: Claude Opus 4.6 e 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.

Queste modifiche migliorano la tua esperienza su Claude Opus 4.7 e modelli successivi. Gli elementi contrassegnati (obbligatorio su Opus 4.7) erano raccomandazioni facoltative al lancio di Opus 4.6 ma sono ora obbligatori; il resto rimane consigliato.

  1. Migra al pensiero adattivo (obbligatorio su Opus 4.7): thinking: {type: "enabled", budget_tokens: N} restituisce un errore 400 su Claude Opus 4.7 e modelli successivi. Passa a thinking: {type: "adaptive"} e usa il parametro effort per controllare la profondità del pensiero; su Claude Opus 5, thinking: {type: "adaptive"} è equivalente a omettere il campo thinking, che viene eseguito con pensiero adattivo per impostazione predefinita. Vedi Pensiero.

    response = client.beta.messages.create(
    model="claude-opus-4-5",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 32000},
    betas=["interleaved-thinking-2025-05-14"],
    messages=[{"role": "user", "content": "Your prompt here"}],
)

    Nota che la migrazione passa anche da client.beta.messages.create a client.messages.create. Il pensiero 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 betas=["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 betas=["fine-grained-tool-streaming-2025-05-14"] dalle tue richieste.

  4. Rimuovi l'header beta del pensiero interleaved: Il pensiero adattivo abilita automaticamente il pensiero interleaved su Claude Opus 4.7, Opus 4.6 e Sonnet 4.6. Rimuovi betas=["interleaved-thinking-2025-05-14"] dalle tue richieste. L'header è ancora funzionante su Sonnet 4.6 con il pensiero esteso manuale, ma la modalità manuale è deprecata.

  5. Migra a output_config.format: Se usi gli output strutturati, aggiorna output_format={...} in output_config={"format": {...}}. L'API accetta ancora il parametro deprecato output_format, ma verrà rimosso in una futura release del modello. Il Python SDK (v1.0 e successive) non accetta output_format={...} su client.beta.messages.create() o count_tokens(). L'argomento output_format=Model degli helper parse() e stream() è invariato.

Migrazione da Claude 4.1 o precedenti

Se stai migrando da Opus 4.1 o modelli precedenti direttamente a Claude Opus 5, applica tutte le modifiche precedenti in questa sezione, più le modifiche aggiuntive in questa sottosezione.

# Da Opus 4.1
model = "claude-opus-4-1-20250805"  # Before
model = "claude-opus-5"  # After

# Da Sonnet 3.7
model = "claude-3-7-sonnet-20250219"  # Before
model = "claude-opus-5"  # After

Modifiche aggiuntive che causano interruzioni

  1. Rimuovi i parametri di campionamento

    A partire da Claude Opus 4.7, impostare temperature, top_p o top_k su qualsiasi valore non predefinito restituisce un errore 400. Il Python SDK (v1.0 e successive) non li definisce, e passarli genera un TypeError. Il percorso di migrazione più sicuro è omettere del tutto questi parametri dalle richieste e usare il prompting per guidare il comportamento del modello. Se usavi temperature = 0 per il determinismo, nota che non ha mai garantito output identici.

    # Prima - Questo genererà un errore nei modelli Claude 4+
response = client.messages.create(
    model="claude-3-7-sonnet-20250219",
    temperature=0.7,
    top_p=0.9,  # Non-default sampling params return 400 on Opus 4.7
    # ...
)

# Dopo
response = client.messages.create(
    model="claude-opus-5",
    # ...
)

  2. Aggiorna le versioni degli strumenti

    Aggiorna alle versioni più recenti 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. Vedi la documentazione dello strumento editor di testo per i dettagli.
    • Esecuzione di codice: Aggiorna a code_execution_20260521. Vedi la documentazione dello strumento di esecuzione del codice per le istruzioni di migrazione.

  3. Gestisci lo stop reason refusal

    Aggiorna la tua applicazione per gestire gli stop reason refusal:

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

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

  4. Gestisci lo stop reason model_context_window_exceeded

    I modelli Claude 4.5+ restituiscono uno stop reason model_context_window_exceeded quando la generazione si interrompe per aver raggiunto il limite della finestra di contesto, anziché il limite max_tokens richiesto. Aggiorna la tua applicazione per gestire questo nuovo stop reason:

    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)

    I modelli Claude 4.5+ preservano i newline finali nei parametri stringa delle chiamate agli strumenti che in precedenza venivano rimossi. Se i tuoi strumenti si basano su una corrispondenza esatta delle stringhe rispetto ai parametri delle chiamate agli strumenti, verifica che la tua logica gestisca correttamente i newline finali.

  6. Aggiorna i tuoi prompt per le modifiche comportamentali

    I modelli Claude 4+ hanno uno stile di comunicazione più conciso e diretto e richiedono indicazioni esplicite. Rivedi le best practice di 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+ hanno l'uso degli strumenti efficiente in termini di token integrato e questi header non hanno alcun effetto.

Checklist di migrazione (da Claude Opus 4.5 o precedenti)

  • Aggiorna l'ID del modello a claude-opus-5
  • Applica tutte le modifiche di rilievo per la migrazione da Claude Opus 4.6 (pensiero esteso rimosso, pensiero attivo per impostazione predefinita, limite di effort per la disattivazione del pensiero, parametri di campionamento rimossi, visualizzazione del pensiero omessa per impostazione predefinita, tokenizzazione aggiornata)
  • MODIFICA DI RILIEVO: Rimuovi i prefill dei messaggi dell'assistente (restituisce un errore 400); usa invece gli output strutturati o output_config.format
  • MODIFICA DI RILIEVO su Opus 4.7: Sostituisci thinking: {type: "enabled", budget_tokens: N} con thinking: {type: "adaptive"} più il parametro effort (restituisce 400 su Opus 4.7)
  • Verifica che il parsing JSON delle chiamate agli strumenti utilizzi un parser JSON standard
  • 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 pensiero adattivo abilita automaticamente il pensiero interleaved)
  • Migra output_format a output_config.format (se applicabile)
  • Se migri da Claude 4.1 o precedenti: rimuovi temperature, top_p e top_k (i valori non predefiniti restituiscono 400 su Opus 4.7)
  • Se migri da Claude 4.1 o precedenti: aggiorna le versioni degli strumenti (text_editor_20250728, code_execution_20260521)
  • Se migri da Claude 4.1 o precedenti: gestisci lo stop reason refusal
  • Se migri da Claude 4.1 o precedenti: gestisci lo stop reason model_context_window_exceeded
  • Se migri da Claude 4.1 o precedenti: verifica la gestione dei parametri stringa degli strumenti per i caratteri di nuova riga finali
  • Se migri da Claude 4.1 o precedenti: 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
  • Esegui i test nell'ambiente di sviluppo prima del deployment in produzione

Migrazione a Claude Opus 5 da Claude Sonnet 5

Claude Opus 5 e Claude Sonnet 5 condividono la stessa superficie API: entrambi funzionano con il pensiero adattivo attivo per impostazione predefinita, entrambi impostano il parametro effort su high per impostazione predefinita sulla Claude API e su Claude Code, entrambi offrono una "context window" (finestra di contesto) da 1M di token per impostazione predefinita con 128k token di output massimi, e nessuno dei due supporta il Priority Tier. Il pensiero esteso manuale e i parametri di campionamento non predefiniti restituiscono un errore 400 su entrambi i modelli, così come il prefill dell'assistente.

Aggiorna il nome del modello

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

Cosa è cambiato

  1. Prezzi: Claude Opus 5 ha un prezzo di $5 USD per milione di token di input e $25 USD per milione di token di output. Claude Sonnet 5 ha un prezzo di $2/$10 USD per milione di token di input/output. Consulta i prezzi di Claude per i prezzi completi.

  2. La disattivazione del pensiero è limitata all'effort high: Su Claude Sonnet 5, thinking: {type: "disabled"} è accettato a qualsiasi livello di effort. Su Claude Opus 5, è accettato solo a un livello di effort pari a high o inferiore; una richiesta che combina thinking: {type: "disabled"} con effort xhigh o max restituisce un errore 400, applicato a ogni richiesta. Verifica le richieste che disattivano il pensiero prima di migrare.

  3. Messaggi di sistema a metà conversazione: Claude Opus 5 accetta messaggi role: "system" immediatamente dopo un turno dell'utente nell'array messages (soggetti alle 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.

  4. Web fetch non è disponibile: Lo strumento web fetch è disponibile su Claude Sonnet 5 ma non su Claude Opus 5.

Checklist di migrazione

  • Aggiorna il nome del modello da claude-sonnet-5 a claude-opus-5.
  • Verifica le richieste che disattivano il pensiero: thinking: {type: "disabled"} con effort xhigh o max restituisce un errore 400 su Claude Opus 5. Riattiva il pensiero o abbassa l'effort a high o inferiore.
  • Se usi web fetch, pianifica un'alternativa: non è disponibile su Claude Opus 5.
  • Esegui nuovamente il conteggio dei token su Claude Opus 5 anziché riutilizzare i conteggi misurati su Claude Sonnet 5, e ricalcola la baseline di costi e latenza sui tuoi carichi di lavoro; il prezzo per token è diverso.

Was this page helpful?