Come creare un agente AI n8n sul tuo VPS

Cos'è un agente AI di n8n e in cosa differisce da una catena

Un agente AI di n8n è un singolo nodo AI Agent con alcuni sottonodi collegati: un modello di chat, uno o più strumenti e, facoltativamente, una memoria. Si definisce un obiettivo in linguaggio naturale e il modello decide quali strumenti chiamare e in quale ordine, finché non è in grado di rispondere. Tutto ciò che segue riguarda la configurazione di questa singola idea.

Una catena funziona al contrario. In una Basic LLM Chain si definiscono i passaggi e il modello si limita a generare il testo. In un agente è il modello a decidere i passaggi, quindi la stessa domanda può richiedere una chiamata al modello oggi e nove domani. Questa differenza determina tutte le impostazioni descritte in questa guida.

Si presume che n8n sia già in esecuzione dietro HTTPS su una macchina sotto il proprio controllo. In caso contrario, iniziare da self-hosting di n8n su Docker con un certificato valido, perché la chiave API che si sta per memorizzare richiede il backup della encryption key indicato in quella guida. Per i pattern senza agenti, come i summarizer tramite webhook e i classificatori pianificati, vedere pattern di workflow con Claude e n8n.

Controllare la propria versione prima di fare affidamento sui nomi dei campi riportati qui, perché n8n modifica spesso i nodi AI.

docker compose exec n8n n8n --version

I nomi in questa guida corrispondono alla versione stabile corrente di n8n a luglio 2026. Dalla versione 1.82.0 ogni nodo AI Agent viene eseguito come Tools Agent, quindi il vecchio menu a discesa per il tipo di agente non esiste più.

Passaggio 1: scegliere il trigger

Per un agente conversazionale, aggiungi un nodo Chat Trigger. Durante la configurazione, lascia disattivata l'opzione Make Chat Publicly Available, in modo che possa raggiungerlo soltanto il pannello della chat dell'editor. Attivala quando l'agente è terminato e hai definito il metodo di autenticazione.

Chat Trigger fornisce all'agente un campo denominato chatInput. Questo nome è importante nel passaggio 3. Un nome errato è la causa più comune del primo errore.

Per un agente non presidiato, usa invece un nodo Schedule Trigger o Webhook. Nessuno dei due produce chatInput, quindi dovrai scrivere personalmente il prompt.

Passaggio 2: la credenziale del modello

Aggiungi un nodo AI Agent nell'area di lavoro. n8n mostra immediatamente un connettore Chat Model vuoto sotto il nodo. Collega lì un sotto-nodo Anthropic Chat Model.

Crea la credenziale dalla Anthropic Console, all'indirizzo platform.claude.com, aprendo Settings e poi API Keys. La chiave viene mostrata una sola volta. L'utilizzo dell'API viene fatturato per token ed è separato da qualsiasi abbonamento Claude.ai. Prima della prima esecuzione, l'account deve quindi avere la fatturazione configurata.

Scegli il modello per ogni agente, non per l'intera azienda. Un agente con un solo strumento, che cerca un'informazione e la restituisce, funziona bene con Haiku, che a luglio 2026 ha un prezzo indicato di $1 per milione di token di input e $5 per milione di token di output. Quando l'agente dispone di diversi strumenti e deve pianificare il loro utilizzo, passa a Sonnet. Il problema da evitare è un modello economico che chiama quattro volte lo strumento sbagliato, con un costo superiore a quello di un modello più costoso che chiama una sola volta lo strumento corretto.

Imposta Maximum Number of Tokens nelle opzioni del sotto-nodo. Questo parametro limita la lunghezza di ogni risposta generata dal modello. Se lasciato sul valore predefinito elevato, una singola esecuzione in errore può produrre una risposta molto lunga e aumentare il costo.

La documentazione di n8n segnala inoltre un dettaglio che causa spesso problemi: le espressioni contenute in un sotto-nodo vengono sempre risolte rispetto al primo elemento di input, mai per ciascun elemento. Inserisci le espressioni dipendenti dal singolo elemento nei campi del prompt del nodo radice.

Passaggio 3: il prompt ricevuto dall’agente

Apri il nodo AI Agent. Il parametro Prompt prevede due impostazioni.

• Take from previous node automatically cerca automaticamente un campo in ingresso denominato chatInput. È la scelta corretta quando il nodo è preceduto da un Chat Trigger.
• Define below mostra il campo Prompt (User Message), in cui puoi inserire testo statico o un’espressione. È la scelta corretta quando il nodo è preceduto da un Schedule Trigger o da un nodo Webhook.

Quando il nodo Webhook è il nodo precedente, il corpo della richiesta POST viene inserito in $json.body. Il campo del prompt è quindi simile al seguente.

Check the current status of {{ $json.body.service }} and tell me
whether it is up. If it is down, say for how long. No preamble.

Passaggio 4: assegnare un tool all'agente

Un nodo AI Agent senza un sotto-nodo tool non viene eseguito. Inizia con un solo tool: un tool funzionante fornisce più informazioni di quattro tool configurati solo parzialmente.

Collega un nodo HTTP Request al connettore Tool dell'agente. Configuralo esattamente come un normale nodo HTTP Request, quindi testa prima l'endpoint da una shell.

curl -s -H 'Accept: application/json' \
  https://status.example.com/api/status/database | head -c 400

Se quel comando curl restituisce un errore o una pagina di accesso HTML, anche l'agente non funzionerà. L'errore sembrerà causato dal modello, ma il problema sarà in realtà nell'URL o nell'autenticazione. Risolvi il problema dalla shell, non nel nodo.

Il campo Description del tool non serve come documentazione per i colleghi. È l'unica informazione che il modello legge per decidere se il tool è pertinente. Scrivilo come una descrizione semplice del risultato restituito: "Restituisce in JSON lo stato attuale, attivo o inattivo, e la durata del downtime per un servizio monitorato."

Per consentire al modello di compilare una parte della richiesta, usa l'espressione $fromAI(). Funziona solo nei tool collegati a un nodo AI Agent e non funziona nel tool Code.

{{ $fromAI('service', 'The name of the service to look up', 'string') }}

Gli argomenti sono key, quindi, facoltativamente, description, type e defaultValue. La chiave deve contenere da 1 a 64 caratteri, usando lettere, cifre, caratteri di sottolineatura e trattini. Il tipo deve essere uno tra string, number, boolean e json e, per impostazione predefinita, è string. Una chiamata più completa è simile alla seguente.

{{ $fromAI('limit', 'How many records to return', 'number', 20) }}

La chiave è un suggerimento, non un riferimento a dati esistenti. $fromAI('service') non legge da nessuna parte un campo denominato service. Indica al modello di "produrre un valore e chiamarlo service"; il modello cerca quindi un valore nella conversazione, nei dati di input e nei risultati degli altri tool. In un workflow di chat potrebbe semplicemente chiederlo all'utente.

La ricerca sul Web è il secondo tool più comune. Poiché è un altro endpoint HTTP, puoi indirizzare questo stesso nodo alla tua istanza SearXNG invece di usare un'API di ricerca a pagamento, purché consideri testo non attendibile ogni pagina che restituisce e che viene quindi inserita nel prompt.

Passaggio 5: memoria e motivo per cui l’agente dimentica

Senza un sottodo di memoria, ogni messaggio parte da zero. Collega un sottodo Simple Memory per conservare la conversazione recente.

Dispone di due parametri. Session Key identifica la conversazione, quindi due utenti con chiavi diverse ottengono cronologie separate. Context Window Length indica quante interazioni precedenti vengono reinserite nel prompt.

Context Window Length è un parametro che incide sui costi oltre che sulla qualità, perché ogni turno memorizzato viene reinviato come token di input a ogni chiamata successiva. Una finestra di 20 in un agente molto loquace significa pagare venti volte gli stessi messaggi iniziali.

Simple Memory non funziona in un workflow di produzione attivo quando n8n viene eseguito in modalità queue, perché la cronologia risiede nei dati del workflow e non in uno storage condiviso. In un'istanza in modalità queue, usa invece il sottodo Postgres Chat Memory e configuralo in modo che punti a un database raggiungibile sia dal processo principale sia dai worker.

Passaggio 6: il messaggio di sistema

Apri le Options dell'agente e aggiungi un System Message. Qui va inserita la descrizione del compito. È il testo con il maggiore impatto operativo dell'intero workflow.

You are an infrastructure status assistant. Always call the status
tool before answering a question about whether something is running.
Never guess. If the tool returns an error, say so and stop.

La frase "Always call the status tool before answering" svolge una funzione concreta. Senza questa istruzione, un modello che ritiene di conoscere già la risposta può ignorare lo strumento e rispondere basandosi sulla memoria. La risposta sarà quindi errata con sicurezza non appena cambia l'infrastruttura.

Perché l'agente entra in loop e cosa lo interrompe

In Options è disponibile anche Max Iterations, con valore predefinito 10. Un'iterazione consiste in una chiamata al modello e nel reinserimento del risultato dello strumento nel contesto. Una singola esecuzione dell'agente non corrisponde quindi a una sola chiamata API: può arrivare a dieci chiamate, ognuna delle quali include come input l'intera conversazione accumulata.

Riduci questo valore. La maggior parte degli agenti che usano un solo strumento termina in due iterazioni. Un limite di 3 o 4 turni trasforma un loop incontrollato in un errore esplicito, visibile nell'elenco delle esecuzioni.

Durante il debug, attiva Return Intermediate Steps. L'output finale includerà le chiamate agli strumenti effettuate dall'agente. Questo consente di distinguere tra il caso in cui «il modello non ha mai chiamato lo strumento» e quello in cui «lo strumento non ha restituito informazioni utili». Disattiva l'opzione prima di mettere il flusso in produzione, perché questi passaggi sono superflui per l'utente finale.

Osserva un'esecuzione dalla shell.

docker compose logs -f n8n

Impedire a un agent non sorvegliato di consumare risorse senza controllo

Un agente dietro un Chat Trigger ha una persona che lo controlla e lo interrompe quando la risposta sembra errata. Un agente dietro uno Schedule Trigger non ha nessuno che lo controlli. In questo caso si controlla il consumo del modello, non il costo delle licenze, perché i nodi agent, tool e memory funzionano tutti nell’edizione self-hosted gratuita, mentre le funzionalità che richiedono una chiave a pagamento riguardano soprattutto il lavoro di squadra e la governance. La trattazione completa è disponibile in Controllo dei costi degli agenti AI su un VPS sempre attivo. Quattro impostazioni svolgono gran parte del lavoro.

• Imposta un limite per Maximum Number of Tokens nel sotto-nodo del modello, in modo che nessuna singola risposta possa diventare troppo lunga.
• Imposta Max Iterations sul valore più basso che consenta comunque di completare l'attività.
• Mantieni ridotte le risposte degli strumenti. Uno strumento che restituisce un blob JSON di 4,000 righe inserisce tutti quei dati nella chiamata successiva al modello e poi in ogni chiamata successiva della stessa esecuzione.
• Valuta se l'agent ha davvero bisogno di una pianificazione. Un'attività eseguita ogni cinque minuti viene avviata 288 volte al giorno. Qualunque sia il costo di una singola esecuzione, questo è il valore da moltiplicare.

Disattiva il workflow durante le iterazioni. Un workflow attivo con uno Schedule Trigger continua a essere eseguito sulla versione salvata da n8n, che non sempre coincide con quella visualizzata sullo schermo.

FAQ

Perché il nodo AI Agent rifiuta di eseguire il workflow?

Il nodo AI Agent richiede un sotto-nodo di modello chat e almeno un sotto-nodo tool. Un nodo con un modello ma senza tool va in errore prima di effettuare qualsiasi chiamata API. Collega un tool, anche semplice, quindi esegui di nuovo il workflow.

L'agente risponde, ma non chiama mai il mio tool. Qual è il problema?

Quasi sempre il problema è il campo Description del tool. Il modello sceglie i tool leggendo queste descrizioni. Una descrizione come "HTTP Request" non indica in quali situazioni il tool è applicabile. Riscrivi la descrizione specificando quali dati restituisce il tool e in quale situazione è utile. Quindi aggiungi una riga al System Message per istruire l'agente a chiamare quel tool prima di rispondere.

Perché la stessa domanda ha un costo diverso a ogni esecuzione?

Perché il modello decide il numero di passaggi. A ogni iterazione, il modello invia di nuovo l'intera conversazione disponibile fino a quel momento, incluso l'output dei tool precedenti. Di conseguenza, un'esecuzione che richiede quattro iterazioni costa molto più di quattro chiamate singole. Max Iterations definisce il limite massimo, mentre Return Intermediate Steps mostra quanti passaggi ha usato effettivamente una determinata esecuzione.

La memoria funziona nell'editor, ma non in produzione. Che cosa è cambiato?

Verifica se l'istanza è in esecuzione in modalità queue. Simple Memory salva la cronologia nei dati di esecuzione del workflow. Questi dati non vengono mantenuti quando l'esecuzione passa a un processo worker separato, quindi un workflow di produzione attivo perde la cronologia. Sostituisci il sotto-nodo con Postgres Chat Memory, che salva la cronologia nel database condiviso da tutti i worker.