An n8n AI agent is a workflow built around the AI Agent node: you connect a chat model, memory and one or more tools, and the model decides which tools to call to finish a request. This tutorial builds a working support agent step by step, compares self-hosting with n8n Cloud, and covers prompts, safety and common errors.
- The AI Agent node needs three things: a chat model, at least one tool, and usually a memory node such as Simple Memory.
- Any n8n integration can become a tool, and the Call n8n Workflow Tool turns whole workflows into tools the agent can use.
- Self-host the Community Edition with one Docker command, or use n8n Cloud from $20 a month billed annually.
- Turn on human review for tools that send messages, change records or spend money.
- Write a specific system message that names each tool and when to use it; most agent mistakes start there.
What is an n8n AI agent?
An n8n AI agent is a workflow where the AI Agent node receives a request, reasons about it, and calls connected tools until it can answer. Per the AI Agent node docs, you connect a chat model and one or more tools, and the agent decides which tools to call to complete a task.
The AI Agent node is a "root node" with slots for sub-nodes:
| Slot | What goes in it | Required |
|---|---|---|
| Chat Model | OpenAI, Anthropic, Google Gemini or another chat model node | Yes |
| Tool | Any tool sub-node: Google Sheets, HTTP Request, a workflow, code, an MCP server | At least one |
| Memory | Simple Memory or a database-backed memory | Recommended for chat |
| Output Parser | Forces structured output | Optional |
Since n8n 1.82.0 every AI Agent node works as a Tools Agent; the older agent type setting is deprecated, and the v1 node that had it will be removed in n8n 3.0. If you follow an old tutorial that mentions "Conversational Agent" or "ReAct Agent," use the current node and connect tools instead.
n8n also has a newer Agents feature (in Preview at the time of writing), built in a separate Agent Builder with instructions, tools, skills, channels such as Slack and schedules. This tutorial uses the AI Agent workflow node, which is stable and what most production n8n agents run on. If agents are new to you, our explainer on what AI agents are covers the reasoning loop behind both.
Should you self-host n8n or use n8n Cloud?
Self-host if you are comfortable running a Docker container and want no execution limits; use n8n Cloud if you want to start in minutes and never patch a server. Model costs are separate either way: you bring your own API keys.
| Option | Cost (October 2026) | Good for |
|---|---|---|
| Community Edition, self-hosted | Free software; you pay for the server | Tinkering, privacy, high volume |
| Cloud Starter | $20 a month billed annually, 2,500 executions | First production workflows |
| Cloud Pro | $50 a month billed annually, 10,000 executions | Small teams, more concurrency |
| Business (self-hosted) | $800 a month billed annually, 40,000 executions | Larger teams on their own servers |
Prices are from the n8n pricing page at the time of writing. n8n Cloud counts workflow executions regardless of how many steps each one has, so an agent that calls five tools in one run is still one execution.
For a broader comparison with other automation platforms, see Zapier vs Make vs n8n.
How do I run n8n locally with Docker?
Create a volume for your data, run the official image, and open http://localhost:5678. This is the command from n8n's Docker install docs:
docker volume create n8n_datadocker run -it --rm \ --name n8n \ -p 5678:5678 \ -e GENERIC_TIMEZONE="Europe/Berlin" \ -e TZ="Europe/Berlin" \ -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \ -v n8n_data:/home/node/.n8n \ n8nio/n8nReplace the time zone with yours; GENERIC_TIMEZONE controls when Schedule Trigger nodes fire. The n8n_data volume keeps your workflows and credentials across restarts. Create the owner account in the browser and you are ready.
Do not expose port 5678 to the internet without HTTPS and authentication in front of it. n8n stores credentials for every service your agent can reach.
Step by step: build your first n8n AI agent
You will build a support agent that answers order questions from a Google Sheet and drafts replies, with a human approving anything it sends. The same pattern works for most business agents.
- Create a workflow. In n8n, select Create workflow and name it "Support agent."
- Add a Chat Trigger. Search for Chat Trigger and add it. It gives you a test chat window in the editor. Later you can turn on Make Chat Publicly Available and choose Hosted Chat (n8n's chat page) or Embedded Chat (your own widget calling the webhook), as described in the Chat Trigger docs.
- Add the AI Agent node after the trigger. Leave the prompt source on the chat input.
- Connect a chat model. Click the Chat Model slot, pick a provider (for example Anthropic or OpenAI), create a credential with your API key, and choose a model. A mid-sized model is plenty for lookups and drafting.
- Add memory. Click the Memory slot and add Simple Memory. Its two settings are the Session Key (which conversation the history belongs to) and Context Window Length (how many previous interactions to keep). Five to ten is a good start.
- Add a lookup tool. Click the Tool slot, add Google Sheets, connect your credential, and set the operation to read rows from your orders sheet. Give the tool a clear name and description, such as "Look up an order by order number."
- Add a reply tool. Add a Gmail (or Outlook) tool set to create a draft or send a message.
- Write the system message in the AI Agent node's options (template in the next sections).
- Test in the chat panel. Ask "Where is order 1042?" and open the execution log to see which tools the agent called and with what inputs.
- Activate the workflow once the test conversations look right.
Opening the execution log after every test is the habit that matters most. It shows exactly what the model decided, which is how you find a vague tool description or a missing instruction.
How do you give an n8n agent tools?
Attach tool sub-nodes to the AI Agent's Tool slot; almost any n8n integration can be one. The tools documentation highlights a few that do most of the work:
- App nodes as tools: Google Sheets, Gmail, Slack, Notion, HubSpot, Postgres and hundreds more.
- HTTP Request Tool: calls any API or fetches a web page.
- Call n8n Workflow Tool: loads another n8n workflow as a tool. Use it to wrap a multi-step process (check stock, then reserve, then log) behind one tool the agent can call.
- Custom Code Tool: runs code you write, for calculations or data shaping.
- MCP servers: n8n can connect servers from an MCP registry as tools. Our guide to what MCP is explains how those servers work.
Two details make tools reliable. First, name and describe every tool in plain words: the model chooses tools by reading those descriptions. Second, let the model fill parameters with the $fromAI() function, for example {{ $fromAI('order_number', 'The order number the customer mentioned') }} in the Sheets lookup field, so the agent passes exactly the value the tool needs.
How should you write the agent's system message?
Tell the agent who it serves, what each tool is for, what it must never do, and how to answer. A vague system message is the most common reason agents call the wrong tool or invent answers.
You are the support assistant for Acme Coffee, an online coffee shop.Tools:- "Look up order": use it whenever the customer gives an order number. Never guess order status without calling it.- "Draft reply": use it only after you have the facts, to prepare an email to the customer. A human approves every email.Rules:- If an order is not found, ask the customer to confirm the number.- Refunds and cancellations: do not promise anything. Say a team member will follow up, and draft a reply for review.- Never share another customer's details.Style: friendly, short, plain English. Two to four sentences.Write it, test five realistic conversations (including one rude customer and one off-topic question), and adjust. Keep a list of those test conversations so you can rerun them after every change.
How do you keep an n8n AI agent safe?
Require human approval for risky tools, limit credentials, protect the chat endpoint, and watch for prompt injection in the data the agent reads.
- Human review for tools: n8n can pause before an agent runs a specific tool and wait for a person to approve or deny it, per the human-in-the-loop docs. Open the Tools panel on the AI Agent node, add a Human review step, pick a channel (n8n Chat, Slack, Telegram and others), and connect the risky tools to it. Use it for sending email, editing records, deleting data or payments.
- Least-privilege credentials: give the agent a Google account that can read the orders sheet, not your whole Drive.
- Chat authentication: if the chat is public, set the Chat Trigger's authentication to Basic Auth or n8n user auth unless it is meant for anonymous visitors.
- Untrusted input: emails, web pages and form entries can contain instructions aimed at the model. Our post on prompt injection explains the pattern; the defense in n8n is the same: approval on actions, and tools that cannot do more than the job needs.
- Memory in queue mode: Simple Memory does not work reliably when n8n runs in queue mode, because calls can go to different workers. Use a database-backed memory node there.
What can you build with an n8n AI agent?
Good first agents have a narrow job, two to four tools and a clear person who checks the output. Three patterns that work well:
| Agent | Trigger | Tools | Human check |
|---|---|---|---|
| Inbox triage | New email (Gmail Trigger) | Classify, look up customer in CRM, draft reply | Approves drafts |
| Lead research | New form submission | HTTP Request to the company website, web search, CRM update | Reviews CRM notes weekly |
| Internal Q&A | Slack message or Chat Trigger | Vector store with your docs, Google Drive search | Flags wrong answers |
For more ideas with concrete setups, see our list of AI automation examples.
Common n8n agent problems and fixes
Most failures trace back to tool descriptions, memory settings or missing data in the prompt.
| Symptom | Likely cause | Fix |
|---|---|---|
| Agent answers without calling a tool | Tool description vague, or system message does not require it | Name the tool and when to use it in the system message |
| Wrong values passed to a tool | Parameter left for the model to guess | Use $fromAI() with a clear description per field |
| Agent forgets earlier messages | No memory node, or session key changes | Add Simple Memory with a stable session key |
| Error about missing tool | AI Agent node has no tool connected | Connect at least one tool sub-node |
| Costs higher than expected | Large model, long memory window | Smaller model, shorter context window length |
| Old template fails after update | v1 AI Agent node with agent type setting | Replace with the current AI Agent node |
How to start today
Build the smallest useful agent first, then add tools one at a time.
- Run n8n in Docker or start an n8n Cloud trial.
- Build the Chat Trigger, AI Agent, model and Simple Memory skeleton, and confirm it chats.
- Add one read-only tool and test until the agent calls it every time it should.
- Write a system message that names each tool and the rules.
- Add one action tool behind human review.
- Save five test conversations and rerun them after each change.
If your automations grow into code, such as custom nodes, scripts or a small app, coding agents can write and maintain that code for you; Orkio offers an Automation kit on an always-on box where agents like Claude Code keep working after you close your laptop.
Frequently asked questions
Is n8n free for AI agents?
The self-hosted Community Edition is free to run on your own server, but you still pay the AI provider for model usage. n8n Cloud plans start at $20 a month billed annually for 2,500 workflow executions, at the time of writing.
Which AI models work with the n8n AI Agent node?
n8n supports chat models from providers such as OpenAI, Anthropic and Google, plus others through dedicated nodes. You add the model as a sub-node with your own API credentials, so you can switch providers without rebuilding the workflow.
What is the difference between an n8n AI agent and a chain?
A chain runs fixed steps in order, while an agent decides which tools to call and in what order based on the request. In n8n, agent nodes can use memory and tools; chains cannot use memory.
Can an n8n AI agent use MCP servers?
Yes. n8n can connect MCP servers as tools for an AI agent, including one-click connections to servers in its MCP registry. Treat MCP tools like any other tool and add human review to the ones that change data.
Why does my n8n agent forget earlier messages?
Usually the memory node is missing, the session key changes between messages, or the context window length is too small. Simple Memory also does not work reliably in queue mode, so use a database-backed memory node there.
