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 una memoria facoltativa. 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 nel modo opposto. 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 ogni impostazione descritta in questa guida.

Si presuppone che n8n sia già in esecuzione dietro HTTPS su una macchina sotto il tuo controllo. In caso contrario, inizia da self-hosting di n8n su Docker con un certificato reale, perché la chiave API che stai per archiviare richiede il backup della chiave di crittografia previsto da quella guida. Per i modelli senza agenti, i riepilogatori basati su webhook e i classificatori pianificati, consulta modelli di workflow con Claude e n8n.

Controlla la tua 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 utilizzati 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: scegli il trigger

Per un agente conversazionale, aggiungi un nodo Chat Trigger. Mantieni disattivata l'opzione Make Chat Publicly Available durante la configurazione, in modo che solo il pannello della chat dell'editor possa raggiungerlo. Attivala quando l'agente è pronto e hai deciso il metodo di autenticazione.

Chat Trigger fornisce all'agente un campo chiamato chatInput. Questo nome è importante nel passaggio 3. Usare 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

Trascina un nodo AI Agent nell'area di lavoro. n8n mostra subito 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, in Settings e quindi API Keys. La chiave viene mostrata una sola volta. L'utilizzo dell'API viene fatturato per token ed è separato da qualsiasi abbonamento Claude.ai. Devi quindi configurare la fatturazione per l'account prima della prima esecuzione.

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 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 volta lo strumento corretto.

Imposta Maximum Number of Tokens nelle opzioni del sotto-nodo. Questo valore limita la lunghezza di ogni risposta generata dal modello. Se lasci un valore predefinito elevato, un'esecuzione confusa può produrre una risposta molto lunga e aumentare il costo.

Una precisazione della documentazione di n8n che spesso causa problemi: le espressioni all'interno di un sotto-nodo vengono sempre valutate rispetto al primo elemento di input, mai rispetto a ogni singolo elemento. Inserisci le espressioni per elemento nei campi del prompt del nodo radice.

Passaggio 3: il prompt ricevuto dall'agente

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

• Take from previous node automatically si aspetta un campo in ingresso denominato chatInput. È la scelta corretta quando viene usato un Chat Trigger.
• Define below mostra un campo Prompt (User Message) in cui puoi scrivere testo statico o un'espressione. È la scelta corretta quando viene usato un Schedule Trigger o un nodo Webhook.

Con un nodo Webhook a monte, il corpo di una richiesta POST viene inserito in $json.body, quindi il campo del prompt appare così.

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: assegna un solo strumento all'agente

Un nodo AI Agent senza un sottonodo tool rifiuta di eseguire il flusso. Inizia con un solo strumento: uno strumento funzionante insegna più di quattro strumenti configurati solo parzialmente.

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

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

Se questo comando curl restituisce un errore o una pagina di accesso HTML, anche l'agente fallirà. L'errore sembrerà un problema del modello, ma sarà in realtà un problema dell'URL o dell'autenticazione. Risolvilo dalla shell, non nel nodo.

Il campo Description dello strumento non serve a documentarlo per i colleghi. È l'unico elemento che il modello legge per stabilire se lo strumento è pertinente. Scrivilo come una semplice descrizione del risultato restituito: "Restituisce lo stato attivo o inattivo corrente e la durata dell'indisponibilità di un servizio monitorato, in formato JSON."

Per consentire al modello di compilare una parte della richiesta, usa l'espressione $fromAI(). Funziona solo negli strumenti 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, seguiti facoltativamente da description, type e defaultValue. La chiave deve contenere da 1 a 64 caratteri e può usare lettere, cifre, caratteri di sottolineatura e trattini. Il tipo deve essere uno tra string, number, boolean e json e il valore predefinito è string. Una chiamata 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 un campo chiamato service da alcuna origine. 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 strumenti. In un flusso di chat, potrebbe semplicemente chiederlo all'utente.

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

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

Ha due parametri. Session Key determina la conversazione, quindi due utenti con chiavi diverse ricevono 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 inviato nuovamente come token di input a ogni chiamata successiva. Un valore di 20 in un agente molto utilizzato significa pagare venti volte per gli stessi primi messaggi.

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 store condiviso. In un'istanza in modalità queue, usa invece il sotto-nodo Postgres Chat Memory e collegalo a un database raggiungibile sia dal processo principale sia dai worker.

Passaggio 6: il messaggio di sistema

Apri Options dell'agente e aggiungi un System Message. Qui va inserita la descrizione del lavoro. È il testo con il maggiore impatto sull'intero flusso di lavoro.

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.

"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 in base alla memoria. La risposta sarà sicuramente errata non appena cambierà l'infrastruttura.

Perché l'agente entra in un ciclo e cosa lo interrompe

Anche in Options è disponibile Max Iterations, il cui valore predefinito è 10. Un'iterazione consiste in una chiamata al modello e in un risultato dello strumento reinserito nel contesto. Una singola esecuzione dell'agente non corrisponde quindi a una sola chiamata API, ma può arrivare a dieci chiamate, ognuna delle quali include come input l'intera conversazione in crescita.

Riduci questo valore. La maggior parte degli agenti che usano un solo strumento termina in due iterazioni; un limite di 3 o 4 trasforma un ciclo senza fine in un errore chiaro, visibile nell'elenco delle esecuzioni.

Durante il debug, abilita Return Intermediate Steps. L'output finale includerà le chiamate agli strumenti effettuate dall'agente, permettendoti di distinguere tra "il modello non ha mai chiamato lo strumento" e "lo strumento non ha restituito informazioni utili". Disabilita nuovamente questa opzione prima di passare alla produzione, perché questi passaggi sono informazioni superflue per l'utente finale.

Osserva un'esecuzione dalla shell.

docker compose logs -f n8n

Impedire a un agente non presidiato di consumare risorse senza controllo

Un agente collegato a un Chat Trigger include un utente che lo interrompe quando la risposta sembra errata. Un agente collegato a un Schedule Trigger non ha nessuno che lo controlli. La trattazione completa è disponibile in Controllo dei costi di un agente AI su un VPS sempre attivo. In questo caso, quattro impostazioni svolgono la maggior 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 numero più basso che consente comunque di completare l'attività.
• Mantieni ridotte le risposte degli strumenti. Uno strumento che restituisce un blob JSON di 4,000 righe inserisce tutti i dati nella chiamata successiva al modello e poi in ogni chiamata successiva della stessa esecuzione.
• Valuta se l'agente richiede davvero una pianificazione. Un job eseguito ogni cinque minuti si avvia 288 volte al giorno. Qualunque sia il costo di una singola esecuzione, quello è il valore da moltiplicare.

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

FAQ

Perché il nodo AI Agent non viene eseguito?

Il nodo AI Agent richiede un sotto-nodo del modello di chat e almeno un sotto-nodo dello strumento. Un nodo con un modello ma senza strumenti ha esito negativo prima di effettuare qualsiasi chiamata API. Collega uno strumento, anche uno semplice, ed esegui nuovamente il nodo.

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

Nella maggior parte dei casi, il problema è il campo Description dello strumento. Il modello sceglie gli strumenti leggendo queste descrizioni. Una descrizione come "HTTP Request" non indica quando lo strumento è applicabile. Riscrivila specificando quali dati restituisce e in quale situazione è utile. Aggiungi quindi una riga al System Message per indicare all'agente di chiamare lo strumento prima di rispondere.

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

Perché il modello sceglie il numero di passaggi. A ogni iterazione, l'intera conversazione viene inviata nuovamente, incluso l'output precedente dello strumento. Per questo, un'esecuzione che richiede quattro iterazioni costa molto più di quattro volte una singola chiamata. Max Iterations definisce il limite massimo, mentre Return Intermediate Steps mostra quanti passaggi ha utilizzato effettivamente una determinata esecuzione.

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

Verifica se l'istanza è eseguita in modalità coda. Simple Memory archivia la cronologia nei dati di esecuzione propri del workflow. Questi dati non persistono quando l'esecuzione viene trasferita a un processo worker separato. Di conseguenza, un workflow di produzione attivo perde la cronologia. Sostituisci il sotto-nodo con Postgres Chat Memory, che conserva la cronologia nel database condiviso da tutti i worker.