How to Build n8n AI Agent for Your VPS

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

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

A 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, 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. If this loop new to you as an idea, instead of just as n8n feature, e good make you write one by hand once before you assemble am from nodes, because the node dey hide the exact part wey you go spend the rest of this guide dey reason about.

This assume say n8n don already dey run behind HTTPS for machine wey you control. If e never be so, start with self-host n8n on 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 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

Version 1.82.0 deprecated the agent-type setting and replace am with Tools Agent. Legacy v1 nodes still get the setting; n8n docs say dem go remove that node version for n8n 3.0.

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 an AI Agent node for the canvas. n8n go immediately show empty Chat Model connector underneath am. Attach Anthropic Chat Model sub-node there.

Create the credential from Claude Console for platform.claude.com, under Settings and then API keys. The key go show only once. The Console still go ask you to choose expiration when you create key. Unattended agent go stop working on the day the key expire, so write that date for place wey you go see am. For unattended agent, use service account key wey get scope for one workspace, so requests no need separate workspace header.

API usage dey billed per token. How you pay depend on your Claude plan, as of 31 October 2026. Max, Ultra and Team plans get monthly API credits: $100 for Max, $200 for Ultra, and up to $500 pooled for Team. You claim am by linking Console organization to the plan from Settings > Billing for Max or Ultra, or Organization settings > Billing for Team. You no need add payment method for the Console. New subscribers fit claim am after 7 days for the plan. Unused credits expire for the end of each billing cycle, or monthly for annual plans. When included credits finish, requests continue against purchased credits. auto-reload fit buy more, and invoiced organizations dey billed for excess usage. Requests stop when prepaid organization no get credits again. API usage never dey charged to your Claude plan. Free, Pro and Enterprise plans no get monthly API credits, so API billing dey separate from subscription for those plans.

Choose the model per agent, no be per company. One-tool agent wey just look up something and report am go run well on Haiku. The current version, Haiku 5.5, list price na $0.10 per million input tokens and $0.50 per million output as of 12 October 2026. The price rise to $0.50 and $2.50 for any request wey prompt pass 100,000 tokens. Long memory window and large tool results fit push you reach that level. When agent get several tools and need plan across dem, move to Sonnet. The failure wey you dey avoid na cheap model wey call wrong tool four times. That fit cost pass expensive model wey call correct tool once.

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

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

Step 3: di prompt wey agent dey receive

Open AI Agent node. Source for Prompt (User Message) parameter get two settings.

• Connected Chat Trigger Node dey expect incoming field wey dem name chatInput. Na this one you go choose when Chat Trigger dey behind am.
• Define below go show Prompt (User Message) field where you fit write static text or expression. Na this one you go choose when Schedule Trigger or Webhook node dey behind am.

When Webhook node dey in front, POST body go land 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 di

n8n docs talk say you must connect at least one tool sub-node to an AI Agent node, even though the current node code (version 3.1) only refuse to run when chat model no dey. Start with one tool either way, because one tool wey work go teach you more than four wey you configure halfway, and agent wey no get tool na just chain wey cost more.

Attach an 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, agent go fail too. The failure fit look like model problem when the real problem na URL or authentication. Fix am for shell, no be inside the node.

The tool Description field no be documentation for your colleagues. Model dey read am together with tool name and parameter schema when e dey decide whether the tool fit help. Write am as plain statement of wetin go come back: "E return the current up or down state and downtime duration for one monitored service, as JSON."

To make model fill part of the request, use the $fromAI() expression. E work only for tools wey connect to AI Agent node, and e no 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 default na string. A fuller call look like this.

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

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

Web search na the usual second tool. Since e be just 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

Without memory sub-node, every message dey start from zero. Attach Simple Memory sub-node to keep recent conversation.

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

Context Window Length na cost control as much as quality control, because every remembered turn dey 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 e dey store history inside process-local singleton Map wey workflow and session IDs dey key, and workers no dey share that memory. 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

For Options, you go also see Max Iterations, and e dey default to 10. One iteration na one model call. The call either request tools or return the final answer; tool results go enter the next call. So one agent run no be one API call. E fit reach ten calls, and every call carry the whole conversation wey dey grow as input.

Reduce am. Most single-tool agents dey finish within two iterations. 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 never call the tool" or "tool return nothing useful". Turn am off again before you go live, because those steps na noise for end user.

Watch one run as e dey happen from shell.

docker compose logs -f n8n

How to stop unattended agent from spending money quietly

Agent wey dey behind Chat Trigger get human person inside am, and that person go stop am when 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 free self-hosted edition, and the features wey really need paid key mostly na team and governance features. 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 on 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 other call for the same run.
• Ask whether agent really need schedule. Job wey dey run every five minutes go fire 288 times for one day. Any amount one run costs, na that amount you go multiply.

Unpublish the workflow while you dey test and adjust am, or at least remember which version dey live. Published workflow wey get Schedule Trigger go continue to run the version wey you publish last, no be the draft wey dey your screen, because n8n dey keep your edits as draft until you publish again.

FAQ

Why my AI Agent node no gree execute?

Check the connectors first. AI Agent node need a chat model sub-node, and if e no dey there, e go stop with "Please connect a model to the Chat Model input" before e make any API call. n8n docs also list at least one tool sub-node as required. So if model dey connected but the node still no gree, attach one tool, even if na simple one, then run am again.

The agent dey answer, but e never call my tool. Wetin dey wrong?

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

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

Because the model dey choose how many steps e go take. Each iteration dey resend the full conversation wey don happen so far, including previous tool output. So, if one run take four iterations, billing go include input and output tokens across all four calls. 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 dey work for production. Wetin change?

Check whether the instance dey run in queue mode. Simple Memory stores history inside one process-local singleton Map, with workflow and session IDs as keys. Separate worker processes no dey share am. Replace am with the Postgres Chat Memory sub-node. E stores history for the database wey every worker dey share.