Claude di Anthropic è uno dei modelli più usati per scrivere codice, analizzare testi lunghi e costruire agenti. In questa guida impari a usarlo dal tuo programma Python: dal primo messaggio fino a tecniche che fanno la differenza in produzione, come lo streaming, l'uso degli strumenti (tool use) e il prompt caching, che può tagliare i costi anche del 90% sui contesti ripetuti.

A chi serve e prerequisiti

È pensata per sviluppatori (anche alle prime armi con le API IA) che vogliono integrare Claude in un'app, uno script o un backend. Ti servono: Python 3.8+, un account su console.anthropic.com con una API key e qualche euro di credito. Tutti gli esempi sono in Python, ma l'SDK ufficiale esiste anche per TypeScript/JavaScript con la stessa logica.

Quale modello scegliere

Anthropic offre una famiglia di modelli con un compromesso diverso tra qualità, velocità e prezzo:

  • Claude Opus 4.7 (claude-opus-4-7) — il più capace, per ragionamento difficile, codice complesso e agenti. Costa di più.
  • Claude Sonnet 4.6 (claude-sonnet-4-6) — l'equilibrio migliore: ottimo per la gran parte dei compiti, veloce e con un buon prezzo. È la prima scelta consigliata per iniziare.
  • Claude Haiku 4.5 (claude-haiku-4-5) — il più rapido ed economico, per classificazione, estrazione e volumi elevati.

Passo 1 — Installazione e primo messaggio

pip install anthropic

Imposta la chiave come variabile d'ambiente (così non finisce nel codice):

# macOS/Linux
export ANTHROPIC_API_KEY="la-tua-chiave"
# Windows (PowerShell)
setx ANTHROPIC_API_KEY "la-tua-chiave"

Il primo messaggio. Si usa l'endpoint Messages; max_tokens è obbligatorio e limita la lunghezza della risposta:

from anthropic import Anthropic

client = Anthropic()  # legge ANTHROPIC_API_KEY dall'ambiente

msg = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system="Sei un assistente esperto che risponde in italiano, in modo conciso.",
    messages=[
        {"role": "user", "content": "Spiega cos'è un'API in 3 frasi."}
    ],
)
print(msg.content[0].text)

Risultato atteso: tre frasi chiare in italiano. Nota due cose: il system prompt è un parametro a parte (non un messaggio), e la risposta è una lista di «blocchi» (msg.content), da cui leggiamo il testo.

L'SDK ufficiale legge la chiave da ANTHROPIC_API_KEY: mai scriverla nel codice.

Passo 2 — Streaming: la risposta che appare parola per parola

Per le interfacce chat conviene ricevere il testo man mano che viene generato, invece di aspettare la fine:

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

Vedrai la poesia comparire in tempo reale. Lo streaming migliora molto la percezione di velocità nelle app rivolte agli utenti.

Passo 3 — Conversazioni a più turni

Claude non ha memoria tra una chiamata e l'altra: la «memoria» sei tu che gliela passi, accodando i messaggi precedenti. La struttura alterna ruoli user e assistant:

storia = [
    {"role": "user", "content": "Ciao, mi chiamo Andrea."},
    {"role": "assistant", "content": "Ciao Andrea! Come posso aiutarti?"},
    {"role": "user", "content": "Come mi chiamo?"},
]
r = client.messages.create(model="claude-sonnet-4-6", max_tokens=200, messages=storia)
print(r.content[0].text)  # -> "Ti chiami Andrea."

Passo 4 — Tool use: far chiamare a Claude le tue funzioni

Il tool use permette a Claude di chiedere l'esecuzione di una funzione che definisci tu (es. meteo, ricerca su database, calcoli). Il flusso: descrivi gli strumenti, Claude risponde indicando quale usare e con quali argomenti, tu esegui e gli restituisci il risultato.

tools = [{
    "name": "meteo_attuale",
    "description": "Restituisce il meteo attuale di una città.",
    "input_schema": {
        "type": "object",
        "properties": {"citta": {"type": "string", "description": "Nome della città"}},
        "required": ["citta"],
    },
}]

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

if r.stop_reason == "tool_use":
    blocco = next(b for b in r.content if b.type == "tool_use")
    # Qui esegui DAVVERO la tua funzione con blocco.input["citta"]
    risultato = {"temperatura": "19°C", "cielo": "sereno"}
    follow = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        tools=tools,
        messages=[
            {"role": "user", "content": "Che tempo fa a Milano?"},
            {"role": "assistant", "content": r.content},
            {"role": "user", "content": [{
                "type": "tool_result",
                "tool_use_id": blocco.id,
                "content": str(risultato),
            }]},
        ],
    )
    print(follow.content[0].text)

Risultato atteso: Claude formula una risposta naturale del tipo «A Milano ci sono 19°C con cielo sereno», basata sul dato che gli hai restituito. È il mattone su cui si costruiscono gli agenti.

Con il tool use Claude decide quale funzione chiamare; l'esecuzione resta nel tuo codice.

Passo 5 — Prompt caching: pagare una volta per il contesto fisso

Se invii ripetutamente lo stesso blocco lungo (un manuale, istruzioni complesse, un grande documento), il prompt caching lo memorizza sul lato server: dalla seconda chiamata in poi quella parte costa una frazione. Si attiva marcando il blocco con cache_control:

r = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[
        {"type": "text", "text": "Sei un assistente legale."},
        {
            "type": "text",
            "text": TESTO_LUNGO_DEL_MANUALE,   # migliaia di token riusati ogni volta
            "cache_control": {"type": "ephemeral"},
        },
    ],
    messages=[{"role": "user", "content": "Riassumi la sezione sui recessi."}],
)
print(r.usage)  # mostra i token letti dalla cache

Nel campo usage vedrai i token serviti dalla cache: l'input «in cache» costa molto meno di quello normale, e per applicazioni che riusano lo stesso contesto il risparmio è enorme. La cache ha una durata breve (si rinnova ad ogni uso), quindi è perfetta per sessioni intense e ripetute.

Errori comuni e soluzioni

  • 401 authentication_error → chiave assente o errata: controlla la variabile ANTHROPIC_API_KEY.
  • 400 «max_tokens is required» → ricorda che max_tokens è obbligatorio in ogni chiamata.
  • 429 rate_limit / overloaded → troppe richieste: implementa un retry con attesa crescente (l'SDK ha già una logica di backoff configurabile).
  • Il tool non viene chiamato → migliora description e input_schema: Claude sceglie lo strumento in base a quanto sono chiari.

Quando usare Claude e quando no

Claude eccelle su codice, testi lunghi e ragionamento; per questi casi è una delle scelte migliori sul mercato. Se però ti servono costi minimi su altissimi volumi o vincoli di esecuzione locale, valuta modelli più economici o open (come DeepSeek o i modelli via Ollama) e tieni Claude per i compiti dove la qualità conta davvero. Il bello dell'API «a messaggi» è che la struttura è simile tra i vari fornitori: imparata qui, la riadatti altrove con poche modifiche. Da qui puoi proseguire con i structured outputs, gli agenti multi-strumento e l'integrazione con un sistema RAG come quello descritto nelle nostre guide.