n8n AI agent: build an agent with the AI Agent node, with a real example

To build an AI agent in n8n, you connect a trigger (Chat Trigger, Webhook or inbound email) to the AI Agent node, then attach a chat model (required), a memory and one or more tools underneath it: the agent reads the goal set in its system message and decides on its own which tools to call, in what order, and when to answer. The AI Agent node is probably the most powerful — and the most misused — node in n8n's AI palette. Many workflows deploy it where a simple LLM chain would do, and conversely, many rigid chains would be better served by an agent. The difference fits in one sentence: a chain always runs the same steps, while an agent decides for itself which tools to call, in what order, and when to stop. This guide covers how the node works (the Tools Agent), its four connections, the central role of the system message, enabling the output parser, and above all the limits you need to accept before shipping it to production. If you're just discovering n8n's AI palette, start with our introduction to AI nodes instead.

AI Agent vs Basic LLM Chain: two different logics

The Basic LLM Chain node is a pipe: a prompt goes in, the model answers, the response comes out. The path is fixed, known in advance, identical on every run. That's exactly what you want for classifying an email, extracting fields from an invoice or summarizing a document — tasks where you already know which steps follow which.

The AI Agent node (whose default mode is the Tools Agent, built on the native tool-calling mechanism of recent models) works differently: you give it a goal and a list of tools, and it builds its own plan. Faced with "what's the status of order 4521 and when will it be delivered?", the agent may decide to first call a database lookup tool, observe the result, then call a carrier API tool, before synthesizing an answer — without you having wired that sequence anywhere.

This approach has a precise academic foundation: the study by Yao et al. presented at ICLR 2023, "ReAct: Synergizing Reasoning and Acting in Language Models", showed that an LLM that interleaves reasoning traces with actions (tool calls followed by observations) solves tasks requiring external information better than a model reasoning alone, while reducing hallucinations since the model grounds itself in what it observes rather than in its internal memory. That's exactly the loop n8n's Tools Agent implements.

The node's four connections

Unlike classic nodes that have a single data input, the AI Agent node exposes specialized connectors below the node:

• Chat Model (required) — the agent's brain. You connect a conversational model here: OpenAI, Anthropic, Google, or a local model. The choice matters more here than for a simple chain, because the agent relies on the model's ability to correctly decide to call tools. Our guide to connecting Claude or GPT to n8n covers credential setup.
• Memory (optional) — without memory, every message starts from scratch: the agent forgets everything between runs, making any sustained dialogue impossible. Connecting a memory node (Window Buffer, Postgres Chat Memory…) is covered in detail in our article on conversation memory for an AI agent.
• Tools (optional, but this is the whole point) — every connected tool becomes a capability the agent can invoke: a calculator, an HTTP call, a query against a vector store, or even a full n8n sub-workflow exposed as a tool. Each tool's description is decisive, because that's what the model reads to decide whether to call it — we dedicate an entire guide to custom tools for the AI Agent.
• Output Parser (optional) — to constrain the final answer to a structured format, see below.

The system message: the single most important piece

The System Message field (in the node's options) defines the agent's role, scope and rules. It's the number-one control lever, well ahead of model choice. An effective system message specifies:

• Role and scope: "You are X's support assistant. You only answer questions about orders and deliveries."
• When to use each tool: "Use the lookup_order tool whenever an order number is mentioned. Never invent an order status."
• What the agent must not do: never promise a refund, never reveal other customers' information, escalate to a human when the request falls outside its scope.
• The tone and language of the final answer.

An agent without an explicit system message behaves like a chatty generalist: it answers everything, calls tools erratically and easily drifts out of its role. It's also the first line of defense against manipulation through the content it processes — a topic we dig into in our article on prompt injection and guardrails.

Choosing the model: tool-calling ability first

Not all models perform equally in agentic use. Three practical criteria:

• Tool-calling reliability: the agent spends its time deciding whether to call a tool and with which arguments; a model that produces malformed arguments or ignores the available tools makes the agent unusable, however good its prose.
• Cost/latency trade-off: every loop iteration (decision → tool → observation) is a model call. A fast, inexpensive recent-generation model is often enough for agents with 2-3 well-described tools; reserve top-tier models for agents whose decisions are genuinely complex.
• Context window: conversation history, tool descriptions and observations pile up in the context at every turn.

Start with a mid-range model, measure, then upgrade only if the agent's decisions are poor — not the other way around.

Structuring the output: Require Specific Output Format

By default, the agent answers in free text — fine for a chatbot, unusable when the rest of the workflow expects precise fields. The node offers the "Require Specific Output Format" option for this (matching the node's hasOutputParser parameter): once enabled, an Output Parser input appears under the node, to which you typically connect a Structured Output Parser configured with a JSON example or a schema.

The agent then receives the format instructions on top of its system message, and its final answer is validated and parsed before being handed to downstream nodes — which can read {{ $json.output.category }} directly instead of slicing text with regex. The full mechanics (schema, auto-fixing, failure cases) are covered in our Structured Output Parser guide.

The reasoning loop: tool → observation → decision

Concretely, an agent run unfolds like this:

1. The model receives the system message, any conversation history, the list of tools with their descriptions, and the user message.
2. It decides: answer directly, or call a tool with precise arguments.
3. n8n executes the tool and returns the result to the model as an observation.
4. The model incorporates the observation and decides again: another tool, the same tool with different arguments, or a final answer.
5. The loop repeats until a final answer is produced or the iteration limit is hit (the node's Max Iterations option, an essential safeguard against infinite loops).

Every iteration is visible in n8n's execution logs: you can read which tools the agent called, with which arguments and which observations — the first debugging reflex when an agent misbehaves.

A real AI agent, node by node

To make this concrete, here is the agent shipped in the Compliance & Audit Pack, the guided questionnaire bot workflow: it runs a simplified 8-question GDPR audit and saves every validated answer to Supabase. The file contains five working nodes:

Node	Role in the agent	Setting in the delivered file
Chat Trigger	opens a public chat page and passes each message on	public: true, welcome message asking for the company name
AI Agent ("Agent questionnaire")	runs the interview and decides when to save	system message with the 8 questions and 6 absolute rules
OpenAI Chat Model	the model wired as ai_languageModel	gpt-4o-mini
Window Buffer Memory	keeps the thread of the conversation	last 12 exchanges (contextWindowLength: 12)
HTTP Request Tool ("Enregistrer la réponse", save the answer)	the agent's only possible action	POST to /rest/v1/audit_responses, three-field body filled in by the model: dossier_id, question, reponse

Three design choices apply to any agent:

• The system message sets rules, not just a persona. Here: one question at a time, rephrasing followed by explicit validation by the user, and a tool call only after that validation. That is what stops the agent from writing a misunderstood answer to the database;
• The tool description says when to call it. The model does not see the node; it reads its description (in the delivered file, in French: "call this tool after EVERY validated user answer…") and its named parameters. A vague description produces an agent that forgets to save, or saves too early;
• One tool, with a narrow effect. The agent can only add a row to a table. A note in the workflow spells it out: the Supabase service_role key must never be published, and the safer alternative is to point the tool at the webhook of the pack's recording workflow rather than straight at the database.

Conversely, the workflows in the Inbox AI Pack use Basic LLM Chains, not an agent: sorting or prioritizing an email always follows the same path, so a chain is enough and costs fewer tokens.

Limits and best practices

Autonomy comes at a price, and you need to know it before going to production:

• Cost: an agent chaining 4 tool calls makes at least 5 model calls, with a context that grows at every turn. At real volume, the bill surprises — instrument from day one with our method to track the cost of AI calls.
• Latency: each iteration adds seconds. A conversational agent that takes 20 seconds to answer is a product problem, not just a technical one.
• Drift: on ambiguous requests, the agent may call irrelevant tools, loop, or hallucinate an answer when no tool fits. The countermeasures: precise tool descriptions, a strict system message, a low iteration limit, and regular testing against a representative set of cases.
• Predictability: an agent is not deterministic. For anything involving irreversible actions (sending an email, writing to a database, issuing a refund), prefer human validation or a fixed chain downstream of the agent.

The simple rule: fixed chain by default, agent when the path genuinely depends on the request. Ticket triage always follows the same steps — chain. An assistant answering varied questions by drawing on a document base, a CRM and a calendar — agent.

Where to start

The shortest path to seeing a Tools Agent work under real conditions is to start from a complete example: the Compliance & Audit Pack (€149) contains the agent described above (Chat Trigger, AI Agent, session memory, Supabase recording tool, written system message), along with the three other audit-trail workflows, to import and adapt to your own framework (quality, security, ESG) rather than starting from a blank page. If what you need is answers drawn from your own documents, the RAG Assistant Pack (€119) does it with a question-and-answer chain over a Supabase vector store, without an agent. And to go deeper on each connection, the guides on custom tools, memory and the output parser each cover their connector in depth.