Come creare un agente AI con n8n in locale: guida pratica passo passo

Negli ultimi mesi si parla sempre più spesso di agenti AI, cioè strumenti capaci non solo di rispondere a un prompt, ma anche di seguire un obiettivo, usare tool esterni, combinare più passaggi e produrre un risultato più utile rispetto a una semplice chat. In questo scenario, n8n è diventato uno dei nomi più interessanti da tenere d’occhio.

n8n è una piattaforma di automazione che può essere installata anche in self-hosting, per esempio con Docker, e include funzionalità dedicate ai workflow AI. La documentazione ufficiale mostra infatti sia la possibilità di installare n8n con Docker sia l’uso di componenti come Chat Trigger, Agent node e Basic LLM Chain per costruire flussi AI pratici.

In questa guida vedremo come creare un agente AI con n8n in locale, passo passo, con un approccio semplice e adatto a chi vuole iniziare davvero senza perdersi subito in progetti troppo complessi.

Cosa faremo in questa guida

L’obiettivo è creare un piccolo agente AI locale accessibile via browser, eseguito su n8n in self-hosting. Useremo Docker per l’installazione, poi costruiremo un workflow di base che riceve un messaggio, lo passa a un modello AI e restituisce una risposta all’interno di una semplice interfaccia chat.

n8n documenta che il Chat Trigger è il nodo da usare per costruire workflow chat e che deve essere collegato a un agent o a una chain. Inoltre, la documentazione spiega che gli agenti in n8n possono usare strumenti e prendere decisioni su più esecuzioni, mentre le chain sono più semplici e adatte a interazioni dirette con un LLM.

Requisiti

Per seguire il tutorial ti servono:

• un PC Linux, un mini server oppure un VPS con Docker installato;
• Docker funzionante;
• una minima familiarità con terminale e browser;
• un accesso a un modello compatibile, per esempio tramite OpenAI oppure un endpoint compatibile configurabile da n8n.

La documentazione ufficiale di n8n per Docker mostra un avvio locale sulla porta 5678, con volume persistente, variabili per timezone e permessi del file di configurazione.

Installare n8n con Docker

Il modo più semplice per iniziare in locale è usare il container ufficiale. La documentazione n8n consiglia di creare un volume persistente e avviare il container esposto sulla porta 5678.

Creiamo quindi il volume:

docker volume create n8n_data

Avviamo poi n8n con questo comando:

docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -e GENERIC_TIMEZONE="Europe/Rome" \
  -e TZ="Europe/Rome" \
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
  -e N8N_RUNNERS_ENABLED=true \
  -v n8n_data:/home/node/.n8n \
  n8nio/n8n:stable

Queste opzioni seguono lo schema mostrato nella documentazione ufficiale: porta 5678, timezone, enforcement dei permessi del file di configurazione, task runners abilitati e volume persistente per i dati.

Una volta avviato il container, apri il browser su:

http://localhost:5678

Se stai usando un VPS remoto, sostituisci localhost con l’indirizzo IP del server e in caso, ricordati di esporre l’accesso sul firewall.

Primo accesso a n8n

Al primo avvio ti troverai davanti la schermata iniziale di configurazione dell’istanza. Completa la creazione dell’account locale e accedi alla dashboard di n8n.

La documentazione di hosting precisa che tutte le installazioni self-hosted usano lo stesso core product, quindi le funzioni principali che trovi nell’interfaccia sono quelle standard della piattaforma.

Capire la differenza tra chain e agent

Prima di costruire il workflow, conviene chiarire una differenza importante. n8n documenta che una Basic LLM Chain serve per interagire con un modello in modo diretto, senza componenti aggiuntivi, mentre un Agent è pensato per comportamenti più orientati agli obiettivi, con uso di tool e decisioni operative.

In pratica:

• se vuoi una chat AI semplice, una chain può bastare;
• se vuoi un flusso più intelligente, capace di usare strumenti e scegliere cosa fare, conviene partire con un agent.

In questa guida faremo un agente semplice, così da usare la struttura più vicina al concetto moderno di AI agentica.

Creare un nuovo workflow

Dopo l’accesso, crea un nuovo workflow vuoto dalla dashboard di n8n. Il nostro flusso di base sarà molto semplice:

1. un nodo Chat Trigger per ricevere il messaggio dell’utente;
2. un nodo AI Agent come cervello principale del flusso;
3. un nodo modello, per esempio OpenAI Chat Model, collegato all’agente.

La documentazione del Chat Trigger indica che ogni messaggio esegue il workflow e che questo nodo deve essere collegato a un agent oppure a una chain root node.

Aggiungere il Chat Trigger

Nel canvas del workflow aggiungi il nodo Chat Trigger. Questo è il punto di ingresso del tuo agente AI.

n8n spiega che il Chat Trigger si usa per chatbot e interfacce chat e che supporta sia le interfacce fornite da n8n sia interfacce personalizzate. Inoltre, se vuoi gestire memoria di sessione, il trigger può essere collegato a un nodo memoria condiviso con l’agente.

Per una prima prova, puoi lasciare una configurazione semplice senza memoria persistente e concentrarti solo sul funzionamento di base.

Aggiungere il nodo AI Agent

Ora aggiungi il nodo AI Agent e collegalo al Chat Trigger. Questo nodo sarà il cuore del sistema.

La documentazione n8n sull’AI spiega che l’agente è rappresentato come nodo e che può combinare passaggi AI con automazione tradizionale, proprio per creare workflow più utili nel mondo reale. Inoltre, il sito n8n dedicato agli agenti evidenzia che il nodo agente può ricevere input da un trigger, usare system prompt, integrare logica deterministica, fallback e human-in-the-loop.

Nel campo prompt di sistema puoi inserire qualcosa di semplice come:

Sei un assistente tecnico chiaro e preciso.
Rispondi in italiano.
Se la richiesta è poco chiara, chiedi un chiarimento.
Mantieni le risposte concise ma utili.

Questo basta già per dare all’agente un comportamento coerente.

Collegare il modello AI

L’agente ha bisogno di un modello. Per questo puoi aggiungere un nodo modello compatibile, per esempio OpenAI Chat Model, e collegarlo all’AI Agent.

La documentazione del nodo OpenAI Chat Model spiega che serve per usare modelli conversazionali e che n8n carica dinamicamente i modelli disponibili per l’account configurato. La stessa documentazione distingue anche tra Chat Completions e Responses API, sottolineando che la seconda supporta meglio flussi agentici e conversazioni persistenti.

Se usi un provider compatibile o un endpoint compatibile OpenAI, la logica generale del workflow resta la stessa: il Chat Trigger riceve la richiesta, l’AI Agent la orchestra e il nodo modello genera la risposta.

Configurare le credenziali del modello

Apri il nodo del modello e inserisci le credenziali richieste. Se usi OpenAI, dovrai configurare la chiave API tramite il sistema credenziali di n8n.

Questa parte dipende dal provider scelto, ma il principio non cambia: senza un modello collegato, l’agente non potrà generare risposte.

Testare il workflow

Una volta collegati Chat Trigger, AI Agent e modello, salva il workflow e avvialo in modalità test. Apri la chat integrata e invia un messaggio semplice, per esempio:

Spiegami in modo semplice cos'è un reverse proxy

Se tutto è configurato correttamente, n8n eseguirà il workflow e l’agente risponderà nell’interfaccia chat. La documentazione del Chat Trigger conferma che ogni messaggio inviato alla chat esegue il workflow, quindi il comportamento che vedi è coerente con il modello operativo previsto da n8n.

Aggiungere memoria alla conversazione

Se vuoi che l’agente ricordi il contesto delle richieste precedenti, puoi aggiungere un nodo memoria condiviso tra Chat Trigger e Agent.

La documentazione del Chat Trigger specifica che, quando si abilita il caricamento di sessioni precedenti, conviene collegare sia il trigger sia l’agente allo stesso memory sub-node, in modo da avere una sola fonte di verità per il contesto della conversazione.

Per un primo test puoi anche evitare questa parte, ma se vuoi un agente un po’ più credibile e meno “stateless”, è uno dei passi più utili da fare subito.

Da semplice chat a vero agente

Una chat AI di base è utile, ma un agente diventa davvero interessante quando può usare strumenti. n8n spiega che gli agenti possono interagire con tool e che durante l’esecuzione possono fare più run per decidere, chiamare uno strumento e poi valutare il risultato.

Ecco alcuni esempi pratici che puoi aggiungere in un secondo momento:

• una chiamata HTTP verso un’API esterna;
• la lettura di dati da Google Sheets o database;
• un tool per interrogare un altro workflow;
• un controllo su webhook, email o ticket.

Secondo n8n, proprio questa combinazione tra automazione classica e passaggi AI è uno dei motivi per cui gli agenti risultano utili in scenari reali.

Esempio pratico di evoluzione

Una buona idea per evolvere questo progetto è trasformarlo in un piccolo assistente tecnico personale. Per esempio, potresti creare un agente che:

• riceve una domanda tecnica;
• cerca una risposta in un tuo archivio note o documenti;
• interroga una API esterna se serve;
• restituisce una risposta più precisa e contestuale.

Questa direzione è coerente con le guide AI di n8n, che mostrano come usare l’AI per costruire chatbot, processare documenti e combinare dati provenienti da più sorgenti.

Problemi comuni

n8n non si apre sulla porta 5678

Controlla che il container sia in esecuzione e che la porta sia davvero esposta. La documentazione Docker di n8n usa proprio la porta 5678 come accesso standard all’interfaccia web.

Il workflow non risponde in chat

Verifica che il Chat Trigger sia collegato a un Agent o a una Chain root node, perché la documentazione lo richiede esplicitamente.

L’agente non capisce il contesto precedente

In questo caso probabilmente non hai ancora aggiunto un nodo memoria condiviso oppure non hai attivato il caricamento della sessione precedente nel Chat Trigger. n8n spiega che memoria e sessione vanno configurate insieme quando vuoi continuità nella conversazione.

Il modello AI non risponde

Controlla le credenziali del nodo modello e verifica che il provider sia configurato correttamente. Il nodo OpenAI Chat Model, per esempio, dipende dalla corretta autenticazione e dai modelli disponibili per l’account.

FAQ

Posso usare n8n in locale senza cloud?

Sì. La documentazione ufficiale include una procedura di installazione self-hosted con Docker, con volume persistente e accesso via browser sulla porta 5678.

Che differenza c’è tra chain e agent in n8n?

Le chain servono per interagire con il modello in modo più diretto, mentre gli agent sono pensati per comportamenti orientati agli obiettivi, uso di tool e decisioni su più passaggi.

Serve per forza un provider esterno per il modello?

Per generare risposte serve comunque un modello collegato al workflow. In questa guida l’esempio più semplice è tramite il nodo OpenAI Chat Model, ma la logica del workflow resta la stessa anche con configurazioni compatibili. Se esegui Ollama come descritto nella nostra guida, puoi tranquillamente utilizzare un modello self-hosted.

Considerazioni finali

Creare un agente AI con n8n in locale è uno dei modi più accessibili per entrare davvero nel mondo dell’AI agentica senza partire subito da codice complesso. Docker semplifica l’installazione, mentre n8n fornisce già i componenti necessari per costruire workflow chat, chain e agenti in modo visuale.

Il vantaggio vero è che puoi partire con una chat molto semplice e poi trasformarla gradualmente in qualcosa di più utile: un assistente tecnico, un motore di automazione, un workflow con tool esterni o un agente che consulta dati reali. È proprio questa scalabilità pratica a rendere n8n uno degli strumenti più interessanti del momento per chi vuole sperimentare con l’AI in modo concreto.