Un agente IA non e' solo un chatbot: e' un sistema che riceve un obiettivo, decide quali strumenti usare (cercare sul web, leggere un database, inviare un messaggio) e porta a termine il compito. n8n e' una delle piattaforme migliori per costruirne uno senza scrivere un intero backend: e' open source, si auto-ospita gratis e ha nodi dedicati all'IA. In questa guida installiamo n8n con Docker e costruiamo un agente funzionante, passo dopo passo.

A chi serve e cosa otterrai

Questa guida e' pensata per chi ha gia' un minimo di dimestichezza con il terminale e vuole automatizzare compiti reali: rispondere a richieste, smistare email, generare bozze, interrogare dati. Al termine avrai un'istanza di n8n attiva sul tuo computer e un agente IA capace di rispondere usando un modello linguistico e almeno uno strumento esterno. Non serve saper programmare: si lavora su un'interfaccia visuale a nodi.

Prerequisiti reali

  • Un computer Windows, macOS o Linux con almeno 4 GB di RAM liberi.
  • Docker Desktop installato (il modo piu' semplice per eseguire n8n in locale).
  • Una chiave API di un fornitore di modelli: va bene OpenAI (GPT-5/GPT-4o), Anthropic (Claude), Google (Gemini) o Mistral. In alternativa, un modello locale via Ollama.

Quale modello scegliere per l'agente

n8n e' agnostico: puoi collegare quasi qualsiasi LLM. La scelta dipende dal caso d'uso:

  • OpenAI GPT-5 / GPT-4o - ottimo equilibrio tra capacita' di ragionamento e uso degli strumenti; la scelta piu' semplice per iniziare. Costo a consumo, nessun piano gratuito sulle API ma tariffe contenute per i volumi di prova.
  • Anthropic Claude Sonnet - molto affidabile nel seguire istruzioni complesse e nel "tool use"; ideale per agenti che devono essere prudenti.
  • Google Gemini - buon piano gratuito sull'API, utile per sperimentare a costo zero.
  • Ollama in locale (es. Llama o Qwen) - gratis e privato, ma richiede una macchina con buona RAM/VRAM e i modelli piccoli reggono meno i compiti agentici.

Prima scelta consigliata: GPT-5 o GPT-4o per partire senza intoppi, perche' il supporto al tool use e' maturo e la documentazione di n8n e' ricca di esempi. Passa a Gemini se vuoi restare nel gratuito, o a Ollama se la privacy e' prioritaria.

n8n permette di costruire agenti IA con un'interfaccia visuale a nodi, senza scrivere un backend.

Passo 1 - Installare n8n con Docker

Apri il terminale e avvia n8n con un solo comando. Creiamo anche un volume per non perdere i workflow:

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

Quando il terminale mostra che il servizio e' attivo, apri il browser su http://localhost:5678. Al primo avvio crei l'account proprietario locale (email e password restano sul tuo computer). Per un uso continuativo, sostituisci --rm con -d per tenere il container in background.

Passo 2 - Salvare le credenziali del modello

In n8n vai su Credentials > New, cerca il tuo fornitore (es. "OpenAI") e incolla la chiave API. Le credenziali vengono cifrate e riutilizzate dai nodi senza doverle riscrivere. Non inserire mai la chiave direttamente dentro un nodo di testo.

Passo 3 - Creare il workflow dell'agente

Crea un nuovo workflow e aggiungi i nodi nell'ordine seguente:

  1. Chat Trigger (oppure "When chat message received"): apre una chat di test da cui parlare con l'agente.
  2. AI Agent: e' il cuore del sistema. Collega come "Chat Model" il nodo del tuo LLM (es. OpenAI Chat Model) e seleziona le credenziali salvate.
  3. Nel campo System Message dell'AI Agent definisci il comportamento. Ad esempio:
Sei un assistente operativo per una piccola azienda italiana. Rispondi in italiano, in modo conciso. Quando ti viene chiesto un calcolo o una data, usa gli strumenti disponibili invece di indovinare. Se non hai abbastanza informazioni, fai una domanda di chiarimento.

Passo 4 - Dare strumenti all'agente

Un agente diventa utile quando puo' agire. All'AI Agent puoi collegare dei Tool:

  • Calculator: per fare calcoli affidabili.
  • HTTP Request Tool: per chiamare un'API esterna (meteo, cambio valuta, un tuo servizio).
  • Memory (Window Buffer Memory): per ricordare i messaggi precedenti nella stessa conversazione.

Aggiungi almeno il Calculator e una Memory. Da ora, se chiedi all'agente "quanto fa il 22% di 1.480 euro?", non improvvisera': usera' lo strumento di calcolo e restituira' il valore corretto.

Passo 5 - Provare l'agente

Apri la chat di test del Chat Trigger e scrivi una richiesta che richieda ragionamento e strumento, ad esempio:

Un cliente deve pagare 3 fatture da 480, 1.250 e 2.300 euro con il 4% di sconto sul totale. Quanto paga? Poi scrivi un messaggio cortese di promemoria in italiano.

Risultato atteso: l'agente usa il Calculator per la somma e lo sconto, poi genera il testo del promemoria. Vedrai nei nodi il percorso seguito: questa tracciabilita' e' uno dei vantaggi di n8n rispetto a uno script opaco.

Passo 6 - Da chat ad automazione reale

La vera potenza arriva sostituendo il Chat Trigger con un trigger automatico. Alcune idee concrete:

  • Un Webhook che riceve i messaggi da un form o da Telegram: l'agente risponde e invia la replica con il nodo Telegram.
  • Un Schedule Trigger che ogni mattina legge un feed RSS, fa riassumere le notizie all'agente e te le manda via email.
  • Un trigger "nuova riga in Google Sheets" che attiva l'agente per categorizzare una richiesta cliente e scrivere una bozza di risposta.

Errori comuni e soluzioni

  • "401 / Invalid API key": la chiave e' sbagliata o senza credito. Rigenerala nel pannello del fornitore e ricontrolla che sia salvata nelle Credentials, non nel testo del nodo.
  • L'agente "inventa" i calcoli: non hai collegato il Calculator, oppure il System Message non gli dice di usare gli strumenti. Aggiungi entrambe le cose.
  • "Cannot connect to localhost:5678": il container Docker non e' partito o la porta e' occupata. Verifica con docker ps e, se serve, cambia la porta (es. -p 5679:5678).
  • Perdi i workflow dopo un riavvio: hai dimenticato il volume. Assicurati di usare -v n8n_data:/home/node/.n8n.

Varianti avanzate e quando non usare n8n

Per casi piu' complessi puoi dare all'agente strumenti personalizzati (un sotto-workflow n8n richiamato come tool), collegare un database vettoriale per un RAG sui tuoi documenti, o orchestrare piu' agenti specializzati. Se invece il compito e' una singola chiamata a un modello dentro un'app che gia' sviluppi, conviene usare direttamente l'API del fornitore in codice: n8n da' il meglio quando il valore sta nell'orchestrare piu' passaggi e servizi.

Come proseguire

Una volta padroneggiato l'AI Agent, esplora i nodi per database vettoriali (per un agente che risponde sui tuoi PDF), le integrazioni con Gmail, Slack e Telegram, e la pubblicazione del workflow tramite webhook per renderlo un vero servizio. La documentazione ufficiale di n8n contiene esempi pronti da importare: il modo piu' rapido per imparare e' partire da un template e modificarlo per il proprio caso.