Un "agente IA" non è per forza un progetto da grande azienda. Con n8n, una piattaforma di automazione open source, puoi costruire in un pomeriggio un assistente che legge le email in arrivo, le riassume con un modello linguistico e ti manda un avviso ordinato, oppure che risponde alle domande dei clienti pescando dai tuoi documenti. Questa guida ti porta dall'installazione al primo agente funzionante.

A chi serve e cosa ti serve prima di iniziare

La guida è pensata per chi vuole automatizzare compiti ripetitivi: titolari di piccole attività, professionisti, sviluppatori alle prime armi con gli agenti. Non serve essere programmatori esperti, ma è utile sapersi muovere con il terminale. I prerequisiti reali:

  • un computer con Docker installato (Windows, macOS o Linux) oppure, in alternativa, un account su n8n Cloud;
  • una chiave API di un modello linguistico: OpenAI (GPT-5.x), Anthropic (Claude Sonnet 4.x) o, per restare gratis e in locale, Ollama;
  • circa un'ora di tempo.

Quale modello scegliere per l'agente

n8n è agnostico rispetto al modello: puoi collegare quello che preferisci. Per orientarti:

  • OpenAI GPT-5.x: ottimo per ragionamento e uso di strumenti, ideale se vuoi affidabilità. A pagamento, a consumo.
  • Anthropic Claude Sonnet 4.x: molto solido su istruzioni lunghe e testi articolati. A pagamento, a consumo.
  • Ollama (modelli locali come Llama o Qwen): gratuito e privato, gira sul tuo PC; richiede però una macchina capace e offre prestazioni inferiori sui compiti complessi.

Consiglio: per il primo agente parti da un modello commerciale come GPT-5.x o Claude Sonnet, così elimini la variabile "hardware" e capisci come funziona il flusso. Passa a Ollama quando vuoi azzerare i costi o tenere tutto in casa per motivi di privacy.

Passo 1 – Installare n8n con Docker

Il modo più pulito per avere n8n in locale è Docker. Apri il terminale ed esegui, come indicato dalla documentazione ufficiale:

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 primo comando crea un volume per conservare i tuoi workflow; il secondo avvia n8n. Quando vedi il messaggio di avvio, apri il browser su http://localhost:5678 e crea l'account locale. Se usi n8n Cloud, salta questo passo e accedi dal sito.

n8n mostra i flussi come nodi collegati: ogni nodo è un passaggio dell'automazione.

Passo 2 – Creare il workflow e aggiungere l'AI Agent

  1. Dalla schermata principale clicca su Create Workflow.
  2. Aggiungi un nodo iniziale (il "Trigger"). Per provare, scegli Manual Trigger; più avanti potrai usare un trigger su email, Telegram o un Webhook.
  3. Clicca sul "+" e cerca il nodo AI Agent (nella sezione Advanced AI). È il cuore del sistema.

Il nodo AI Agent ha tre attacchi da configurare: il Chat Model (il cervello), gli eventuali Tools (gli strumenti) e la Memory (la memoria della conversazione).

Passo 3 – Collegare il modello

Sotto l'AI Agent, aggiungi il nodo del modello scelto, ad esempio OpenAI Chat Model, Anthropic Chat Model oppure Ollama Chat Model. Ti verrà chiesto di inserire le credenziali:

  • per OpenAI o Anthropic, incolla la tua chiave API nel campo dedicato e seleziona il modello (es. gpt-5.5 o claude-sonnet-4-6);
  • per Ollama, indica l'indirizzo del servizio locale (di norma http://localhost:11434) dopo aver scaricato un modello con ollama pull llama3.1.

Passo 4 – Dare un compito all'agente

Nel nodo AI Agent imposta il System Prompt, cioè le istruzioni di base. Ecco un esempio copiabile per un assistente che riassume e classifica testi:

"Sei un assistente che riceve un testo e produce: 1) un riassunto in 3 punti; 2) una categoria tra [urgente, informativo, commerciale]; 3) un'azione consigliata in una riga. Rispondi sempre in italiano e in formato elenco."

Collega il Manual Trigger all'AI Agent, clicca su Test workflow e, nel campo di input, incolla un testo di prova (ad esempio il corpo di una email). Il risultato atteso è una risposta strutturata con riassunto, categoria e azione.

Passo 5 – Aggiungere strumenti e memoria

Qui un agente diventa davvero utile. Collegando dei Tools all'AI Agent gli dai la possibilità di compiere azioni, non solo di rispondere:

  • il nodo HTTP Request come tool gli permette di interrogare un'API esterna (meteo, cambi, un tuo gestionale);
  • i nodi Gmail, Telegram o Slack gli consentono di inviare messaggi;
  • un nodo Vector Store (con un database come Qdrant o il vettoriale integrato) trasforma l'agente in un sistema di risposta sui tuoi documenti (RAG).

Aggiungi infine un nodo Memory (ad esempio Window Buffer Memory) se vuoi che l'agente ricordi i messaggi precedenti in una conversazione.

Un esempio completo: il triage delle email

Mettiamo insieme i pezzi in un caso reale e utile: un agente che ogni mattina legge le nuove email, le classifica e ti manda un riepilogo su Telegram. Ecco il flusso da costruire:

  1. Trigger Gmail ("On message received"): si attiva a ogni nuova email. In alternativa, un Schedule Trigger che parte alle 8:00 e legge le email della notte.
  2. AI Agent con il System Prompt visto sopra, che riceve oggetto e corpo del messaggio.
  3. Un tool HTTP Request facoltativo, se vuoi che l'agente arricchisca l'analisi con dati esterni.
  4. Telegram ("Send message"): invia il riassunto strutturato sul tuo telefono.

Per passare il contenuto dell'email all'agente, nel campo di input usi un'espressione che richiama il nodo precedente, ad esempio:

Oggetto: {{ $json.subject }}
Testo: {{ $json.textPlain }}

La doppia parentesi graffa è la sintassi con cui n8n inserisce dinamicamente i dati che arrivano dal nodo precedente. Il risultato, dopo il test, sarà un messaggio Telegram del tipo: "Riassunto: il cliente chiede un preventivo per 50 licenze. Categoria: commerciale. Azione consigliata: rispondere entro oggi con il listino". È un assistente che ti fa risparmiare la lettura di decine di email ogni mattina.

Attivare il workflow in produzione

Finché lavori con il Manual Trigger, il flusso parte solo quando premi "Test". Per renderlo automatico devi sostituire il trigger con uno reale (Gmail, Schedule, Webhook) e poi attivare l'interruttore Active in alto a destra nell'editor. Da quel momento n8n eseguirà il workflow da solo, secondo l'evento scelto. Se usi l'installazione locale con Docker, ricorda che il flusso gira solo quando il container è acceso: per un servizio sempre attivo conviene ospitare n8n su un piccolo server o su n8n Cloud. Tieni d'occhio anche la sezione Executions, dove trovi lo storico delle esecuzioni con eventuali errori, utilissima per il debug.

Errori comuni e come risolverli

  • "Port 5678 already in use": hai già un'istanza attiva. Chiudila o avvia n8n su un'altra porta cambiando il parametro -p, ad esempio -p 5679:5678.
  • "401 / invalid API key": la chiave del modello è errata o senza credito. Rigenerala dal pannello del provider e controlla il saldo.
  • "Rate limit exceeded": troppe richieste in poco tempo. Inserisci un nodo Wait tra le chiamate o passa a un piano superiore.
  • L'agente non usa lo strumento: rendi il System Prompt più esplicito ("usa lo strumento X quando serve Y") e assegna un nome e una descrizione chiari a ciascun tool.

Varianti, alternative e prossimi passi

Una volta capito il meccanismo, puoi sostituire il Manual Trigger con un Webhook per far partire l'agente da un sito, o con un trigger su Gmail per processare ogni nuova email. Se preferisci non gestire l'infrastruttura, esistono alternative come Make e Zapier (più semplici ma a pagamento e meno flessibili) o piattaforme specializzate negli agenti come Flowise e Dify. n8n resta però la scelta migliore quando vuoi unire automazione classica e IA con costi sotto controllo, grazie all'auto-hosting gratuito. Il passo successivo naturale è costruire un agente RAG sui tuoi PDF: la base che hai messo qui è esattamente quella che ti serve. Per approfondire, fai riferimento alla sezione Advanced AI della documentazione.