A chi serve: sviluppatori e curiosi che sanno un po' di Python e vogliono integrare Claude, il modello di Anthropic, nelle proprie applicazioni - per riassumere testi, estrarre dati, costruire chatbot o piccoli agenti. Cosa otterrai: un ambiente funzionante e quattro ricette pronte (prima chiamata, streaming, tool use, controllo costi). Prerequisiti: Python 3.8+, un terminale, e una chiave API ottenuta dalla console di Anthropic (la registrazione e l'uso delle API sono a consumo, a pagamento).

Quale modello scegliere e quanto costa

Anthropic offre piu' modelli, da bilanciare tra intelligenza, velocita' e costo. Per la maggior parte dei compiti il riferimento e' Claude Opus 4.8 (ID claude-opus-4-8); per carichi ad alto volume conviene Claude Sonnet 4.6 (claude-sonnet-4-6), piu' economico; per compiti semplici e veloci c'e' Claude Haiku 4.5 (claude-haiku-4-5). I prezzi indicativi 2026 per milione di token (input/output) sono circa: Opus 4.8 a 5/25 dollari, Sonnet 4.6 a 3/15, Haiku 4.5 a 1/5. La regola pratica: prototipa con Opus o Sonnet, poi scegli il modello piu' piccolo che regge la qualita' richiesta.

Conviene prototipare con un modello capace e poi scegliere il piu' piccolo che basta.

1. Installazione e prima chiamata

Installa l'SDK ufficiale e imposta la chiave come variabile d'ambiente (mai scriverla nel codice):

pip install anthropic
export ANTHROPIC_API_KEY="la-tua-chiave"   # su Windows: setx ANTHROPIC_API_KEY "..."

La prima richiesta usa l'endpoint Messages. Il parametro max_tokens e' il tetto di lunghezza della risposta:

import anthropic

client = anthropic.Anthropic()  # legge ANTHROPIC_API_KEY dall'ambiente

resp = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    system="Sei un assistente conciso che risponde in italiano.",
    messages=[{"role": "user", "content": "Spiega cos'e' un'API in due frasi."}],
)

for block in resp.content:
    if block.type == "text":
        print(block.text)

Nota: resp.content e' una lista di blocchi, non una stringa. Controlla sempre block.type prima di leggere block.text. Il prompt di sistema (system) definisce il comportamento; i messaggi alternano i ruoli user e assistant.

2. Streaming: risposte in tempo reale

Per output lunghi o interfacce chat conviene lo streaming, che stampa il testo man mano che viene generato ed evita timeout sulle risposte lunghe:

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=2048,
    messages=[{"role": "user", "content": "Scrivi una breve storia sul mare."}],
) as stream:
    for testo in stream.text_stream:
        print(testo, end="", flush=True)
    finale = stream.get_final_message()
    print("\n\nToken usati:", finale.usage.output_tokens)

Il risultato atteso e' la storia che appare parola per parola, seguita dal conteggio dei token. get_final_message() restituisce comunque il messaggio completo, utile per registrare l'uso o continuare la conversazione.

3. Tool use: far chiamare funzioni a Claude

Il vero salto di qualita' e' il tool use: si descrivono delle funzioni e Claude decide quando usarle, restituendo i parametri da passare. Sta a noi eseguirle e rimandare il risultato. Esempio con una funzione meteo fittizia:

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

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

if resp.stop_reason == "tool_use":
    blocco = next(b for b in resp.content if b.type == "tool_use")
    # qui chiameresti la tua vera API meteo:
    risultato = "18 gradi e sereno"
    messages.append({"role": "assistant", "content": resp.content})
    messages.append({"role": "user", "content": [{
        "type": "tool_result", "tool_use_id": blocco.id, "content": risultato}]})
    finale = client.messages.create(model="claude-opus-4-8", max_tokens=1024,
                                    tools=tools, messages=messages)
    print(next(b.text for b in finale.content if b.type == "text"))

Il flusso e': Claude chiede di usare lo strumento (stop_reason == "tool_use"), tu esegui la funzione vera, rimandi il risultato con tool_result e Claude formula la risposta finale, ad esempio "A Torino ci sono 18 gradi e il cielo e' sereno". E' lo schema con cui si costruiscono gli agenti.

Con il tool use, Claude decide quando chiamare le tue funzioni e tu le esegui.

4. Controllare i costi

Ogni risposta riporta l'uso dei token in resp.usage (input_tokens e output_tokens): moltiplicandoli per le tariffe del modello si stima la spesa. Tre accorgimenti utili: tieni max_tokens ragionevole per non pagare output inutile; usa il modello piu' piccolo che regge il compito; sfrutta il prompt caching quando ripeti lo stesso contesto lungo (ad esempio un documento di riferimento), passando cache_control per pagare le parti gia' viste a tariffa ridotta. Per stimare in anticipo la dimensione di un prompt esiste l'endpoint client.messages.count_tokens(), da preferire a librerie generiche di altri fornitori.

5. Conversazioni a piu' turni

L'API e' senza memoria: a ogni chiamata devi rimandare l'intera conversazione. Per costruire un chatbot basta accumulare i messaggi in una lista, alternando i ruoli, e reinviarla ogni volta:

messaggi = []

def chiedi(testo):
    messaggi.append({"role": "user", "content": testo})
    r = client.messages.create(model="claude-opus-4-8", max_tokens=1024,
                               messages=messaggi)
    risposta = next(b.text for b in r.content if b.type == "text")
    messaggi.append({"role": "assistant", "content": risposta})
    return risposta

print(chiedi("Mi chiamo Luca."))
print(chiedi("Come mi chiamo?"))  # Claude ricorda: "Luca"

Il modello "ricorda" perche' gli ripassi tu la cronologia. Per conversazioni molto lunghe esistono tecniche di compattazione automatica del contesto, ma per iniziare questo schema basta e avanza.

Errori comuni e soluzioni

  • 401 authentication_error: chiave mancante o errata. Verifica che ANTHROPIC_API_KEY sia impostata nell'ambiente da cui lanci lo script.
  • 404 not_found: ID del modello sbagliato. Usa esattamente claude-opus-4-8, claude-sonnet-4-6 o claude-haiku-4-5, senza suffissi di data inventati.
  • 429 rate_limit: troppe richieste. L'SDK riprova in automatico con backoff; per volumi alti valuta l'API Batches, piu' economica.
  • Risposta troncata (stop_reason == "max_tokens"): alza max_tokens o passa allo streaming.

Come proseguire

Da qui si puo' crescere in piu' direzioni: gestire conversazioni a piu' turni accumulando i messaggi nella lista messages; usare gli output strutturati per ottenere JSON validato; far analizzare PDF passandoli come documento; costruire un piccolo agente che concatena piu' strumenti. La documentazione ufficiale di Anthropic e il repository dell'SDK contengono esempi completi per ogni funzione. Il consiglio di metodo: parti da una chiamata semplice che funziona, poi aggiungi una capacita' alla volta - streaming, poi strumenti, poi memoria - verificando ogni passo.