Costruire un agente IA non significa per forza scrivere centinaia di righe di codice. Con n8n, la piattaforma open-source di automazione, si puo' assemblare un agente che ragiona, usa strumenti e risponde agli utenti collegando blocchi visuali. In questa guida partiamo da zero: installiamo n8n, creiamo un agente basato su un modello come GPT-5 o Claude, gli diamo degli strumenti e infine lo trasformiamo in un bot Telegram funzionante.

A chi serve questa guida e cosa otterrai

La guida e' pensata per chi conosce un po' di informatica - sa cos'e' un terminale e un'API - ma non e' necessariamente uno sviluppatore. Al termine avrai un agente IA che riceve un messaggio, decide in autonomia se rispondere direttamente o usare uno strumento (per esempio una ricerca web o un calcolo), e restituisce una risposta. Lo stesso schema si riusa per assistenti interni, automazioni aziendali e bot di supporto.

Prerequisiti reali: un computer con Windows, macOS o Linux; Docker installato (oppure Node.js per la versione via npx); una chiave API di un fornitore di modelli (OpenAI, Anthropic o Google); circa 30-45 minuti. n8n e' gratuito in versione self-hosted; pagherai solo il consumo dell'API del modello, in genere pochi centesimi per le prove.

Quale piattaforma e modello scegliere

n8n si puo' usare in due modi: la versione self-hosted, gratuita e installabile sul proprio computer o server, e n8n Cloud, a pagamento ma senza installazione. Per imparare conviene la versione self-hosted con Docker: e' gratis, gira in locale e ti da' pieno controllo.

Sul modello, ecco i candidati principali per il "cervello" dell'agente:

  • OpenAI (GPT-5 / GPT-5.5): ottima capacita' di ragionamento e uso degli strumenti, documentazione enorme, integrazione nativa in n8n. Costo a consumo. E' la prima scelta consigliata per iniziare, per affidabilita' e supporto.
  • Anthropic (Claude Sonnet / Opus): molto solido nel seguire istruzioni complesse e nel coding, eccellente con contesti lunghi. Alternativa ideale se lavori con molto testo.
  • Google Gemini: buon rapporto qualita'-prezzo e contesto ampio, con un piano gratuito generoso utile per le prove.
  • Modelli open via Ollama: gratis e privati, girano in locale, ma richiedono hardware adeguato e in genere ragionano meno bene sugli strumenti. Buoni per la privacy, meno per gli agenti complessi.

Per questa guida usiamo OpenAI come esempio, ma cambiare modello e' questione di un nodo diverso.

n8n collega modelli, strumenti e servizi esterni in un unico flusso di lavoro.

Installare n8n in locale con Docker

Il modo piu' pulito di installare n8n e' con Docker. Se hai gia' Docker, apri il terminale e lancia:

docker volume create n8n_data

docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -v n8n_data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

Il volume n8n_data serve a non perdere i tuoi flussi quando il container si ferma. Quando il terminale mostra che n8n e' pronto, apri il browser su http://localhost:5678 e crea l'account locale (resta sul tuo computer).

Se preferisci non usare Docker e hai Node.js installato, l'alternativa rapida e':

npx n8n

Anche in questo caso l'interfaccia sara' su http://localhost:5678.

Creare il workflow: trigger, AI Agent e strumenti

Dentro n8n, crea un nuovo workflow. Ti servono pochi nodi:

  1. Trigger: e' il punto di partenza. Per provare subito, aggiungi il nodo Chat Trigger ("When chat message received"): apre una chat di test integrata. In seguito potrai sostituirlo con un Webhook o con Telegram.
  2. AI Agent: e' il nodo centrale. Cercalo tra i nodi e aggiungilo dopo il trigger. Questo nodo orchestra il ragionamento: riceve il messaggio, decide cosa fare e, se serve, chiama gli strumenti.
  3. Chat Model: e' il modello collegato all'agente. Si aggancia all'AI Agent nella sua sezione dedicata.
  4. Tools: gli strumenti che l'agente puo' usare (calcolatrice, ricerca, chiamate HTTP, ecc.).

Nel campo "System Prompt" dell'AI Agent definisci il comportamento dell'agente. Un esempio:

Sei l'assistente di AI Notizie. Rispondi in italiano, in modo chiaro e conciso. Se ti viene chiesto un calcolo, usa lo strumento Calculator. Se devi recuperare informazioni aggiornate, usa lo strumento di ricerca. Non inventare dati: se non sai, dillo.

Collegare un modello e dare strumenti all'agente

Aggancia all'AI Agent un nodo OpenAI Chat Model. Alla prima configurazione ti chiedera' le credenziali: incolla la tua chiave API di OpenAI (la generi dalla dashboard della piattaforma) e seleziona il modello, ad esempio gpt-5. Salva le credenziali: n8n le riusa nei prossimi flussi.

Ora diamo all'agente delle capacita'. Collega uno o piu' nodi-strumento alla sezione "Tool" dell'AI Agent:

  • Calculator: per i conti, cosi' il modello non sbaglia l'aritmetica.
  • HTTP Request Tool: per interrogare un'API esterna (meteo, prezzi, dati interni). Nella descrizione dello strumento spiega all'agente quando usarlo: e' quel testo che il modello legge per decidere.
  • Memory (Window Buffer Memory): per ricordare i messaggi precedenti della conversazione.

La logica e' questa: l'agente legge la richiesta, guarda gli strumenti disponibili e le loro descrizioni, e decide se rispondere subito o invocare uno strumento, leggerne il risultato e poi rispondere. E' il cuore di un agente "vero".

Testare l'agente e gestire la memoria

Apri la chat di test del Chat Trigger e scrivi qualcosa che obblighi l'agente a ragionare, ad esempio:

Quanto fa il 18% di 2.450 euro? E spiegami in una riga a cosa serve quel calcolo per una fattura.

Se tutto e' collegato, vedrai l'agente invocare lo strumento Calculator per la parte numerica e poi comporre la risposta in italiano. Nei log di n8n (cliccando sui singoli nodi) puoi vedere esattamente cosa ha pensato e quali strumenti ha chiamato: e' lo strumento migliore per capire e correggere il comportamento.

La memoria fa la differenza fra un agente "smemorato" e uno che tiene il filo. Con il nodo Window Buffer Memory l'agente ricorda gli ultimi scambi: prova a fare una domanda di follow-up senza ripetere il contesto e verifica che risponda coerentemente.

Trasformarlo in un bot Telegram

Una volta che l'agente funziona, dargli un volto pubblico e' semplice. Su Telegram crea un bot scrivendo a BotFather, che ti restituira' un token. In n8n:

  1. Sostituisci (o affianca) il Chat Trigger con un nodo Telegram Trigger, inserendo il token del bot nelle credenziali.
  2. Collega l'output del Telegram Trigger all'AI Agent, mappando il testo del messaggio in ingresso.
  3. Dopo l'AI Agent, aggiungi un nodo Telegram (Send Message) che rimanda all'utente la risposta dell'agente, usando l'ID della chat ricevuto dal trigger.
  4. Attiva il workflow con l'interruttore in alto a destra: da quel momento il bot risponde ai messaggi reali.

Con lo stesso schema puoi collegare l'agente a un Webhook (per integrarlo in un sito), a Slack o a un modulo email.

Errori comuni e come risolverli

Ecco i problemi piu' frequenti, con la soluzione:

  • "Authentication failed" sul modello: la chiave API e' sbagliata o senza credito. Verifica la chiave e che l'account abbia fondi disponibili.
  • L'agente non usa mai gli strumenti: la descrizione dello strumento e' troppo vaga. Rendila esplicita ("Usa questo strumento per...") e cita nel system prompt quando ricorrervi.
  • "Workflow could not be activated" con il Webhook/Telegram: in locale il trigger funziona solo con n8n in esecuzione e, per Telegram, serve che n8n sia raggiungibile da internet. In sviluppo usa il pulsante "Test"; in produzione esponi n8n con un dominio o un servizio di tunneling.
  • Risposte tagliate o loop infiniti: imposta un limite di iterazioni nell'AI Agent e riduci la temperatura del modello per risposte piu' stabili.

Varianti e quando non usare n8n

Da qui puoi crescere: aggiungere uno strumento di ricerca web per dati aggiornati, collegare un database vettoriale per fare RAG sui tuoi documenti, oppure orchestrare piu' agenti specializzati. n8n e' ideale quando vuoi integrare l'IA con molti servizi esterni e vedere il flusso a colpo d'occhio.

Quando conviene un'altra strada? Se ti serve un agente molto sofisticato con logica complessa e test automatici, scrivere il codice con una libreria dedicata (ad esempio gli SDK ufficiali dei modelli) offre piu' controllo. E se hai bisogno solo di una singola chiamata a un modello, n8n e' sovradimensionato: basta una semplice richiesta API. Ma per la grande maggioranza delle automazioni con IA - quelle che collegano modelli, dati e azioni - n8n e' uno dei modi piu' veloci per passare dall'idea a un agente funzionante.