Come creare un agente AI n8n sul tuo VPS

Che 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 opzionale. 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 costruita intorno a questa 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 tutte le impostazioni descritte in questa guida. Se questo ciclo è nuovo per te come concetto, e non soltanto come funzionalità di n8n, conviene scriverne manualmente una volta prima di assemblarlo con i nodi, perché il nodo nasconde esattamente la parte su cui dovrai ragionare per il resto della guida.

Si presume 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 valido, perché la chiave API che stai per memorizzare richiede il backup della chiave di cifratura indicato in quella guida. Per i pattern senza agenti, cioè i workflow che riassumono i webhook e quelli che classificano i dati in base a una pianificazione, consulta pattern di workflow per 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

La versione 1.82.0 ha deprecato l’impostazione del tipo di agente in favore di Tools Agent. I nodi legacy v1 includono ancora questa impostazione; la documentazione di n8n indica che la rimozione di questa versione del nodo è prevista con n8n 3.0.

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

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 Claude Console all'indirizzo platform.claude.com, aprendo prima Settings e poi API keys. La chiave viene mostrata una sola volta. Durante la creazione di una chiave, la Console chiede anche di scegliere una scadenza. Un agent non presidiato smette di funzionare il giorno in cui scade la chiave, quindi annota la data in un punto visibile. Per un agent non presidiato, usa una chiave di un account di servizio associata a un workspace, così le richieste non devono includere un header workspace separato.

L'uso dell'API viene fatturato per token. Il metodo di pagamento dipende dal piano Claude in vigore al 31 October 2026. I piani Max, Ultra e Team includono crediti API mensili: $100 per Max, $200 per Ultra e fino a $500 condivisi per Team. Per utilizzarli, collega un'organizzazione Console al piano da Settings > Billing nei piani Max o Ultra, oppure da Organization settings > Billing nel piano Team. Non è necessario aggiungere un metodo di pagamento nella Console. I nuovi abbonati possono utilizzare i crediti dopo 7 giorni dall'attivazione del piano. I crediti inutilizzati scadono alla fine di ogni ciclo di fatturazione, oppure ogni mese nei piani annuali. Quando i crediti inclusi terminano, le richieste continuano a utilizzare i crediti acquistati; il ricaricamento automatico può acquistarne altri e le organizzazioni con fatturazione a consuntivo ricevono l'addebito per l'utilizzo eccedente. Le richieste si interrompono quando un'organizzazione prepagata non ha più crediti. L'uso dell'API non viene mai addebitato al piano Claude. I piani Free, Pro ed Enterprise non includono crediti API mensili. In questi piani, l'API viene quindi fatturata separatamente dall'abbonamento.

Scegli il modello per ogni agent, non per l'intera organizzazione. Un agent con un solo strumento, che cerca un'informazione e la restituisce, funziona bene con Haiku. La versione attuale, Haiku 5.5, ha un prezzo indicato di $0.10 per milione di token di input e $0.50 per milione di token di output al 12 October 2026. Per una richiesta il cui prompt supera 100,000 token, i prezzi salgono rispettivamente a $0.50 e $2.50. Una finestra di memoria lunga e risultati estesi degli strumenti possono portare la richiesta oltre questa soglia. Quando l'agent usa diversi strumenti e deve pianificare le operazioni tra loro, passa a Sonnet. Il problema da evitare è un modello economico che chiama quattro volte lo strumento sbagliato. Il costo può superare 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 valore limita la lunghezza di ogni risposta generata dal modello. Se lasci un valore predefinito elevato, un'esecuzione confusa può generare una risposta molto lunga e aumentare il costo.

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

Passaggio 3: il prompt ricevuto dall'agente

Apri il nodo AI Agent. Il parametro Source for Prompt (User Message) presenta due impostazioni.

• Connected Chat Trigger Node si aspetta un campo in ingresso denominato chatInput. È la scelta corretta quando il nodo è preceduto da un Chat Trigger.
• Define below mostra un 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 è preceduto da un Webhook, il corpo della richiesta POST viene inserito in $json.body. Il campo del prompt sarà 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: assegna all’agente uno strumento

La documentazione di n8n indica che è necessario collegare almeno un sotto-nodo strumento a un nodo AI Agent, anche se il codice attuale del nodo (versione 3.1) rifiuta di eseguire il flusso solo quando manca un modello di chat. Inizia comunque con un solo strumento: uno strumento funzionante insegna più di quattro strumenti configurati a metà, e un agente senza strumenti è soltanto una chain che costa di più.

Collega un nodo HTTP Request al connettore Tool dell’agente. Configuralo esattamente come configureresti 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 quel comando curl restituisce un errore o una pagina HTML di login, anche l’agente non funzionerà. L’errore sembrerà un problema del modello, mentre la causa sarà in realtà un problema di URL o di autenticazione. Risolvilo dalla shell, non nel nodo.

Il campo Description dello strumento non serve come documentazione per i colleghi. Il modello lo legge insieme al nome dello strumento e allo schema dei parametri per decidere se lo strumento è pertinente. Scrivilo come una frase semplice che descriva il risultato restituito: "Restituisce lo stato attuale, attivo o inattivo, e la durata dell’interruzione per 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 nello strumento 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 e può usare lettere, cifre, caratteri di sottolineatura e trattini. Il tipo deve essere uno tra string, number, boolean o 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 chiamato 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 strumenti. In un workflow di chat potrebbe semplicemente chiederlo all’utente.

La ricerca sul Web è il secondo strumento più comune. Poiché è soltanto un altro endpoint HTTP, puoi indirizzare questo stesso nodo alla tua istanza SearXNG invece di usare un’API di ricerca a pagamento, purché consideri ogni pagina restituita come testo non attendibile che ora si trova all’interno del prompt.

Passaggio 5: memoria e perché 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 stabilisce a quale conversazione appartiene la sessione, 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 inviato nuovamente 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é memorizza la cronologia in una Map singleton locale al processo, indicizzata dagli ID del workflow e della sessione, e i worker non condividono questa memoria. In un’istanza in modalità queue, usa invece il sotto-nodo Postgres Chat Memory e configuralo per utilizzare 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 un ciclo e cosa lo interrompe

In Options è disponibile anche Max Iterations, che per impostazione predefinita è 10. Un’iterazione corrisponde a una chiamata al modello, che può richiedere l’uso di strumenti oppure restituire la risposta finale; i risultati degli strumenti vengono passati alla chiamata successiva. Una singola esecuzione dell’agente non consiste quindi in una sola chiamata API, ma 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 trasform​a invece un ciclo senza fine in un errore chiaro, visibile nell’elenco delle esecuzioni.

Durante il debug, attiva Return Intermediate Steps. L’output finale includerà anche le chiamate agli strumenti effettuate dall’agente. Questo permette 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 passare in produzione, perché questi passaggi sono rumore per l’utente finale.

Osserva un’esecuzione dalla shell.

docker compose logs -f n8n

Impedire a un agent non supervisionato di consumare risorse senza controllo

Un agent collegato a un Chat Trigger include una persona che lo controlla e lo ferma quando la risposta sembra errata. Un agent collegato a uno Schedule Trigger non ha nessuno che lo supervisioni. In questo caso si controlla il consumo del modello, non il costo delle licenze, perché i nodi dell'agent, degli strumenti e della memoria funzionano nell'edizione self-hosted gratuita, mentre le funzionalità che richiedono una chiave a pagamento riguardano soprattutto team e governance. La trattazione completa è disponibile in Controllare i costi degli agent AI su un VPS sempre attivo. Quattro impostazioni coprono la maggior parte delle esigenze.

• 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 consente comunque di completare l'attività.
• Mantieni ridotte le risposte degli strumenti. Uno strumento che restituisce un blocco JSON di 4,000 righe inserisce tutti i dati nella chiamata successiva al modello e poi in ogni chiamata successiva della stessa esecuzione.
• Verifica se l'agent ha davvero bisogno di una pianificazione. Un job eseguito ogni cinque minuti si avvia 288 volte al giorno. Qualunque sia il costo di una singola esecuzione, devi moltiplicarlo per questo numero.

Annulla la pubblicazione del workflow mentre apporti modifiche oppure, almeno, annota quale versione è attiva. Un workflow pubblicato con uno Schedule Trigger continua a eseguire l'ultima versione pubblicata, non la bozza visualizzata sullo schermo, perché n8n conserva le modifiche come bozza finché non le pubblichi di nuovo.

FAQ

Perché il nodo AI Agent si rifiuta di eseguire?

Controlla prima i connettori. Il nodo AI Agent richiede un sotto-nodo del modello di chat; senza questo collegamento si arresta con il messaggio "Please connect a model to the Chat Model input", prima di effettuare qualsiasi chiamata API. La documentazione di n8n indica inoltre come necessario almeno un sotto-nodo strumento. Se il modello è collegato ma il nodo continua a rifiutarsi, collega uno strumento, anche molto semplice, quindi esegui nuovamente il flusso.

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

Quasi sempre il problema è il campo Description dello strumento. Il modello sceglie gli strumenti leggendo queste descrizioni; una descrizione come "HTTP Request" non spiega in quali situazioni lo strumento sia applicabile. Riscrivi la descrizione specificando quali dati restituisce e in quale situazione è utile, quindi aggiungi una riga al System Message per istruire l'agente a chiamare quello 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 viene reinviata l'intera conversazione fino a quel momento, compreso l'output precedente dello strumento. Di conseguenza, un'esecuzione che richiede quattro iterazioni addebita i token di input e di output di tutte e quattro le chiamate. Max Iterations imposta il limite massimo, mentre Return Intermediate Steps mostra quanti passaggi ha effettivamente utilizzato una determinata esecuzione.

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

Controlla se l'istanza è eseguita in modalità queue. Simple Memory salva la cronologia in una Map singleton locale al processo, indicizzata dagli ID del workflow e della sessione; processi worker separati non condividono questa struttura. Sostituiscila con il sotto-nodo Postgres Chat Memory, che conserva la cronologia nel database condiviso da tutti i worker.