Come costruire un chatbot AI con l'API Claude nel 2026

In passato, costruire un chatbot significava gestire classificatori di intenti, alberi di dialogo e una mole enorme di casi particolari. Con un’API moderna per modelli linguistici, è il modello stesso a svolgere la parte più complessa — comprendere e rispondere — mentre il vostro compito si riduce a realizzare la logica di integrazione attorno ad esso. Con l’API Claude potete avere un chatbot davvero performante operativo in molto meno di un’ora.

Questa guida illustra concetti e codice: configurazione iniziale, gestione di una conversazione, controllo del comportamento, streaming delle risposte e ottimizzazione dei costi.

Passo 1: Configurazione iniziale

Avete bisogno di due elementi: una chiave API e un SDK.

1. Ottenere una chiave API — create un account nella Console Anthropic e generate una chiave API. Tenetela segreta: memorizzatela in una variabile d’ambiente, mai codificarla direttamente nel codice né includerla nei repository di controllo versione.
2. Installare l’SDK — Anthropic fornisce SDK ufficiali. Per Python:

pip install anthropic

(È disponibile anche un SDK per Node.js; i concetti descritti di seguito sono identici.)

Passo 2: Il vostro primo messaggio

Il cuore dell’API Claude è l’ API Messages. Inviate una lista di messaggi; Claude restituisce il successivo. Ecco la chiamata più semplice possibile:

from anthropic import Anthropic

client = Anthropic() # reads the ANTHROPIC_API_KEY environment variable

response = client.messages.create(
 model="claude-sonnet-4-6",
 max_tokens=1024,
 messages=[
 {"role": "user", "content": "Hello! What can you help me with?"}
 ],
)

print(response.content[0].text)

Questo è un chatbot funzionante — sebbene privo di memoria. model specifica quale versione di Claude utilizzare, max_tokens limita la lunghezza della risposta e messages rappresenta la cronologia della conversazione fino a quel momento.

Passo 3: Aggiungere la memoria

L’esempio sopra non prevede alcuna memoria: ogni chiamata è indipendente. Per condurre una conversazione reale, tu dovete conservare la cronologia e reinviarla ad ogni turno. L’API stessa è senza stato (stateless) — conosce soltanto ciò che le inviate.

Il pattern consiste nel mantenere una messages lista, aggiungervi ogni messaggio dell’utente e ogni risposta di Claude, e trasmettere l’intera lista ad ogni chiamata.

from anthropic import Anthropic

client = Anthropic()
messages = []

while True:
 user_input = input("You: ")
 if user_input.lower() == "quit":
 break

 messages.append({"role": "user", "content": user_input})

 response = client.messages.create(
 model="claude-sonnet-4-6",
 max_tokens=1024,
 messages=messages,
 )

 reply = response.content[0].text
 print(f"Claude: {reply}")

 messages.append({"role": "assistant", "content": reply})

Ora è un vero chatbot — ricorda tutto ciò che è stato detto in precedenza nella conversazione, poiché tale cronologia viene trasmessa ad ogni turno.

Passo 4: Definire la personalità con un prompt di sistema

Un assistente generico raramente è ciò che desiderate. Il prompt di sistema definisce il ruolo, il tono e le regole del bot. Viene passato come parametro separato, system non come messaggio.

SYSTEM_PROMPT = """You are a friendly support assistant for a coffee
subscription service. Be warm, concise, and helpful. If a customer asks
about something you don't know, tell them you'll connect them to a human
agent. Never discuss competitors."""

response = client.messages.create(
 model="claude-sonnet-4-6",
 max_tokens=1024,
 system=SYSTEM_PROMPT,
 messages=messages,
)

Il prompt di sistema è il tuo principale strumento per modellare il comportamento del bot: dedica tempo alla sua stesura. Specifica con chiarezza il ruolo, il tono, come deve comportarsi in caso di incertezza e quali sono i limiti invalicabili.

Passo 5: trasmettere la risposta in streaming

Negli esempi precedenti, si attende l’intera risposta prima che venga visualizzato qualsiasi contenuto. Le vere interfacce chat invece trasmettono i testi in streaming — cioè il testo arriva parola per parola. L’SDK rende questa operazione semplicissima:

with client.messages.stream(
 model="claude-sonnet-4-6",
 max_tokens=1024,
 system=SYSTEM_PROMPT,
 messages=messages,
) as stream:
 for text in stream.text_stream:
 print(text, end="", flush=True)

Lo streaming non accelera la generazione, ma rende il bot percepito notevolmente più reattivo, poiché l’utente vede l’output immediatamente.

Passo 6: ridurre i costi mediante la cache dei prompt

Le chiamate API vengono fatturate in base al numero di token, e un chatbot invia ripetutamente molti testi identici ad ogni turno — il prompt di sistema e una cronologia delle conversazioni che cresce continuamente. La cache dei prompt Consente di contrassegnare le parti stabili del prompt affinché l’API le riutilizzi invece di rielaborarle, riducendo sensibilmente sia i costi che la latenza.

Aggiungi un marcatore di cache al contenuto che desideri memorizzare nella cache — tipicamente il prompt di sistema e qualsiasi contesto lungo e fisso:

response = client.messages.create(
 model="claude-sonnet-4-6",
 max_tokens=1024,
 system=[
 {
 "type": "text",
 "text": SYSTEM_PROMPT,
 "cache_control": {"type": "ephemeral"},
 }
 ],
 messages=messages,
)

Per qualsiasi chatbot destinato a gestire traffico reale, abilita fin dall’inizio la cache dei prompt: è una delle ottimizzazioni con maggiore impatto disponibili e non comporta alcun costo aggiuntivo.

Scelta del modello

Claude è disponibile in diverse versioni. Come regola generale:

• Un modello veloce e bilanciato (ad esempio la versione Sonnet) è la scelta predefinita più indicata per la maggior parte dei chatbot — qualità elevata, buona velocità e costo ragionevole.
• Il modello più potente (la versione Opus) è giustificato quando il bot deve affrontare ragionamenti complessi o compiti articolati.
• Un modello più piccolo e veloce (la versione Haiku) è ideale per chatbot semplici e ad alto volume, dove velocità e costo sono prioritari.

Inizia sempre dalla versione bilanciata e passa a una versione superiore o inferiore solo dopo aver analizzato i dati reali sull’utilizzo.

Passaggio in produzione

Il codice sopra riportato rappresenta il nucleo funzionante. Per una vera distribuzione, aggiungi:

• Uno strato web — incapsula la logica in un endpoint API e collega un’interfaccia chat.
• Limiti sulla cronologia — le conversazioni crescono indefinitamente; limita o riassume i turni più vecchi per evitare che i prompt diventino eccessivamente lunghi.
• Gestione degli errori — gestisci i limiti di frequenza e i guasti temporanei implementando tentativi ripetuti.
• Conoscenza — per consentire al bot di rispondere utilizzando i tuoi dati, aggiungi la generazione assistita da recupero (retrieval-augmented generation) in modo che il bot recuperi automaticamente i documenti pertinenti.
• Sicurezza — convalida gli input e definisci chiaramente i limiti nel prompt di sistema.

Gestisci errori e limiti di frequenza prima che gli utenti li riscontrino

Un chatbot che funziona sul tuo laptop potrebbe comunque interrompersi in produzione non appena viene raggiunto un traffico reale. L'API di Claude restituisce due tipi di errore, ciascuno dei quali richiede una risposta diversa. Il primo è un errore transiente dell'API — si manifesta come un'eccezione accompagnata da un codice di stato HTTP. Il secondo è un rifiuto, ovvero una risposta perfettamente valida che semplicemente declina la richiesta. Confondere questi due casi rappresenta il bug di affidabilità più comune che riscontriamo nel codice iniziale dei chatbot.

Sul fronte degli errori transitori, due codici di stato sono particolarmente rilevanti:

• 429 (limite di frequenza) — hai superato la quota di richieste al minuto o di token al minuto associata al tuo account. La risposta include un header retry-after che indica esattamente quanti secondi devi attendere. Rispettalo con precisione: aspettare meno tempo comporta semplicemente un altro errore 429.
• 529 (sovraccarico) — l'API di Anthropic è temporaneamente saturata per tutti gli utenti. Non puoi prevenire questo errore mediante codice, e le richieste respinte con codice 529 non vengono fatturate. Esegui un backoff e riprova; non inviare ripetutamente richieste a un endpoint sovraccarico.
• 500 (errore del server) — un raro guasto interno. Trattalo come un 529: riprova con backoff.

La buona notizia è che gli SDK ufficiali già gestiscono automaticamente i tentativi di ripetizione per gli errori 429 e 5xx, applicando un backoff esponenziale (il valore predefinito è due tentativi). Per un chatbot in produzione, aumenta questo limite e lascia che sia l'SDK a occuparsene, invece di scrivere manualmente un ciclo di ripetizione:

• Aumenta max_retries sul client (un valore compreso tra 4 e 5 è ragionevole per un chatbot rivolto agli utenti).
• Cattura le eccezioni tipizzate — RateLimitError, OverloadedError, APIError — piuttosto che effettuare confronti basati su stringhe nel testo dell'errore, che smetterebbero di funzionare in modo silenzioso se il testo venisse modificato.
• Quando i tentativi di ripetizione vengono infine esauriti, mostra all'utente un messaggio tranquillo del tipo «Al momento sono un po’ impegnato, riprova tra un momento», invece di visualizzare uno stack trace.

I rifiuti costituiscono un percorso completamente distinto. Quando una risposta viene restituita con stop_reason: "refusal", la richiesta è andata a buon fine — Claude ha rifiutato di rispondere per motivi di sicurezza e, sui modelli attuali, non vieni addebitato quando non viene generato alcun output. È fondamentale che tu non invii nuovamente la stessa conversazione: il rifiuto si ripeterà. Invece, rimuovi o riformula il turno che lo ha innescato, oppure reimposta la cronologia della conversazione, quindi comunica chiaramente all'utente quanto accaduto. Poiché un rifiuto è un campo presente nella risposta e non un'eccezione, un codice che controlla soltanto i campi end_turn e tool_use potrebbe lasciarlo passare inosservato, restituendo una risposta vuota e confusa. Aggiungi sempre un ramo esplicito per gestirlo.

Implementa questi tre comportamenti — ripetizione con backoff, gestione tipizzata delle eccezioni e gestione esplicita dei rifiuti — e il tuo chatbot si degraderà in modo controllato sotto carico, anziché fallire clamorosamente davanti alle persone per le quali lo hai progettato.

Domande frequenti

Come creo un chatbot con l’API Claude?

Installa l’SDK di Anthropic, ottieni una chiave API ed effettua una chiamata all’API Messages: invia un elenco di messaggi e Claude restituirà una risposta. Per renderlo conversazionale, conserva tu stesso la cronologia dei messaggi e includila ad ogni nuovo turno. Aggiungi un prompt di sistema per definirne la personalità e attiva lo streaming per garantire una sensazione di reattività.

L’API Claude ricorda i messaggi precedenti?

No — l’API è senza stato (stateless). Conosce soltanto ciò che le invii in una determinata richiesta. Per dotare un chatbot di memoria, la tua applicazione deve archiviare la cronologia della conversazione e includerla nell’elenco messages ad ogni chiamata.

Cos’è un prompt di sistema?

Il prompt di sistema è un’istruzione separata che definisce il ruolo, il tono e le regole del chatbot — ad esempio: «Sei un assistente di supporto conciso; in caso di dubbi, trasferisci la richiesta a un operatore umano». Viene passato come parametro system ed è il principale mezzo per modellare il comportamento del bot.

Quanto costa eseguire un chatbot Claude?

Il costo dipende dal modello scelto e dal numero di token elaborati. Un modello bilanciato risulta economico per un normale traffico conversazionale. Poiché i chatbot inviano nuovamente ad ogni turno il prompt di sistema e la cronologia in continua espansione, abilitare la cache dei prompt può ridurre significativamente i costi — infatti riutilizza le parti stabili del prompt anziché rielaborarle.

Quale modello Claude devo usare per un chatbot?

Per la maggior parte dei chatbot, inizia con un modello veloce e bilanciato (versione Sonnet) — offre elevate prestazioni a una velocità e un costo ragionevoli. Usa il modello più potente per compiti di ragionamento complesso e un modello più piccolo e veloce per chatbot semplici ad alto volume.

Cosa significano gli errori 429 e 529 provenienti dall'API di Claude?

Un codice 429 indica che hai raggiunto il limite di frequenza del tuo account (richieste o token al minuto); la risposta include un header retry-after che specifica per quanto tempo devi attendere. Un codice 529 indica che l'API di Anthropic è temporaneamente sovraccarica per tutti gli utenti — tali richieste non vengono fatturate e non possono essere evitate tramite codice. Entrambi richiedono un backoff esponenziale, che gli SDK ufficiali applicano automaticamente per impostazione predefinita.

Come deve gestire il mio chatbot un rifiuto di Claude?

Un rifiuto viene restituito come risposta normale e valida con stop_reason: "refusal", non come un errore, e non ti viene addebitato alcun costo qualora non venga prodotto alcun output. Non ritentare la stessa richiesta identica — verrà nuovamente rifiutata. Rimuovi o riformula il messaggio che l'ha innescata (oppure reimposta la conversazione), quindi fornisci all'utente una spiegazione chiara e amichevole. A partire da Opus 4.7, la risposta include inoltre un campo stop_details che indica la categoria della policy violata.

Devo implementare manualmente la logica di ripetizione per l'API di Claude?

Di solito no. Gli SDK ufficiali di Anthropic già gestiscono automaticamente i tentativi di ripetizione per gli errori 429 e 5xx applicando un backoff esponenziale, con un valore predefinito di due tentativi. Per un chatbot rivolto agli utenti, la configurazione più semplice ed efficace consiste nell'aumentare max_retries a circa quattro o cinque sul client e nel catturare le eccezioni tipizzate (come ad esempio RateLimitError e OverloadedError) anziché implementare manualmente un ciclo di backoff o effettuare confronti basati su stringhe negli errori.

Conclusione

Creare un chatbot con l’API Claude riguarda soprattutto l’ingegnerizzazione dell’infrastruttura, non l’intelligenza artificiale. Il modello si occupa della comprensione e della generazione della risposta; spetta a te fornire il ciclo di gestione. Conserva una messages cronologia e includila ad ogni turno per garantire la memoria, usa un system prompt di sistema per definirne la personalità, attiva lo streaming per una sensazione di reattività e abilita la cache dei prompt per controllare i costi.

Questo nucleo fondamentale richiede davvero circa un’ora di lavoro. Il percorso verso la produzione consiste nelle consuete attività ingegneristiche che lo circondano — uno strato web, la gestione della cronologia, la gestione degli errori e RAG se il bot deve accedere ai tuoi dati. Inizia con il semplice ciclo descritto sopra, fai in modo che il bot cominci a rispondere e costruisci progressivamente intorno ad esso.