How to Build n8n AI Agent for Your VPS

Wetin be n8n AI agent, and how e different from chain

An n8n AI agent na one AI Agent node wey get sub-nodes attached to am: one chat model, one or more tools, and optional memory. You go state goal for plain language, then the model go decide which tools to call and the order to call dem until e fit answer. Everything for here na configuration around that one idea.

Chain dey work the other way. For Basic LLM Chain, na you dey decide the steps, while the model only dey fill in text. For agent, na the model dey decide the steps, so the same question fit cost one model call today and nine tomorrow. Na this one difference dey control every setting for this guide.

This guide assume say n8n don already dey run behind HTTPS for machine wey you control. If e never dey run so, start with self-hosting n8n for Docker with real certificate, because the API key wey you wan store need the encryption-key backup wey that guide insist on. For patterns wey no use agent, like webhook summarizers and scheduled classifiers, see Claude and n8n workflow patterns.

Check your version before you trust any field name for here, because n8n dey change the AI nodes often.

docker compose exec n8n n8n --version

The names for this guide match n8n current stable as of July 2026. Since version 1.82.0, every AI Agent node dey run as Tools Agent, so the old agent-type dropdown no longer dey exist.

Step 1: choose the trigger

For conversational agent, add a Chat Trigger node. Leave Make Chat Publicly Available turned off while you dey build, so na only the editor chat panel fit reach am. Turn am on when you don finish the agent and decide the authentication wey you go use.

The Chat Trigger dey give the agent one field called chatInput. That name important for step 3, and mistake for this name na the most common first failure.

For unattended agent, use Schedule Trigger or Webhook node instead. None of dem dey produce chatInput, so you go write the prompt by yourself.

Step 2: model credential

Put one AI Agent node for the canvas. n8n go immediately show empty Chat Model connector under am. Attach one Anthropic Chat Model sub-node for there.

Create the credential from Anthropic Console for platform.claude.com, under Settings and then API Keys. Dem go show the key once only. API usage dey charge per token, and e separate from any Claude.ai subscription. So the account need billing setup before the first run.

Choose the model for each agent, no be for the whole company. One-tool agent wey just look up something and report am fit run well for Haiku. As of July 2026, Haiku dey list for $1 per million input tokens and $5 per million output tokens. Once the agent get many tools and need plan how to use dem, move am go Sonnet. The failure wey you dey avoid na cheap model wey call wrong tool four times. That one fit cost pass expensive model wey call correct tool once.

Set Maximum Number of Tokens for the sub-node options. E limit the length of every response wey the model produce. If you leave am for large default value, one confused run fit produce very long answer and make you pay for am.

One warning from n8n docs wey dey catch everybody: expressions inside sub-node always resolve against the first input item, never per item. Put expressions wey suppose work per item inside the root node prompt fields.

Step 3: prompt wey agent go receive

Open the AI Agent node. The Prompt parameter get two settings.

• Take from previous node automatically dey expect incoming field wey dem name chatInput. Na this one correct when e dey behind Chat Trigger.
• Define below go show Prompt (User Message) field where you fit write static text or expression. Na this one correct when e dey behind Schedule Trigger or Webhook node.

When Webhook node dey front, POST body go enter under $json.body, so the prompt field go look like this.

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.

Step 4: agent ke one tool give

AI Agent node wey no get tool sub-node no go run. Start with one, because one tool wey dey work go teach you pass four tools wey half-configured.

Connect HTTP Request node to agent Tool connector. Configure am exactly as you go configure normal HTTP Request node, then test the endpoint from shell first.

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

If that curl return error or HTML login page, agent go fail too. The failure go look like model problem, when na really URL or authentication problem. Fix am for shell, no be inside node.

The tool Description field no be documentation for your colleagues. Na the only thing model dey read when e dey decide whether this tool relevant. Write am as plain statement of wetin go come back: "E return the current up or down state and the downtime duration for one monitored service, as JSON."

To make model fill part of the request, use $fromAI() expression. E dey work only for tools wey connect to AI Agent node, and e no dey work for Code tool.

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

The arguments na key, then optional description, type and defaultValue. The key must get 1 to 64 characters, and e fit use letters, digits, underscores and hyphens. The type must be one of string, number, boolean or json, and e default to string. A fuller call go look like this.

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

The key na hint, e no be reference to data wey already exist. $fromAI('service') no dey read field wey dem call service from anywhere. E dey tell model, "produce a value and call am service", and model go check conversation, input data and results from other tools to find one. For chat workflow, e fit simply ask user.

Web search na the usual second tool. Since e just be another HTTP endpoint, you fit point this same node to your own SearXNG instance instead of paid search API, as long as you treat every page wey e bring back as untrusted text wey don enter your prompt.

Step 5: memory, and why the agent dey forget

If memory sub-node no dey, every message go start from zero. Attach a Simple Memory sub-node to keep the recent conversation.

E get two parameters. Session Key dey decide which conversation be this, so two users wey get different keys go get separate histories. Context Window Length na how many previous interactions go replay inside the prompt.

Context Window Length na cost control as much as quality control, because every remembered turn go send again as input tokens for every later call. Window of 20 for chatty agent mean say you go pay for the same early messages twenty times.

Simple Memory no dey work for active production workflow when n8n dey run for queue mode, because the history dey inside the workflow own data instead of shared store. For queue-mode instance, use Postgres Chat Memory sub-node instead, then point am to database wey both the main process and workers fit reach.

Step 6: System Message

Open the agent Options and add System Message. Na here you go put job description, and na the text wey get the biggest effect for the whole 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.

"Always call the status tool before answering" dey do real work for there. If you no put am, model wey think say e already know the answer fit skip the tool and answer from memory. That answer go confidently wrong immediately your infrastructure change.

Why agent dey loop, and wetin dey stop am

Also for Options, you go see Max Iterations, wey default na 10. One iteration na one model call plus one tool result wey go back into the context. So one agent run no be just one API call; e fit reach ten, and each one carry the whole conversation wey dey grow as input.

Reduce am. Plenty single-tool agents dey finish within two iterations, and limit of 3 or 4 turns runaway loop into clean failure wey you fit see for execution list.

While you dey debug, turn on Return Intermediate Steps. Final output go then include the tool calls wey agent make along the way. Na so you go know difference between “model never call the tool” and “tool return nothing useful.” Turn am off again before you go live, because those steps na noise for end user.

Watch one run happen from shell.

docker compose logs -f n8n

How to stop unattended agent from quietly spending

Agent wey dey behind Chat Trigger get human wey dey monitor am, and that human go stop am when the answer no look correct. Agent wey dey behind Schedule Trigger no get anybody wey dey watch am. Wetin you dey monitor here na model spend, no be licence spend, because agent, tool, and memory nodes all dey work for the free self-hosted edition, and the features wey need paid key na mostly team and governance ones. The full explanation dey for AI agent cost control on an always-on VPS. Four settings dey do most of the work here.

• Set limit for Maximum Number of Tokens for the model sub-node, so one response no fit run too long.
• Set Max Iterations to the smallest number wey still fit complete the task.
• Make tool responses small. Tool wey return 4,000-line JSON blob go put all of am inside the next model call, then inside every call after that for the same run.
• Ask whether agent really need schedule at all. Job wey dey run every five minutes go fire 288 times for one day. Any amount wey one run cost, na that figure you go multiply.

Deactivate the workflow while you dey iterate. Active workflow wey get Schedule Trigger go continue running against the version wey n8n don save, and that one no always be the version wey dey your screen.

FAQ

Why my AI Agent node no gree execute?

AI Agent node need one chat model sub-node and at least one tool sub-node. Node wey get model but no tool go fail before e make any API call. Attach one tool, even if na simple one, then run am again.

The agent dey answer, but e no ever call my tool. Wetin be the problem?

Almost every time, na the tool Description field dey cause am. Model dey choose tools by reading those descriptions, so description like "HTTP Request" no tell am when the tool dey useful. Rewrite am to explain wetin data go return and for which situation the tool dey useful. Then add one line for System Message wey instruct the agent to call that tool before e answer.

Why the same question dey cost different amount each time I run am?

Na because model dey choose how many steps e go take. Each iteration dey resend the complete conversation up to that point, including previous tool output. So run wey take four iterations go cost much more than four times one call. Max Iterations na the limit for this, while Return Intermediate Steps go show how many steps that particular run actually use.

My memory dey work for the editor but e no work for production. Wetin change?

Check whether the instance dey run for queue mode. Simple Memory dey store history inside the workflow own execution data. That data no survive when dem hand am over to separate worker process, so active production workflow go lose the history. Replace am with the Postgres Chat Memory sub-node. E dey keep history for the database wey every worker share.