How to Build n8n AI Agent for Your VPS

Wetin n8n AI agent be, 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 one goal for ordinary language, then the model go decide which tools to call and the order to call dem until e fit answer. Everything wey dey below na configuration around this 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 like that, start with how to self-host n8n for Docker with real certificate, because the API key wey you wan store needs the encryption-key backup wey that guide require. For patterns wey no use agents, 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: piki di trigger

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

Chat Trigger dey give agent one field wey dem call chatInput. That name matter for step 3, and if you write am wrong, na the commonest 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

Drop one AI Agent node for 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. The key go show only once. API usage dey billed per token, and e separate from any Claude.ai subscription. So, the account need billing setup before the first run.

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

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

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

Step 3: prompt wey agent go receive

Open 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 in front, POST body go land under $json.body, so 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: give the agent one tool

An AI Agent node wey no get tool sub-node go refuse to run. Start with one, because one tool wey dey work go teach you pass four wey never complete configuration.

Connect one HTTP Request node to the agent Tool connector. Configure am exactly as you go configure normal HTTP Request node, then test that 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, the 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 the node.

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

To make the model fill part of the request, use the $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, using letters, digits, underscores and hyphens. The type na one of string, number, boolean or json, and e dey default to string. A fuller call look like this.

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

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

Step 5: memory, and why the agent forgets

If memory sub-node no dey, every message go start from zero. Attach Simple Memory sub-node make e hold the recent conversation.

E get two parameters. Session Key dey decide which conversation dis be, 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, and point am to database wey both the main process and workers fit reach.

Step 6: di System Message

Open di agent Options and add System Message. Na here di job description dey go, and na di text wey get di biggest effect for di 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 di status tool before answering” dey do real work for there. If e no dey there, model wey think say e already know di answer fit skip di tool and reply from memory. E go dey confidently wrong as soon as your infrastructure change.

Why agent dey loop, and wetin dey stop am

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

Reduce am. Most single-tool agents dey finish for 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. The final output go then include the tool calls wey agent make along the way. Na so you fit know whether "model no ever call the tool" or "tool return nothing useful". Turn am off again before you go live, because those steps na noise for the end user.

Watch one run from the shell.

docker compose logs -f n8n

How you fit stop agent wey nobody dey watch from spending quietly

Agent wey dey behind Chat Trigger get human being inside am, and that person dey stop am when the answer no look correct. Agent wey dey behind Schedule Trigger no get anybody wey dey watch am. You fit see the full explanation for AI agent cost control for VPS wey dey always on. Four settings dey do most of the work here.

• Put 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 returns 4,000-line JSON blob go put all of am inside the next model call, and then inside every call after that for the same run.
• Ask whether the agent really need schedule. 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 to run against the version wey n8n don save, and that one no always be the version wey dey your screen.

FAQ

Why AI Agent node dey refuse to 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 e simple, then run am again.

Agent dey answer, but e no ever call my tool. Wetin dey wrong?

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

Why the same question dey cost different amount for each run?

Na because model dey choose how many steps e go take. Each iteration dey resend the full conversation so far, including previous tool output. So, run wey take four iterations fit cost far pass four times one single call. Max Iterations na the limit for that, and Return Intermediate Steps go show how many steps one run actually use.

My memory dey work for 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 dey survive when dem hand am to separate worker process, so active production workflow dey lose am. Replace am with the Postgres Chat Memory sub-node, wey dey keep history for the database wey every worker dey share.