n8n's AI Agent node: the complete guide

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" (Google Scholar), 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.

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 RAG Assistant Pack (€119) ships an agent connected to a Supabase vector store, with conversation memory, a written system message and configured tools — a concrete starting point to adapt, rather than a blank page. And to go deeper on each connection, the guides on custom tools, memory and the output parser each cover their connector in depth.