Usare le API di Claude (Opus 5 e Sonnet 5) in Python

Con l'arrivo di Claude Opus 5 il 24 luglio 2026, le API di Anthropic sono diventate ancora piu' interessanti per chi costruisce applicazioni: intelligenza di frontiera per il coding e l'uso di strumenti, a un prezzo dimezzato rispetto ai modelli piu' potenti dell'azienda. In questa guida vediamo, passo dopo passo, come chiamare Claude da Python — dalla prima richiesta fino a funzioni avanzate come lo streaming, il function calling e il ragionamento esteso.

A chi serve questa guida e cosa ti serve prima di iniziare

La guida e' pensata per sviluppatori con basi di Python che vogliono integrare Claude in un'app, uno script o un agente. Serviranno:

• Python 3.9 o superiore installato (verifica con python --version);
• un account su console.anthropic.com e una chiave API (si crea dalla sezione API Keys);
• del credito sul conto: le API sono a consumo, si paga per token effettivamente usati;
• un terminale e un editor di testo.

Al termine saprai fare chiamate semplici e complesse, gestire le conversazioni multi-turno e far usare a Claude i tuoi strumenti (funzioni Python), il tutto con codice riutilizzabile.

Passo 1: installazione e configurazione della chiave

Installa l'SDK ufficiale con pip:

pip install anthropic

Non scrivere mai la chiave API dentro il codice. Impostala come variabile d'ambiente, cosi' l'SDK la legge automaticamente. Su Linux e macOS:

export ANTHROPIC_API_KEY="la-tua-chiave-qui"

Su Windows (PowerShell):

setx ANTHROPIC_API_KEY "la-tua-chiave-qui"

Passo 2: la prima chiamata a Claude Opus 5

Ecco lo script minimo. L'identificativo del modello e' claude-opus-5; per un modello piu' economico e velocissimo puoi usare claude-sonnet-5.

from anthropic import Anthropic

client = Anthropic()  # legge ANTHROPIC_API_KEY dall'ambiente

resp = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Spiega in 3 frasi cos'e' un embedding."}
    ],
)

print(resp.content[0].text)

Il parametro max_tokens e' obbligatorio e limita la lunghezza della risposta. Il risultato atteso e' un breve testo di tre frasi. L'oggetto resp contiene anche resp.usage, con il conteggio dei token in ingresso e in uscita: utile per stimare i costi.

Passo 3: dare istruzioni con il system prompt

Il prompt di sistema definisce il ruolo e il comportamento del modello. A differenza di altri SDK, in Anthropic non e' un messaggio nella lista ma un parametro dedicato system:

resp = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=800,
    system="Sei un assistente che risponde solo in italiano, con tono conciso e professionale.",
    messages=[
        {"role": "user", "content": "Dammi 3 idee per un titolo di articolo sull'IA in sanita'."}
    ],
)
print(resp.content[0].text)

Passo 4: streaming, per risposte in tempo reale

Per interfacce di chat conviene ricevere la risposta parola per parola invece di aspettare che sia completa. Si usa il metodo stream:

with client.messages.stream(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Scrivi una breve poesia sull'estate."}],
) as stream:
    for testo in stream.text_stream:
        print(testo, end="", flush=True)

Il testo appare progressivamente sul terminale, come nell'app di ChatGPT o Claude. E' l'approccio da preferire quando l'utente attende una risposta lunga.

Passo 5: conversazioni multi-turno

Le API sono senza stato: per mantenere il contesto devi rimandare l'intera cronologia a ogni chiamata. Basta accodare i messaggi, alternando i ruoli user e assistant:

storia = [
    {"role": "user", "content": "Consigliami un linguaggio per iniziare a programmare."},
]
r1 = client.messages.create(model="claude-sonnet-5", max_tokens=500, messages=storia)
storia.append({"role": "assistant", "content": r1.content[0].text})
storia.append({"role": "user", "content": "E per la data science, invece?"})
r2 = client.messages.create(model="claude-sonnet-5", max_tokens=500, messages=storia)
print(r2.content[0].text)

Passo 6: function calling (tool use), il cuore degli agenti

La funzione piu' potente e' il tool use: Claude puo' decidere di chiamare una funzione che gli metti a disposizione — per esempio una che interroga il meteo o il tuo database. Definisci lo strumento con uno schema JSON e gestisci la risposta quando il modello lo invoca:

tools = [{
    "name": "meteo",
    "description": "Restituisce il meteo attuale per una citta'.",
    "input_schema": {
        "type": "object",
        "properties": {"citta": {"type": "string"}},
        "required": ["citta"],
    },
}]

msg = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "Che tempo fa a Milano?"}],
)

if msg.stop_reason == "tool_use":
    blocco = next(b for b in msg.content if b.type == "tool_use")
    # qui chiami la TUA funzione reale con blocco.input["citta"]
    risultato = "Sereno, 29 gradi"
    followup = client.messages.create(
        model="claude-opus-5",
        max_tokens=1024,
        tools=tools,
        messages=[
            {"role": "user", "content": "Che tempo fa a Milano?"},
            {"role": "assistant", "content": msg.content},
            {"role": "user", "content": [{
                "type": "tool_result",
                "tool_use_id": blocco.id,
                "content": risultato,
            }]},
        ],
    )
    print(followup.content[0].text)

Il flusso e' sempre questo: il modello chiede di usare uno strumento, tu esegui la funzione reale nel tuo codice e gli restituisci il risultato con un blocco tool_result, poi il modello formula la risposta finale in linguaggio naturale. E' lo schema su cui si costruiscono gli agenti.

Passo 7: attivare il ragionamento esteso

Per i problemi complessi — matematica, pianificazione, debugging difficile — puoi attivare il ragionamento esteso (extended thinking), che fa "pensare" il modello prima di rispondere assegnando un budget di token al ragionamento:

resp = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    thinking={"type": "enabled", "budget_tokens": 2000},
    messages=[{"role": "user", "content": "Risolvi passo passo: 17 operai in 12 giorni... quanti giorni servono a 6 operai?"}],
)
for blocco in resp.content:
    if blocco.type == "text":
        print(blocco.text)

Con Opus 5, Anthropic ha introdotto un controllo dello sforzo su piu' livelli: piu' budget dai al ragionamento, migliori (e piu' costose) sono le risposte sui compiti difficili. Per le richieste banali tienilo disattivato, per non sprecare token.

Errori comuni e come risolverli

• authentication_error / 401: la chiave non e' impostata o e' sbagliata. Verifica la variabile d'ambiente con echo $ANTHROPIC_API_KEY.
• rate_limit_error / 429: troppe richieste. Introduci attese progressive (backoff) tra i tentativi.
• invalid_request_error per max_tokens mancante: il parametro e' obbligatorio, aggiungilo sempre.
• Risposta troncata: hai raggiunto il limite di max_tokens. Alzalo se ti serve output piu' lungo.

Quanto costa e quando scegliere quale modello

Claude Opus 5 costa 5 dollari per milione di token in ingresso e 25 in uscita: e' la scelta giusta per coding agentico, ragionamento complesso e uso di strumenti. Per la maggior parte dei compiti quotidiani — classificazione, riassunti, chat semplici — conviene invece Claude Sonnet 5, molto piu' economico e veloce. Una buona regola: prototipa con Opus 5 per capire il massimo delle prestazioni, poi valuta se Sonnet 5 basta per il tuo caso reale, risparmiando molto sui costi in produzione.

Alternative e prossimi passi

Se preferisci non dipendere da un servizio cloud, puoi eseguire modelli open in locale con Ollama o LM Studio; se lavori gia' con l'ecosistema OpenAI o Google, gli SDK sono concettualmente simili a questo. Da qui puoi proseguire costruendo un piccolo agente che combina piu' strumenti, oppure integrando le API in un backend web. La documentazione ufficiale di Anthropic resta il riferimento per parametri, limiti e novita' dei modelli.