A8gent
n8n AI Agents CourseGet full course
The AI Agent Node Explained cover
n8n AI Foundations · Lesson 2 of 14

The AI Agent Node Explained

The AI Agent node is the core of AI work in n8n. Learn what it does, the sub-nodes it connects to, and when to use it over a plain model call.

What the AI Agent node actually does

The AI Agent node in n8n is a cluster node that lets a language model decide which tools to call to complete a task, rather than following a fixed sequence you hardcoded. You give it a goal and a set of tools, and the model reasons about which tool to use, reads the result, and decides the next step, looping until it has an answer or hits its iteration limit. This is the difference between a fixed automation and an agent: the agent chooses its own path through the tools you gave it. Under the hood, modern n8n runs the AI Agent as a Tools Agent, which uses the model's native tool-calling ability rather than fragile prompt tricks.

The sub-nodes it connects to

The AI Agent node has connection points along its bottom edge for the pieces it depends on:

  • Chat Model (required): the language model that does the reasoning, such as an OpenAI or Anthropic chat model connected with your credentials.
  • Memory (optional): a store that feeds recent conversation history back into the agent each turn, covered in a later lesson.
  • Tool (optional, multiple): actions the agent may call, such as an HTTP Request tool, a Google Sheets tool, or a Call n8n Workflow tool.
  • Output Parser (optional): forces the agent's final answer into a structure you define, useful when a downstream node needs clean JSON.

The node settings that matter

Setting What it does Practical guidance
Prompt (User Message)The input the agent works on each runUsually an expression like the incoming chat message; a connected Chat Trigger fills it automatically
System MessageStanding instructions sent before the conversationThis is where role, rules, and boundaries live; never leave it on the default
Max IterationsHow many reasoning/tool loops before the agent must stop (default 10)Lower it for simple agents to cap cost and runaway loops
Return Intermediate StepsIncludes each tool call and result in the outputTurn on while debugging to see exactly what the agent did
Fallback ModelA backup chat model used if the primary failsWorth enabling in production workflows

Agent node versus a plain model call

n8n also offers a Basic LLM Chain node that sends a prompt to a model and returns the answer, with no tool use and no looping. The decision is simple:

Use Basic LLM Chain when... Use AI Agent when...
The task is one decision: classify, summarize, extract, rewriteThe model must gather information or act through tools before answering
The steps are known in advance and never varyThe path depends on what the data turns out to be
Cost and latency must stay minimal and predictableFlexibility is worth extra tokens and seconds

Do not use an agent where a single model call would do. The agent is slower, costs more, and is harder to predict. A surprising amount of "AI automation" is just one well-prompted LLM Chain node inside a normal workflow.

Writing the system message

The agent's behavior is shaped almost entirely by its System Message. Be specific about the role, the hard rules, and when to stop. Here is a working example you can adapt:

You are a support triage assistant for Acme Software.

Your job: read the incoming customer message, look up the customer
if needed, and either answer from the tools provided or escalate.

Rules:
- Only answer questions about Acme products, billing, and returns.
- Use the "Look up customer plan" tool before discussing billing.
- Never promise refunds or discounts. Escalate those.
- If a tool returns nothing useful, say you do not know and
  offer to connect the customer with a human. Do not guess.
- Keep answers under 120 words, plain language, no markdown.

What the node looks like as JSON

When you export a workflow, the agent and its model appear as a root node plus a sub-node joined by an ai_languageModel connection:

{
  "name": "Support Agent",
  "type": "@n8n/n8n-nodes-langchain.agent",
  "parameters": {
    "options": {
      "systemMessage": "You are a support triage assistant for Acme Software...",
      "maxIterations": 6
    }
  }
},
{
  "name": "OpenAI Chat Model",
  "type": "@n8n/n8n-nodes-langchain.lmChatOpenAi",
  "parameters": { "model": "gpt-4o-mini", "options": { "temperature": 0.2 } },
  "credentials": { "openAiApi": { "name": "OpenAI account" } }
}

Reading exported agent JSON like this is a fast way to audit someone else's template before importing it: you can see the system message, the model, and every tool at a glance.

What one agent run looks like

With Return Intermediate Steps on, you can watch the loop the agent actually ran. A single support question typically produces a trace like this:

User: "Why was I charged twice this month?"

Step 1  -> tool: look_up_subscription
           args: { "customer_email": "priya@example.com" }
           result: { "plan": "pro", "status": "active",
                     "last_charges": ["2026-06-01", "2026-06-03"] }
Step 2  -> reasoning: two charges present, the second matches a
           plan upgrade proration; refunds are out of scope
Final   -> "I can see two charges on your account. The June 3
           charge relates to your upgrade to Pro. If you believe
           this is an error, I will connect you with our billing
           team to review it."

Reading a few traces like this teaches you more about your agent than any amount of prompt theorizing: you see which tool it chose, what arguments it invented, and where its reasoning bent the rules. When an agent misbehaves, the trace is always the first place to look.

Building your first agent, in the order that works

The reason first agents feel unpredictable is usually build order: people attach five tools and a memory store before the thing has answered a single question. Build it in this order instead, executing at every step, and each new failure has exactly one possible cause.

  1. Chat Trigger plus AI Agent plus Chat Model. No tools. Ask it something it can answer from the system message alone. You are testing that credentials work and that the system message is being applied - nothing else.
  2. Add one tool. Ask a question that can only be answered using it. Turn on Return Intermediate Steps and confirm the trace actually shows the call. If it does not, the tool description is the suspect, not the model.
  3. Ask a question the tool cannot answer. This is the test people skip and it is the most important one. A well-configured agent says it does not know. A badly configured one invents an answer, and you want to discover that on your own laptop rather than in front of a customer.
  4. Add the second tool, and re-run both earlier questions. Tools interfere with each other. An agent that reliably picked the right tool when it had one will start choosing wrongly when two descriptions overlap, and re-running old cases is how you catch it.
  5. Only now attach memory. Memory changes the input on every turn, which makes every earlier failure harder to reproduce. Add it once the stateless behaviour is solid.

The general principle is the one from the previous lesson applied to agents: make the last change the only suspect. An agent is the least deterministic thing on an n8n canvas, so it deserves the most disciplined build order, not the least.

Tool descriptions are the actual control surface

New builders tune the system message when the agent picks the wrong tool. The system message is rarely the problem. The model chooses a tool by reading tool names and descriptions, so that is where selection is fixed.

Two descriptions for the same underlying HTTP call:

// Weak - the model has to guess what "customer info" covers
name: get_customer
description: Gets customer info.

// Strong - says what it returns, and when NOT to use it
name: look_up_subscription
description: >
  Returns the customer's current plan, subscription status, renewal
  date, and the last five charges, given their email address. Use for
  any question about billing, charges, plan level, or renewals. Does
  NOT return support ticket history - use look_up_tickets for that.

Three rules that fix most selection problems:

  • Name the fields it returns. The model is matching a question against a description; if "renewal date" never appears, a renewal question will not route here.
  • Say what it is not for whenever two tools are neighbours. Overlapping descriptions are the single biggest cause of an agent flip-flopping between tools across runs.
  • One tool, one job. A tool whose description needs "and" is two tools, and merging them makes both harder to select and harder to permission.

The same principle governs the tool's parameters. If an argument is an email address, say so in its description and give an example, or you will see the agent invent plausible-looking arguments - which shows up in the trace as a tool call with an email nobody ever supplied.

What an agent costs, and how to see it

An agent is not one model call. Each loop sends the whole conversation so far, plus every tool definition, plus every tool result returned to that point. A five-step agent run therefore costs considerably more than five times a single call, because the input grows on every step. This is worth internalising before you put one in front of volume, and it is measurable rather than theoretical: turn on Return Intermediate Steps, count the steps in the trace, and check the usage your model provider reports for that execution against a single Basic LLM Chain call doing a comparable job. Do it on your own workflow with your own model - published cost figures will not match your prompt.

Three levers, in order of effect:

  1. Do not use an agent. If the trace shows the agent calling one tool and answering, the loop bought you nothing. A Basic LLM Chain node with a normal HTTP Request node before it does the same job, faster and cheaper, and it never surprises you.
  2. Lower Max Iterations. The default allows a lot of room. If your traces never exceed three steps, six is a generous ceiling and it caps the damage when something loops.
  3. Return less from tools. Every tool result stays in context for the rest of the run. A tool returning a whole API response instead of the four fields the agent needs inflates every subsequent step of that run.

Reading a trace when the agent misbehaves

The trace tells you which of four things went wrong, and each has a different fix. Work down this list rather than rewriting the system message and hoping.

What the trace shows Diagnosis Fix
No tool call at all, agent answered from memoryThe tool was never a candidateTool description - add the words the question actually used
Right tool, invented argumentsParameter meaning is unclearParameter descriptions and an example value
Same tool called repeatedly with the same argumentsThe result did not answer the question and the agent is retrying blindlyReturn a clearer result, including an explicit "no records found" rather than an empty object
Correct tool calls, wrong final answerNow it really is the system messageAdd the missing rule, and add the case to the questions you re-test

The third row deserves attention because it is the expensive one. A tool that returns {} or an empty list when nothing matches gives the model no signal, so it tries again, and again, until Max Iterations stops it - and you pay for every loop. Make every tool return a sentence when it finds nothing: "No subscription found for that email address." That single change removes more runaway agent runs than any prompt edit.

Prerequisites: what has to exist before the node does anything

The AI Agent node is the one place in n8n where a correctly configured canvas can still refuse to run, because the node depends on things that are not on the main data connection. Four checks, in order, save most of the first-hour frustration. Details below are as of August 2026 against n8n's current documentation.

  1. A model credential exists and is tested. Create it in the Credentials area first, independently of any workflow, and use the connection test there. A credential that fails inside an agent produces an error that reads like an agent problem, which sends people editing the system message for twenty minutes.
  2. At least one tool sub-node is attached. This is a documented requirement, not a convention - you must connect at least one tool sub-node to an AI Agent node. If you genuinely want no tools, you did not want an agent; you wanted a Basic LLM Chain.
  3. You are not looking for an agent-type selector. Older tutorials tell you to choose between agent types - Conversational Agent, ReAct, Plan and Execute, and so on. That setting was removed: from version 1.82.0 onwards, every AI Agent node works as a Tools Agent, which was the recommended and most frequently used setting anyway. If a tutorial tells you to pick an agent type, it predates that change and everything else in it should be treated with suspicion too.
  4. The model you chose supports tool calling. The Tools Agent relies on the model's native tool-calling ability. Point it at a model without that capability and the agent will answer questions but never call anything, with no error to explain why - which looks exactly like a bad tool description and is not.

Reading the connection JSON, and auditing someone else's template

Most people's first agent comes from an imported template, and importing a template you have not read is how unpleasant surprises get onto a canvas. The good news is that agent workflows are unusually easy to audit, because the sub-node relationships are explicit in the export.

Select everything and press Ctrl+Shift+E to export the workflow as JSON. Sub-nodes do not use the ordinary main connection that carries items - they use typed connections, one per role. The three you will see constantly are ai_languageModel, ai_memory, and ai_tool:

"connections": {
  "When chat message received": {
    "main": [ [ { "node": "Support Agent", "type": "main", "index": 0 } ] ]
  },
  "OpenAI Chat Model": {
    "ai_languageModel": [ [ { "node": "Support Agent", "type": "ai_languageModel", "index": 0 } ] ]
  },
  "Look Up Subscription": {
    "ai_tool": [ [ { "node": "Support Agent", "type": "ai_tool", "index": 0 } ] ]
  },
  "Window Buffer Memory": {
    "ai_memory": [ [ { "node": "Support Agent", "type": "ai_memory", "index": 0 } ] ]
  }
}

Note the direction: the sub-node names the agent as its target, not the other way round. That is worth knowing because it is the opposite of how the canvas reads visually, and it means you find an agent's full capability list by searching the connections block for the agent's name rather than by looking under it.

With that, here is the audit to run on any template before you trust it - five minutes, and it is the same five minutes whether the template came from a marketplace, a colleague, or a video description:

  • List every ai_tool connection into the agent. That is the complete set of things it can do. Anything you would not authorise a new junior hire to do unsupervised should not be there.
  • Read every tool's parameters for write operations. An HTTP Request tool with a POST or DELETE method is an action, not a lookup, however innocently it is named.
  • Read the systemMessage in full. It is a single string in the JSON and it is where the actual behaviour lives. Templates frequently ship with a system message written for a different business.
  • Check maxIterations. If it is absent, the node default applies, which is 10.
  • Check for credentials referenced by name. An imported template refers to credentials that do not exist in your instance; those nodes will fail until you attach your own, and it is better to know that before you activate it than during a run.
  • Look for a Call n8n Workflow tool. That tool means the agent can trigger another workflow, so your audit is not finished until you have read that workflow too.

Troubleshooting: what agent failures look like from the outside

Agent failures are harder to read than ordinary node failures because the node succeeds while the behaviour is wrong. This table maps the visible symptom to the layer that actually needs the fix, so you stop editing the system message by reflex.

Symptom Layer at fault What to do
Node will not execute; complains about a missing connectionStructureA chat model must be attached, and at least one tool sub-node is required. Attach both before anything else
401 or 403 the moment the agent runsCredentialTest the credential on its own page. Do not debug this from inside the agent
Answers arrive but no tool is ever called, and the trace is empty of stepsModel choice or tool descriptionConfirm the model supports tool calling, then rewrite the tool description with the question's own words
Run ends after many steps with nothing usefulIteration limit reachedRead the trace for a repeated identical call. Almost always a tool returning empty instead of saying "nothing found"
Works in the editor, does nothing in productionActivationThe workflow was never toggled Active, or the trigger is an editor-only test trigger
Downstream node errors on the agent's outputOutput shapeThe agent returns prose. Attach an output parser, or add a Set node that extracts what the next node needs
Behaviour changed and nobody edited the workflowMemory or the modelMemory means the input differs every turn. Clear it and re-test statelessly to establish which of the two moved
The agent is correct on your test question and wrong on real onesTest setCollect ten real questions from real history and re-run all ten after every edit. One question is not a test

The last row is the habit that matters most and it costs almost nothing. Keep ten real inputs in a text file next to the workflow - the awkward ones, not the flattering ones - and re-run all ten after any change to a tool description, the system message, or the model. Without it, every edit is a guess, and you will spend weeks discovering that the fix for question three broke question seven.

The system message, rewritten from a first draft

Most first system messages are a job description. What the node needs is an operating procedure with boundaries. The same agent, written twice:

BEFORE
You are a helpful support assistant for Acme Software. Answer
customer questions accurately and professionally. Be friendly
and try to resolve their issue. Use the tools available to you
if needed.

AFTER
You are a support triage assistant for Acme Software.

Before answering any billing question, call
"look_up_subscription". Never answer a billing question from
memory, even if the customer states their plan.

Never state a refund amount, promise a refund, or offer a
discount. Route all of those to a human with the reason.

If a tool returns nothing useful, say you could not find the
record and offer to pass the customer to a person. Do not
guess, and do not try the same tool again with the same
arguments.

Keep answers under 120 words. Plain sentences, no markdown,
no bullet lists - this text is read aloud by an agent in
chat, not rendered.

Four differences, and each maps to a failure this lesson has already described. The AFTER version names when to call a specific tool, which is the fix for the trace showing no tool call at all. It states the prohibited actions as absolutes rather than as tone guidance. It tells the agent what to do on an empty result, which is what stops the repeated-identical-call loop that burns iterations. And it constrains the output shape, which is what keeps downstream nodes working.

The general test: read each sentence and ask whether you could tell from a transcript that it was obeyed. "Be friendly and professional" fails that test. "Never state a refund amount" passes it, and a rule you can check is a rule you can debug.

Common mistakes

  • Using the AI Agent node for a task a single Basic LLM Chain call would handle more cheaply and reliably.
  • Attaching many broad tools, which makes the agent's choices harder to predict and debug.
  • Leaving the System Message vague, so the agent guesses instead of following your rules.
  • Never adjusting Max Iterations, then paying for ten reasoning loops on a two-step task.

What you should be able to do now

  • Name the four sub-node connection types the AI Agent accepts and which one is required.
  • Decide for a given task whether it needs the AI Agent or a Basic LLM Chain, and defend the choice.
  • Write a system message with a role, hard rules, and an honesty clause.
  • Explain what Max Iterations and Return Intermediate Steps do and when to change them.
  • Read an agent trace and identify the tool calls, arguments, and final answer.

Where this goes next

That is the end of the free half. With the node model and this lesson you can build an agent, read its trace, and tell the difference between a prompt problem and a tool problem - which is most of what separates people who ship n8n agents from people who fight them.

The paid lessons take it into production. Attaching real tools including the Call n8n Workflow tool, so an agent can trigger workflows you already trust. Memory: which store to use, what actually gets replayed each turn, and why conversation history is the fastest way to inflate cost. Structured output parsers so downstream nodes receive JSON rather than prose. Error branches and retries for the API that is down at 3am. Multi-agent patterns and when they beat one agent with more tools. And the handover work - credentials, environments, and what to check before somebody else owns the canvas. Every lesson ships importable workflow JSON.

If you would rather have the agent built and handed over, that is project work we take on - see AI automation services, or start with the free automation audit, which will also tell you honestly when a workflow does not need an agent at all. The tool calling and AI agent glossary entries cover the vocabulary if you are explaining this to a colleague.

Enter your email below and both free lessons arrive with the workflow JSON - agent node, chat model, system message and all - ready to import onto your own canvas.

Key takeaways

What to remember from this lesson

  • The AI Agent node lets the model choose which tools to call and in what order, looping until it answers or hits Max Iterations. That choice is the whole difference from fixed automation.
  • Four sub-node connection types: Chat Model (the only required one), Memory, Tool (many), and Output Parser.
  • Use a Basic LLM Chain when the task is one known decision. Use the AI Agent only when the path depends on what the data turns out to be.
  • The System Message shapes almost all agent behavior: role, hard rules, and an explicit instruction to say 'I do not know' rather than guess.
  • Return Intermediate Steps turns the agent from a black box into a readable trace. When an agent misbehaves, the trace is the first place to look, not the prompt.

Try it yourself

Write the agent loop the AI Agent node runs for you

The AI Agent node is a loop: ask the model, run the tool it asked for, feed the result back, repeat until it answers or hits Max Iterations. The model below is a fixture that replays a scripted set of turns - no network call happens. Write the loop and you will never again wonder what Max Iterations actually caps.

Check yourself

Agent, or just a model call?

  1. You need to summarise every incoming support email into three bullet points. Nothing else. What should you build?

  2. Which sub-node connection is the only one the AI Agent node cannot run without?

  3. Your agent burns far more tokens than expected on a simple job and sometimes takes 40 seconds. Which setting should you look at first?

Answer every question to mark.

Exercise

Force an agent to show its work, then downgrade it

25 min
  1. 1Build a workflow with a Chat Trigger and an AI Agent node, and attach a Chat Model sub-node with your credentials.
  2. 2Write a System Message with all three parts from the lesson: a role sentence, at least two hard rules with the word 'never', and an honesty clause telling it to say it does not know rather than guess.
  3. 3Attach one narrow tool (an HTTP Request tool against any public JSON API is enough) and set Max Iterations to 3.
  4. 4Turn on Return Intermediate Steps and run one question that requires the tool. In the output, write down the tool name it chose, the exact arguments it invented, and its final answer.
  5. 5Now run a question your hard rules forbid. Confirm the agent refuses or escalates instead of answering. If it does not, the rule was not specific enough - tighten it and re-run.
  6. 6Replace the agent with a Basic LLM Chain node for a single classify-or-summarize task and compare the run time and token use against the agent doing the same job.

You are done when You can read your own intermediate-steps trace and name the tool call, its arguments, and the final answer; the forbidden question gets refused or escalated; and you have measured numbers showing the Basic LLM Chain is faster and cheaper for the single-decision task.

Companion files

Agent node config from this lesson

The exported agent plus chat-model JSON, including the support-triage system message, so you can import a known-good starting point and edit from there.

The free-preview pack includes 4 files of runnable code and config for The AI Agent Node Explained, plus the other free lessons of this course. No email needed.

Free preview pack - 8 KB zip

Check yourself

Answer before you reveal

Which of the AI Agent's sub-node connections is required, and which are optional?Show answer

Chat Model is required. Memory, Tool (any number), and Output Parser are all optional.

The task is: read an incoming email and label it as billing, technical, or sales. Agent or Basic LLM Chain?Show answer

Basic LLM Chain. It is one decision with no information to gather and no varying path, so the agent would only add cost, latency, and unpredictability.

Your agent takes ten reasoning loops on a two-step task. Which setting fixes it, and what is the side benefit?Show answer

Max Iterations - lower it to around 3. Besides capping cost, it turns a silent runaway loop into a visible stop you can debug.

Free lesson notes

Get the notes pack for n8n AI Agents Course, plus every new module free by email.

No card, no spam, unsubscribe any time.