You build an AI agent workflow in n8n by giving an agent step four things: a language model to reason with, a clear system prompt describing the job and its limits, memory so it can follow a conversation, and a small set of tools (HTTP requests, database queries, CRM actions or other workflows) it may call. A trigger starts it, the agent decides which tools to use to reach the goal, and the workflow then validates its output, routes anything risky to a person and logs what happened.
The difference between an n8n AI agent that impresses in a demo and one you can trust with real work is mostly in the parts around the model: narrow tools, structured output, guardrails and a test set. This guide walks through each part, describing steps by what they do rather than by exact node names, which change between versions. Check the current n8n documentation for the specific nodes and settings.
What is an AI agent in n8n, compared with a normal workflow?
A normal n8n workflow follows a fixed path you drew: if this, then that. An AI agent workflow hands part of the path to the model. You define the goal and the available tools; the model reads the input, decides which tools to call, in what order, looks at the results, and decides when it's done.
That flexibility is useful when the path genuinely varies. A customer message might need an order lookup, a refund policy check, both, or neither. It's unnecessary, and riskier, when the steps are always the same. If you're new to the concept, our explainer on what agentic AI is covers the idea.
A good rule: use fixed steps for anything predictable, and an agent only for the part that needs judgment. Many of the best n8n workflows are mostly deterministic with one agent step in the middle.
What are the building blocks of an n8n AI agent?
| Building block | What it does | Design advice |
|---|---|---|
| Trigger | Starts the run: webhook, chat message, email, schedule | Filter out noise before the agent sees it |
| Agent step | Runs the reasoning loop: think, call a tool, read result, repeat | One agent per job; keep the goal narrow |
| Model | The LLM that does the reasoning | Test a few on your own cases; set spend limits |
| System prompt | The job description, rules and output format | Specific, short, with explicit "never" rules |
| Memory | Conversation history across turns | Persist it per user or per case, with a size limit |
| Tools | Actions the agent may take | Narrow, validated, read-only where possible |
| Output parser | Forces a structured result | A defined schema the workflow can check |
| Post-processing | Validates, routes, logs | Where guardrails and human checkpoints live |
How do you choose the model?
n8n can connect to several LLM providers, and to local models if you self-host and have suitable hardware. Model capabilities and prices change quickly, so don't pick from a leaderboard. Instead:
- Build a small test set of 20 to 50 real inputs with the outcome you expect.
- Run two or three models against it and compare accuracy, tool-calling reliability, speed and cost.
- Consider splitting the work: a cheaper model for simple classification before the agent, a stronger one for the agent itself.
- Set spending limits at the provider, and cap the number of agent iterations per run so a confused agent can't loop indefinitely.
How should you write the system prompt?
The system prompt is the agent's job description. Write it like one:
- Role and goal. "You handle order-status questions for an online store's customers."
- What it can do. "Use the order lookup tool to find an order by number and email."
- What it must never do. "Never promise refunds. Never quote delivery dates not returned by the tool. Never reveal other customers' data."
- When to stop and hand off. "If the customer is upset, asks for a refund, or the order isn't found after one retry, set handoff to true."
- Output format. "Return reply, intent, handoff, and reason."
- Tone and language. "Short, friendly, in the customer's language."
Keep it focused. A prompt trying to cover five jobs produces an agent that does all five badly. If you have five jobs, build five agents or route to them with a classifier first.
How do you give the agent memory?
Each workflow execution starts fresh, so the agent only remembers what you load. For conversational agents, store the conversation history per user or per case and load the recent turns each run. n8n offers memory options for its agent features; check the current docs for which persist between executions (for example, backed by a database) rather than only within one.
Limit how much history you load. Long histories cost more tokens and can confuse the model. For facts that should persist beyond a conversation, like a customer's preferences or account details, look them up from your CRM as a tool or context step rather than relying on chat memory. Our explainer on AI agent memory covers the different kinds.
How do you design the tools?
Tools are where an agent touches your business, so they deserve the most care. Common tool types in n8n:
- HTTP request tools that call an API (your order system, a booking service, an internal endpoint).
- Database tools that run a defined query.
- App actions for CRMs, helpdesks, spreadsheets and email.
- Sub-workflows used as tools, so a whole n8n workflow becomes one action the agent can call.
- Document search over a vector store, for answering from your policies and knowledge base (the pattern known as retrieval-augmented generation, or RAG).
Rules we follow for every tool:
- One narrow job per tool, with a clear name and description. The model chooses tools based on those descriptions.
- Read-only first. Add write actions only when the read-only version works, and start them behind approval.
- Validate inputs inside the tool. If the agent passes an order number in the wrong format, the tool rejects it rather than querying blindly.
- Enforce permissions in the tool, not the prompt. A refund tool should cap the amount itself. Prompts can be talked around; code can't. Our post on prompt injection explains why this matters.
- Return short, structured results. A tool that returns a 200-field record wastes tokens and invites mistakes.
Sub-workflows are especially useful: you can build and test a "create support ticket" workflow on its own, with its own validation and logging, and then expose it to the agent as a single tool.
Why does structured output matter?
If the agent returns free text, the rest of your workflow has to guess what it meant. Ask for a defined structure instead, for example:
- reply: the message to send
- intent: one of order_status, return, product_question, other
- handoff: true or false
- reason: a short explanation
n8n supports output parsing for agent steps; check the current docs for how to define a schema. Then check the output in plain workflow logic: if handoff is true, route to a person; if intent is "other", don't auto-send; if the structure is invalid, retry once and then escalate.
Where do guardrails and human checkpoints go?
Put them after the agent, in ordinary workflow steps you can read and test:
- Validation: is the output well-formed and within allowed values?
- Policy checks: does the reply mention a price, a refund or anything on your blocked list?
- Confidence and handoff routing: low confidence or a handoff flag goes to a person.
- Approval for high-impact actions: anything that moves money, changes customer records or sends external messages waits for a human click at first.
- Logging: input, tool calls, output and final action stored for audit.
Our guides to AI agent guardrails and human-in-the-loop design go deeper on both.
How do you test an n8n AI agent before going live?
- Build the test set from real inputs, including awkward, ambiguous and adversarial ones ("ignore your instructions and...").
- Run every case and record: right tool calls, right outcome, right handoff, acceptable reply.
- Fix the tools and prompt, then rerun the full set, not just the case that failed.
- Shadow mode: run the agent on live inputs but have a person send the actual replies, comparing the two.
- Go live narrowly, for one channel, one customer segment or after-hours only.
- Review weekly and add every new failure to the test set.
Production concerns like error workflows, retries and monitoring are covered in making n8n workflows production-ready.
Frequently Asked Questions
Do I need to code to build an AI agent in n8n?
Not for the basic structure; the agent, model, memory and many tools can be configured visually. In practice, custom tools, data mapping and validation often need small code snippets or API knowledge, which is where a developer helps.
Which LLM works best with n8n agents?
There's no single answer, and rankings change fast. Test two or three models on your own cases, paying attention to how reliably they call tools and follow the output format, then weigh accuracy against cost and speed.
How many tools should an agent have?
As few as the job needs. A handful of well-described, narrow tools works far better than a long list. If you need many tools, split the work into several agents with a router in front.
Can an n8n AI agent take actions like refunds or updates?
Technically yes, but start with read-only tools and add write actions behind human approval. Enforce limits inside the tool itself, such as maximum amounts and allowed record types, so the agent can't exceed them.
How do I stop an agent from running up costs?
Cap the number of iterations per run, limit tokens per response, set spending limits at your LLM provider, and alert on unusual volume. Filtering irrelevant inputs before the agent step also cuts cost.
Want an n8n agent that does one job properly?
If you have a workflow where an AI agent could take real work off your team, tell us what the job is and which systems it touches. We'll design the tools, guardrails and tests so it works on a busy Tuesday, not just in a demo. See how we approach agentic AI development.