4. The native AI Agent node in n8n 2.0

Description

In the previous lesson you saw the reason-act-observe loop as a concept: the sequence an agent runs internally when it decides what to do. Today you're going to open the node that runs that loop for you — you'll learn to recognize every connector on n8n 2.0's AI Agent node, tell apart which ones are required and which are optional, and understand what manual practices it replaced.

This matters because for years, before n8n had a native agent node, people who needed "something like an agent" built it by hand: an HTTP Request node calling the model's API, a Code node parsing the response as JSON, and a Switch deciding which branch to take based on what the model "said" it wanted to do. It worked, sometimes. But there was no real memory between steps, no controlled iteration limit, and every new branch meant more IF nodes stacked on top. If you walk into an automation team today and tell them you're going to "simulate an agent with a Switch," they're going to ask why you're not using the node that already does exactly that — and you need to be able to answer with the node's concrete anatomy, not just loop theory.

Connection to the module: lesson 3 gave you the mental model of the agentic loop; this lesson gives you its physical form on the n8n 2.0 canvas. Lesson 5 is going to dig into each of the four pieces that connect to the node (model, prompt, tools, memory) — today is just the map: what connectors exist, what parameters you configure, and how they relate to each other.

The root node and its connectors

Think of an old-style telephone switchboard, the kind with plugs and an operator sitting in the middle. The operator doesn't solve the caller's problems — she doesn't fix the invoice, she doesn't dispatch the order. What she does is listen to the call, decide which line to connect it to (accounting, warehouse, support) and, if needed, reconnect it to another line depending on the response that comes back. The operator is a central point with several plugs around her, each toward a different resource.

The AI Agent node is that operator. In n8n's documentation it's literally classified under the Root Nodes category: a node that doesn't work on its own, that needs other nodes connected to its special ports to have something to reason with and something to act with. The nodes that connect to those ports are called sub-nodes, and they don't travel through the flow's normal data path (the "main" connection, the horizontal line you already know from any n8n flow). They travel through a different kind of connection, reserved for AI, which in n8n's engine have their own names:

• ai_languageModel — the chat model.
• ai_memory — conversational memory.
• ai_tool — each tool.
• ai_outputParser — the structured output parser.

On the canvas, these connections don't look like the main straight line: they show up as small ports on the node's bottom edge, with curved lines going down to each sub-node. It's the visual signal for "this isn't data flowing, this is a piece the agent uses to think or act."

The AI Agent node's concrete ports, with their real behavior:

Port	Connection type	Required	Max connections
Chat Model	ai_languageModel	Yes	1
Fallback Model (if you enable the option)	ai_languageModel	Yes, once enabled	1
Memory	ai_memory	No	1
Tool	ai_tool	No, per the editor — but without one the agent can't act	unlimited
Output Parser (if you enable the option)	ai_outputParser	No	1

Two nuances matter here. First, the Chat Model port filters which nodes you can connect: it deliberately excludes some older chat model nodes (like the classic OpenAI node or the Hugging Face Inference one) because they don't properly support the structured tool-calling the agent needs to decide which tool to call. If you drag the wrong model in, the editor won't even let you connect it. Second, the Tool port doesn't carry a required asterisk in the editor — technically you can save the node without any tool connected — but an agent with no tools can only converse: it has no hands, only a mouth. n8n's official documentation is explicit about this: you need to connect at least one tool sub-node for the node to work as a real agent.

Worked example

Let's build the simplest possible agent and see what gets recorded. On the canvas, you connect three pieces to the AI Agent node: a Chat Trigger (to receive the message), a chat model, and a tool.

Step 1 — drag the node and connect the model. You drop "AI Agent" on the canvas. The node appears with a red "Chat Model" port asking for a required connection. You click the "+ Chat Model" button that appears right at that port, pick your OpenAI credential, and select the model.

Step 2 — connect a tool. You add an "HTTP Request Tool" node and connect it to the agent's "Tool" port. You give it a URL that looks up an order's status by ID.

Step 3 — define the prompt and options. In the node's panel, you leave "Source for Prompt (User Message)" set to "Connected Chat Trigger Node" (so the agent picks up the message coming from the Chat Trigger without you having to write anything else), and under "Options" you write a System Message.

If you export that workflow as JSON — something you can do from n8n's menu at any time to review or version your flow — the special connections look like this:

{
  "nodes": [
    {
      "name": "AI Agent",
      "type": "@n8n/n8n-nodes-langchain.agent",
      "typeVersion": 3.1,
      "parameters": {
        "promptType": "auto",
        "hasOutputParser": false,
        "options": {
          "systemMessage": "You are a support agent for an online store. Use the available tools before answering.",
          "maxIterations": 10,
          "returnIntermediateSteps": true
        }
      }
    },
    {
      "name": "OpenAI Chat Model",
      "type": "@n8n/n8n-nodes-langchain.lmChatOpenAi",
      "typeVersion": 1.3,
      "parameters": {
        "model": { "value": "gpt-5.4" }
      }
    },
    {
      "name": "Order Status Tool",
      "type": "@n8n/n8n-nodes-langchain.toolHttpRequest",
      "typeVersion": 1.1,
      "parameters": {
        "url": "https://api.example-store.com/orders/{{ $fromAI('order_id', 'The order ID mentioned by the customer', 'string') }}"
      }
    }
  ],
  "connections": {
    "OpenAI Chat Model": {
      "ai_languageModel": [[ { "node": "AI Agent", "type": "ai_languageModel", "index": 0 } ]]
    },
    "Order Status Tool": {
      "ai_tool": [[ { "node": "AI Agent", "type": "ai_tool", "index": 0 } ]]
    }
  }
}

What to expect: when you send "How's my order 4821 doing?" from the chat, the AI Agent node's execution panel shows, in order: a call to the model, a call to "Order Status Tool" with order_id automatically resolved by $fromAI() from the message, and finally the response text in $json.output. Since you left returnIntermediateSteps set to true, the output also carries an intermediateSteps array with every action the agent took before responding — that's your window for debugging without guessing what happened inside.

What this node replaced

The detail worth having clear to justify why this node exists: up through version 1.82 of n8n, the AI Agent node wasn't even a single thing internally — you had to pick an "agent type" from a dropdown (Conversational Agent, OpenAI Functions Agent, ReAct Agent, among others), each with its own internal logic and its own limitations. Since that version, that choice disappeared: every AI Agent node now works as a Tools Agent, the only type that survived because it was the most used and the most flexible. You no longer decide "what kind of reasoning" you want — the engine decides how to chain tools for you, and you just configure which tools are available.

n8n 2.0 added another layer on top of that: the redesign of the node's configuration panel (the view that opens when you double-click, previously behind a feature flag and now the default behavior) and improvements to how the canvas shows each node's visual state — for example, a direct warning right on the node itself when a connection you're going to need in production is missing, like "connect an additional model as fallback" as soon as you enable that option. That immediate feedback is exactly what a hand-built IF/Switch never gave you: there, if something failed halfway through the pseudo-loop, the error showed up three nodes later with no context about which piece was missing.

Common mistakes

Not connecting any tool because the editor doesn't require it. The Tool port doesn't carry a red asterisk like Chat Model does, so it's easy to save and publish an agent with no tool connected. The flow runs without errors — the problem is the agent can only converse, never act. You spot it when the System Message promises actions ("I'll check your order") but the response never reflects real data, just generic or made-up text. It's fixed by connecting at least one real tool sub-node before publishing.

Leaving "Max Iterations" at its default value for a task that needs several chained calls. The field ships with 10 by default, which is enough for most cases, but if your task requires the agent to call a tool, evaluate the result, call another one, and repeat that cycle several times, it can cut off halfway through without throwing any visible error — it just delivers an incomplete response. You spot it by turning on "Return Intermediate Steps" and counting how many steps appear: if the number matches the iteration limit, that's where the cutoff is. It's fixed by raising the value or simplifying the prompt so it needs fewer steps.

Dragging the wrong chat model node onto the Chat Model port. People coming from older automations sometimes try to connect the classic OpenAI node (the generic HTTP-request one, not the LangChain one) or a model like Hugging Face Inference. n8n filters those nodes out on purpose because they don't support the tool-calling format the agent needs to decide which tool to call. You notice it because the editor simply won't let you drop the connection onto that port. It's fixed by using the LangChain-family chat model node that matches your provider (for example, "OpenAI Chat Model," not "OpenAI").

Exercises

Exercise 1. You're handed this connections fragment from an exported workflow, and the flow never responds — the chat just sits there waiting:

"connections": {
  "OpenAI Chat Model": {
    "ai_languageModel": [[ { "node": "AI Agent", "type": "ai_languageModel", "index": 0 } ]]
  }
}

What's missing from this workflow for the agent to be able to act, even though nothing in the code above has a syntax error?

See solution

What's missing is any ai_tool-type connection to the AI Agent. The fragment only connects the chat model — syntactically valid, the node runs — but without any tool the agent can only generate conversational text. If the expected task requires querying an external system (an API, a database), the agent has no way to do it and likely gets stuck trying to "use a tool that doesn't exist" or responds with made-up information.

Why the fix works: adding a tool node (for example an HTTP Request Tool) and connecting it with "ai_tool": [[ { "node": "AI Agent", "type": "ai_tool", "index": 0 } ]] gives the agent a real resource to execute during the reason-act-observe loop.

Exercise 2. An agent has "options": { "maxIterations": 3 } and its task requires: (1) look up a customer's ID, (2) with that ID look up their orders, (3) with the most recent order check the shipping status, (4) format the response. What's likely to happen, and what would you change first?

See solution

It's likely the agent cuts off before reaching step 4: each tool call (steps 1, 2, and 3) counts as one turn of the loop, so with the limit at 3 the agent manages to make all three queries but runs out of room for the final turn where it puts together the response with that data — the result is an empty or cut-off response.

The first thing to change isn't necessarily bumping maxIterations blindly: I'd turn on "Return Intermediate Steps" to confirm it's actually cutting off there (and not for another reason, like a tool error), and only with that evidence would I raise the limit to a number that covers the task's real steps plus a reasonable margin.

Exercise 3. Explain in two or three lines, without using the word "Switch," why the AI Agent node isn't "the same thing but prettier" than building the decision by hand with conditional logic nodes.

See solution

It's not a matter of aesthetics: the AI Agent node delegates the decision of what action to take to the language model at runtime, inside a loop that repeats up to maxIterations without you predefining the possible branches. A chain of conditional logic nodes, on the other hand, can only follow routes you anticipated in advance when building the flow. If a combination of cases you didn't foresee shows up, the conditional logic node simply has no branch for it; the agent, with the right tools connected, can attempt a new combination because it isn't following a fixed script.

Summary and next step

You now recognize the AI Agent node's anatomy: a root node with special ports — Chat Model required and limited to one connection, Memory and Output Parser optional and also limited to one connection, Tool with no connection limit but essential in practice even though the editor doesn't mark it as required — and you know what it replaced: the agent-type dropdown that existed before version 1.82 (now everything is Tools Agent) and the manual chains of HTTP Request plus Switch people used to build before this node existed.

What you learned today is the map; in the next lesson you're going to step into each territory on that map: which chat model to choose and why the choice matters, how to write a System Message and a prompt that genuinely guide the agent, what types of tools exist and when to use each one, and what memory options there are beyond the simple conversation you tried here.

Before moving on you should be able to explain, without looking back at this lesson: which of the AI Agent node's four ports are required, what connection type each one uses (ai_languageModel, ai_memory, ai_tool, ai_outputParser), and what happens to an agent that has no tool connected.

Resources

• AI Agent node documentation — the node's official reference: description, connection requirements, and related links.
• Common issues — AI Agent node — frequent errors when configuring the prompt and model, including why at least one tool is needed.
• What agents do — explains the difference between an agent and a chain, and how it decides which tool to use.
• How tools work — how tool sub-nodes connect to the root node and what tools n8n ships out of the box.
• How memory works — why only agent nodes (not chains) can use memory, and the available memory options.
• n8n GitHub releases — the real changelog for each version, useful for confirming exactly what changed between 1.x and 2.0 before assuming a behavior.