Costruire un piccolo assistente IA che non si limiti a chiacchierare, ma sappia usare strumenti — consultare un calendario, fare un calcolo, interrogare un database — è oggi alla portata di chiunque sappia un po' di Python. In questa guida partiamo da zero con le API di Claude, i modelli di Anthropic, fino a costruire un agente funzionante con il cosiddetto tool use.

A chi serve e cosa ti occorre

Questa guida è pensata per chi ha basi minime di Python (sai cos'è una funzione e come si esegue uno script) e vuole iniziare a programmare con l'IA generativa. Alla fine avrai: una prima chiamata API funzionante, la consapevolezza dei costi e un agente che chiama una tua funzione e usa il risultato per rispondere.

Ti servono tre cose reali:

  • Python 3.9 o superiore installato sul tuo computer (Windows, macOS o Linux).
  • Un account su console.anthropic.com e una API key (si genera dalla sezione “API Keys”).
  • Un piccolo credito sul conto: le API sono a pagamento a consumo, ma per fare pratica bastano pochi euro.

Quale modello scegliere e quanto costa

Anthropic offre tre famiglie di modelli, con prezzi diversi per milione di token (un token è circa tre quarti di una parola). Ecco i principali, con il costo di input e output per milione di token:

ModelloIDInput / OutputIdeale per
Claude Opus 4.8claude-opus-4-85 / 25 $compiti difficili, agenti, coding
Claude Sonnet 4.6claude-sonnet-4-63 / 15 $equilibrio tra costo e qualità
Claude Haiku 4.5claude-haiku-4-51 / 5 $compiti semplici e veloci

Per imparare conviene partire da Haiku (economico) e passare a Opus solo quando serve davvero più intelligenza. Negli esempi useremo modelli diversi a seconda del compito. Perché Claude e non un'altra API? Per il tool use e gli agenti, i modelli Anthropic sono tra i più affidabili nel seguire le istruzioni e nel decidere quando usare uno strumento — ma i concetti di questa guida valgono, con piccole differenze, anche per altri fornitori.

Passo 1: installare l'SDK e impostare la chiave

Apri il terminale e installa la libreria ufficiale:

pip install anthropic

Imposta poi la tua chiave come variabile d'ambiente, così da non scriverla nel codice (regola d'oro: le chiavi non si mettono mai dentro i file sorgente):

# su macOS / Linux
export ANTHROPIC_API_KEY="la-tua-chiave"

# su Windows (PowerShell)
setx ANTHROPIC_API_KEY "la-tua-chiave"

Passo 2: la prima chiamata

Crea un file primo.py e incolla questo codice. L'SDK legge automaticamente la chiave dalla variabile d'ambiente:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-haiku-4-5",
    max_tokens=1000,
    messages=[
        {"role": "user", "content": "Spiega in 3 frasi cos'e' un'API."}
    ],
)

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

Eseguilo con python primo.py. Dovresti vedere una risposta in poche righe. Nota due cose: max_tokens limita la lunghezza della risposta (e quindi il costo), e response.content è una lista di “blocchi” — controlliamo sempre il tipo prima di leggere il testo.

Bastano poche righe di Python per la prima risposta dal modello.

Passo 3: aggiungere il ragionamento (adaptive thinking)

Per i compiti che richiedono ragionamento — matematica, logica, pianificazione — i modelli recenti supportano il pensiero adattivo: il modello decide da solo quanto “riflettere” prima di rispondere. Si attiva così:

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # low | medium | high
    messages=[
        {"role": "user", "content": "Se un treno parte alle 9:40 e impiega 2h35m, a che ora arriva? Ragiona passo passo."}
    ],
)
for block in response.content:
    if block.type == "text":
        print(block.text)

Attenzione: sui modelli Opus più recenti il vecchio parametro budget_tokens non è più valido e i parametri come temperature non vanno passati: si usano thinking e effort.

Passo 4: il cuore della guida, un agente con tool use

Il tool use permette al modello di chiamare funzioni che scrivi tu. Il modello non esegue il codice: dice “voglio usare lo strumento X con questi argomenti”, tu lo esegui e gli restituisci il risultato. L'SDK offre un tool runner che gestisce automaticamente questo ciclo. Definiamo uno strumento che calcola il prezzo finale con l'IVA:

import anthropic
from anthropic import beta_tool

client = anthropic.Anthropic()

@beta_tool
def prezzo_con_iva(prezzo_netto: float, aliquota: float = 22) -> str:
    """Calcola il prezzo finale applicando l'IVA.

    Args:
        prezzo_netto: prezzo senza IVA in euro.
        aliquota: aliquota IVA in percentuale (default 22).
    """
    finale = prezzo_netto * (1 + aliquota / 100)
    return f"{finale:.2f} euro (IVA {aliquota}%)"

runner = client.beta.messages.tool_runner(
    model="claude-opus-4-8",
    max_tokens=1500,
    tools=[prezzo_con_iva],
    messages=[
        {"role": "user", "content": "Quanto costa con l'IVA un prodotto da 80 euro netti?"}
    ],
)

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

Risultato atteso: il modello capisce che deve usare lo strumento, lo chiama con prezzo_netto=80, riceve “97.60 euro” e formula una risposta in linguaggio naturale, ad esempio: “Il prezzo finale è 97,60 euro, IVA al 22% inclusa.” Il bello è che la decisione di usare lo strumento la prende il modello, non tu.

Errori comuni e come risolverli

  • AuthenticationError / 401: la chiave non è impostata o è sbagliata. Verifica la variabile ANTHROPIC_API_KEY e riapri il terminale dopo averla impostata.
  • RateLimitError / 429: troppe richieste. L'SDK riprova in automatico; se persiste, rallenta o aumenta i limiti dalla console.
  • 400 con budget_tokens o temperature: stai usando parametri non più supportati su Opus 4.8. Rimuovili e usa thinking ed effort.
  • Risposta troncata (stop_reason uguale a max_tokens): aumenta max_tokens.

Varianti e come proseguire

Da qui puoi crescere in diverse direzioni. Se l'output deve essere lungo (oltre ~16.000 token), usa lo streaming con client.messages.stream(...) per evitare timeout. Se lavori in TypeScript, Go, Java o altri linguaggi, esistono SDK ufficiali con la stessa logica. Se vuoi più strumenti, aggiungili semplicemente alla lista tools: il modello sceglierà quali usare e in che ordine.

Per controllare i costi prima di inviare, usa client.messages.count_tokens(...) per stimare i token. E ricorda la regola di metodo: parti dal modello più piccolo che risolve il problema, e sali di livello solo se la qualità non basta. Con queste basi hai tutto per costruire assistenti che non solo rispondono, ma agiscono.