Come utilizzare l'API di Claude Opus 4.5

Anthropic ha rilasciato Claude Opus 4.5 a fine novembre 2025 come un modello di classe Opus più capace ed efficiente, mirato all’ingegneria del software professionale, ai workflow agentici e ai compiti di lungo orizzonte. È disponibile tramite la piattaforma per sviluppatori di Anthropic e via CometAPI e introduce nuovi controlli API (in particolare il parametro effort), strumenti migliorati per l’uso del computer, extended thinking e miglioramenti all’efficienza dei token rilevanti in produzione.

Di seguito una guida pratica e professionale: cosa è cambiato, come ottenere l’accesso, come usare i nuovi controlli (effort, extended thinking, tool use, file/computer use), indicazioni su costi e ottimizzazione, considerazioni su sicurezza/governance e modelli di integrazione reali.

Che cos’è esattamente Claude Opus 4.5 e perché è importante?

Claude Opus 4.5 è il più recente membro della famiglia di modelli di classe Opus di Anthropic (rilasciato il 24–25 novembre 2025) che punta al massimo sulle capacità di ragionamento e coding, migliorando l’efficienza dei token e offrendo nuovi controlli API per bilanciare costi e accuratezza. Anthropic posiziona Opus 4.5 come il “modello più intelligente” finora rilasciato, puntando a compiti complessi di ingegneria del software, agenti a lunga esecuzione, automazione su spreadsheet/Excel e attività che richiedono ragionamento multi-step prolungato.

Quali sono gli aggiornamenti principali in Opus 4.5?

Anthropic ha progettato Opus 4.5 per migliorare la profondità del ragionamento e il comportamento agentico, offrendo al contempo agli sviluppatori un controllo migliore sui trade-off costo/latenza. I punti salienti del rilascio sono:

• Parametro effort (beta): una manopola API di primo livello che controlla quanto “budget di pensiero” Claude spende per una richiesta (comunemente low, medium, high). Influenza il ragionamento, le chiamate agli strumenti e i token interni di “thinking” così da poter calibrare velocità vs. accuratezza per singola chiamata invece di cambiare modello. È una funzionalità distintiva di Opus 4.5.
• Migliore orchestrazione di agenti e strumenti: maggiore accuratezza nella scelta degli strumenti, chiamate agli strumenti più strutturate e un workflow tool-result più robusto per costruire agenti e pipeline multi-step. Anthropic fornisce documentazione e guida SDK per il flusso di “tool use”.
• Efficienza di token/costi — Anthropic riporta riduzioni fino a ~50% nell’uso di token per alcuni workflow rispetto a Sonnet 4.5, oltre a meno errori nelle chiamate agli strumenti e meno iterazioni per compiti di ingegneria complessi.
• Capacità multimodali potenziate: miglioramenti completi in ambito visivo, di ragionamento e matematico.
• Finestra di contesto ampliata a 200K token, a supporto di conversazioni profonde e lunghe e di analisi di documenti complessi.

Quali capacità pratiche sono migliorate?

Aggiornamento delle prestazioni

• Migliore orchestrazione di agenti e strumenti: maggiore accuratezza nella scelta degli strumenti, chiamate agli strumenti più strutturate e un workflow tool-result più robusto per costruire agenti e pipeline multi-step. Anthropic fornisce documentazione e guida SDK per il flusso di “tool use”. Migliorata la gestione del contesto, helper di compattazione per esecuzioni prolungate degli agenti, e SDK di strumenti di prima classe per registrare e validare gli strumenti: tutto ciò rende Opus 4.5 più adatto a costruire agenti che operano senza supervisione per molti step.
• Capacità multimodali potenziate: miglioramenti completi in ambito visivo, di ragionamento e matematico.
• Finestra di contesto ampliata a 200K token, a supporto di conversazioni profonde e lunghe e di analisi di documenti complessi.

Sviluppo e attività di lungo periodo

Opus 4.5 continua a essere guidato da benchmark per i compiti di coding; riduce il numero di iterazioni e gli errori nelle chiamate agli strumenti durante lavori lunghi (migrazione di codice, refactor, debug multi-step). Report iniziali e la system card di Anthropic segnalano prestazioni sostenute migliori sui benchmark di ingegneria e notevoli guadagni di efficienza in pipeline guidate da strumenti.

In SWE-bench, Opus 4.5 riporta punteggi leader sui benchmark di ingegneria del software (Anthropic indica un 80,9% su SWE-bench Verified nel materiale di lancio), e i clienti segnalano miglioramenti nel debug, nelle modifiche multi-file e nei compiti di codice di lungo periodo.

Costi ed efficienza

Anthropic ha progettato Opus 4.5 per migliorare la profondità del ragionamento e il comportamento agentico, offrendo al contempo agli sviluppatori un controllo migliore sui trade-off costo/latenza:

• Riduzione di prezzo rispetto a Opus 4.1: $5 (input) / $25 (output) per milione di token.
• Miglioramento dell’uso dei token: riduzione media del 50–75% dei consumi mantenendo le prestazioni.
• una manopola API di primo livello che controlla quanto “budget di pensiero” Claude spende per una richiesta (comunemente low, medium, high). Influenza il ragionamento, le chiamate agli strumenti e i token interni di “thinking”, così puoi calibrare velocità vs. accuratezza per singola chiamata invece di cambiare modello. È una funzionalità distintiva di Opus 4.5 (Rispetto a Sonnet 4.5: Medium Effort → 76% di token in meno, prestazioni comparabili; High Effort → +4,3% di prestazioni, 48% di riduzione dei token).

Come accedo e uso l’API di Claude Opus 4.5?

Come ottenere l’accesso e le chiavi?

1. Crea un account sviluppatore Anthropic / Claude. Registrati al portale per sviluppatori Claude/Anthropic e crea una chiave API tramite la Console (per i team esistono flussi organization/admin). La Messages API è l’endpoint principale per interazioni in stile chat/assistant.
2. Cloud partner: Opus 4.5 è disponibile anche tramite i principali marketplace cloud Google Vertex AI, CometAPI(An AI API aggregation platform, need to uses its authentication)), In CometAPI, you can access Claude opus 4.5 API via Anthropic Messages format and Chat format.

Come devo autenticare le richieste?

Usa i token Bearer standard: includi un header Authorization: Bearer $_API_KEY in ogni chiamata API. Le richieste sono JSON su HTTPS; la Messages API accetta un elenco di messaggi strutturati (system + user + assistant).

Avvio rapido — Python (SDK ufficiale)

Installa l’SDK:

pip install anthropic

Esempio minimo (sincrono):

import os
from anthropic import Anthropic

# expects ANTHROPIC_API_KEY in env

client = Anthropic(api_key=os.environ)

resp = client.messages.create(
    model="claude-opus-4-5-20251101",
    messages=,
    max_tokens=512,
)

print(resp.content.text)  # SDK returns structured content blocks

Questa chiamata usa l’identificatore canonico del modello Opus 4.5. Per endpoint gestiti dal provider (Vertex, CometAPI, Foundry) segui la documentazione del provider per costruire il client e fornire URL e chiave del provider (ad es., https://api.cometapi.com/v1/messages per CometAPI).

Avvio rapido — Python (CometAPI)

È necessario accedere a CometAPI e ottenere una chiave.

curl 
--location 
--request POST 'https://api.cometapi.com/v1/messages' \ 
--header 'Authorization: Bearer ' \ 
--header 'Content-Type: application/json' \ 
--data-raw '{ "model": "claude-opus-4-5-20251101", "max_tokens": 1000, "thinking": { "type": "enabled", "budget_tokens": 1000 }, "messages":  }'

Come uso il nuovo parametro effort e l’extended thinking?

Che cos’è il parametro effort e come lo imposto?

Il parametro effort è un controllo API di primo livello introdotto con Opus 4.5 che regola quanta computazione interna e quale budget di token il modello spende per produrre l’output. I valori tipici sono low, medium e high. Usalo per bilanciare latenza e costo dei token rispetto alla completezza:

• low — risposte rapide ed efficienti in token per automazioni ad alto volume e compiti di routine.
• medium — equilibrio qualità/costo per l’uso in produzione.
• high — analisi approfondita, ragionamento multi-step o quando l’accuratezza conta di più.

Anthropic ha introdotto effort per Opus 4.5 (beta). Devi includere un header beta (ad es., effort-2025-11-24) e specificare output_config: { "effort": "low|medium|high" } (esempio sotto). high è il comportamento predefinito. Abbassare l’effort riduce l’uso di token e la latenza ma può ridurre moderatamente la completezza. Usalo per carichi ad alto throughput o sensibili alla latenza.

Esempio:

# Example using the beta messages API shown in Anthropic docs

from anthropic import Anthropic
import os

client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))

response = client.beta.messages.create(
    model="claude-opus-4-5-20251101",
    betas=,   # required beta header

    messages=,
    max_tokens=1500,
    output_config={"effort": "medium"}  # low | medium | high

)

print(response)

Quando usare cosa: imposta low per pipeline automatizzate (ad es., categorizzazione email), medium per assistant standard e high per generazione di codice, ricerche approfondite o compiti sensibili al rischio. Anthropic evidenzia questo parametro come un controllo chiave per Opus 4.5.

Nel test SWE-bench:

• In modalità Medium Effort: prestazioni comparabili a Sonnet 4.5, ma i token di output sono ridotti del 76%;
• In modalità High Effort: le prestazioni superano Sonnet 4.5 di circa 4,3 punti percentuali, e i token sono ridotti del 48%.

Che cos’è l’Extended Thinking e come lo richiamo?

L’Extended Thinking (chiamato anche “extended thinking” o “thinking blocks”) consente al modello di eseguire catene di pensiero intermedie o ragionamento passo-passo preservando o riassumendo opzionalmente i blocchi di pensiero interni. La Messages API supporta questo comportamento e Anthropic ha aggiunto controlli per preservare i blocchi di pensiero precedenti, così che agenti multi-turn possano riutilizzare il ragionamento pregresso senza ripetere ricomputazioni costose. Usa l’extended thinking quando il compito richiede pianificazione multi-step, problem solving di lungo orizzonte o orchestrazione di strumenti.

Come integro strumenti e costruisco agenti con Opus 4.5?

Uno dei punti di forza di Opus 4.5 è il migliorato uso degli strumenti: definisci gli strumenti nel tuo client, lascia che Claude decida quando chiamarli, esegui lo strumento e restituisci il tool_result — Claude utilizzerà quei risultati nella risposta finale. Anthropic fornisce Agent SDK che consentono di registrare funzioni di strumenti tipizzate (ad es., run_shell, call_api, search_docs) che Claude può scoprire e chiamare durante l’extended thinking. La piattaforma converte le definizioni degli strumenti in funzioni invocabili che il modello può chiamare e da cui può ricevere risultati. È così che costruisci workflow agentici in sicurezza (con input/output controllati).

Di seguito uno schema pratico e un esempio end-to-end in Python.

Schema di utilizzo degli strumenti (concettuale)

1. Il client fornisce metadati tools con nome, descrizione e schema JSON (input_schema).
2. Il modello restituisce un blocco tool_use (l’istruzione strutturata del modello per chiamare uno strumento specifico con determinati input). Il campo stop_reason della risposta API può essere tool_use.
3. Il client esegue lo strumento (il tuo codice chiama l’API esterna o la funzione locale).
4. Il client invia un messaggio di follow-up con role:"user" e un blocco di contenuto tool_result contenente gli output dello strumento.
5. Il modello consuma il risultato dello strumento e restituisce la risposta finale o ulteriori chiamate a strumenti.

Questo flusso consente un controllo sicuro lato client su ciò che viene eseguito (il modello propone le chiamate; tu decidi se eseguirle).

Esempio end-to-end — Python (strumento meteo semplice)

# 1) Define tools metadata and send initial request

from anthropic import Anthropic
import os, json

client = Anthropic(api_key=os.environ)

tools = [
    {
        "name": "get_weather",
        "description": "Return the current weather for a given city.",
        "input_schema": {"type":"object","properties":{"city":{"type":"string"}},"required":}
    }
]

resp = client.messages.create(
    model="claude-opus-4-5-20251101",
    messages=,
    tools=tools,
    max_tokens=800,
)

# 2) Check if Claude wants a tool call

stop_reason = resp.stop_reason  # SDK field

if stop_reason == "tool_use":
    # Extract the tool call (format varies by SDK; this is schematic)

    tool_call = resp.tool_calls  # e.g., {"name":"get_weather", "input":{"city":"Tokyo"}}

    tool_name = tool_call
    tool_input = tool_call

    # 3) Execute the tool client-side (here: stub)

    def get_weather(city):
        # Replace this stub with a real weather API call

        return {"temp_c": 12, "condition": "Partly cloudy"}

    tool_result = get_weather(tool_input)

    # 4) Send tool_result back to Claude

    follow_up = client.messages.create(
        model="claude-opus-4-5-20251101",
        messages=[
            {"role":"user", "content":[{"type":"tool_result",
                                        "tool_use_id": resp.tool_use_id,
                                        "content": json.dumps(tool_result)}]}
        ],
        max_tokens=512,
    )

    print(follow_up.content.text)
else:
    print(resp.content.text)

Come strutturare gli agenti per l’affidabilità?

• Sanitizza gli input degli strumenti (evita injection via prompt).
• Convalida gli output degli strumenti prima di reinserirli nel modello (controlli di schema).
• Limita l’ambito degli strumenti (principio del privilegio minimo).
• Usa gli helper di compattazione (dagli SDK Anthropic) per mantenere gestibile il contesto in esecuzioni lunghe.

---

Come progettare i prompt e strutturare i messaggi per Opus 4.5?

Quali ruoli dei messaggi e strategie di prefill funzionano meglio?

Usa uno schema in tre parti:

• System (ruolo: system): istruzioni globali — tono, paletti, ruolo.
• Assistant (opzionale): esempi precompilati o contenuti di priming.
• User (ruolo: user): la richiesta immediata.

Precompila il messaggio di sistema con vincoli (formato, lunghezza, policy di sicurezza, schema JSON se desideri output strutturati). Per gli agenti, includi specifiche degli strumenti ed esempi d’uso così che Opus 4.5 possa chiamarli correttamente.

Come usare la compattazione del contesto e il caching del prompt per risparmiare token?

• Compattazione del contesto: comprimi le parti più vecchie di una conversazione in riassunti concisi che il modello possa ancora usare. Opus 4.5 supporta l’automazione per compattare il contesto senza perdere blocchi di ragionamento critici.
• Prompt caching: metti in cache le risposte del modello per prompt ripetuti (Anthropic fornisce pattern di caching del prompt per ridurre latenza/costo).

Entrambe le funzionalità riducono l’impronta di token nelle interazioni lunghe e sono consigliate per workflow di agenti di lunga durata e assistant in produzione.

Gestione degli errori e best practice

Di seguito raccomandazioni pragmatiche su affidabilità e sicurezza per integrazioni in produzione con Opus 4.5.

Affidabilità e retry

• Gestisci i rate limit (HTTP 429) con backoff esponenziale e jitter (parti da 500–1000 ms).
• Idempotenza: per chiamate all’LLM non mutanti puoi eseguire retry in sicurezza, ma fai attenzione in workflow dove il modello innesca effetti collaterali esterni (tool call) — deduplica tracciando tool_use_id o tuoi ID di richiesta.
• Stabilità dello streaming: gestisci stream parziali e riconnetti in modo resiliente; in caso di interruzione, meglio ritentare l’intera richiesta o riprendere usando lo stato applicativo per evitare interazioni incoerenti con gli strumenti.

Sicurezza e tutela

• Prompt injection e sicurezza degli strumenti: non consentire mai al modello di eseguire direttamente comandi shell o codice arbitrario senza validazione. Valida sempre gli input degli strumenti e sanitizza gli output. Il modello propone le chiamate; il tuo codice decide se eseguirle. La system card e la documentazione di Anthropic descrivono vincoli di allineamento e livelli di safety — seguili per domini ad alto rischio.
• Gestione dei dati e compliance: tratta prompt e input/output degli strumenti contenenti PII o dati regolamentati secondo le tue policy legali/compliance. Usa i controlli VPC/enterprise del provider se hai requisiti stringenti di residenza dei dati o audit (Bedrock / Vertex / Foundry offrono opzioni enterprise).

Osservabilità e controllo dei costi

• Registra i metadati delle richieste/risposte (non i contenuti sensibili grezzi, a meno che sia consentito) — conteggi dei token, livello effort, latenza, ID modello e provider. Queste metriche sono essenziali per l’attribuzione dei costi e il debug.
• Usa effort per controllare il costo per chiamata: preferisci low per riassunti di routine o endpoint ad alto QPS; usa high per debug approfonditi o indagini. Monitora qualità vs. consumo di token per scegliere i default per i diversi endpoint.

Conclusione — Quando (e come) dovresti scegliere Opus 4.5?

Claude Opus 4.5 è una scelta naturale quando il tuo prodotto necessita di:

• ragionamento multi-step profondo (lunghe catene logiche, ricerca o debug),
• orchestrazione robusta di agenti/strumenti (workflow complessi che invocano API esterne), oppure
• assistenza al codice di livello production su grandi codebase.

Operativamente, usa effort per calibrare i budget per chiamata; affidati al pattern di tool use per mantenere sicura l’esecuzione e scegli un partner cloud (o l’API diretta Anthropic) in base alle tue esigenze di compliance. Esegui benchmark sul tuo corpus: i numeri del vendor (SWE-bench, ecc.) sono segnali utili, ma il ROI lo determinano i tuoi task e dati reali. Per la sicurezza, segui la system card di Opus 4.5 e metti paletti attorno all’esecuzione degli strumenti e alla gestione delle PII.

Gli sviluppatori possono accedere all’API di Claude Opus 4.5 tramite CometAPI. Per iniziare, esplora le funzionalità del modello di CometAPI nel Playground e consulta la guida all’API per istruzioni dettagliate. Prima di accedere, assicurati di aver effettuato il login a CometAPI e di aver ottenuto la chiave API. CometAPI offre un prezzo molto inferiore a quello ufficiale per aiutarti nell’integrazione.

Pronto a partire? → Registrati a CometAPI oggi stesso!

Se vuoi altri consigli, guide e notizie sull’IA, seguici su VK, X e Discord!