The n8n AI Agent node has one required input (a Chat Model) and a small pile of optional ones, and most of the trouble people hit comes from misreading what each input actually does. This is the reference: what every input and option means, what to set it to, and where it bites.
TL;DR: The AI Agent node is a root node that takes a Chat Model (required), optional Memory, and one or more Tools as connected sub-nodes, then loops "reason, call a tool, read result" until it produces a final answer or hits Max Iterations (default 10). The current default agent type is the Tools Agent - it uses the model's native tool-calling and replaces most of the older agent types. The settings that matter most: a specific System Message, Max Iterations sized to your tool chain, Require Specific Output Format only when a downstream node needs clean JSON, and Return Intermediate Steps on while you debug and off in production.
What the node actually is
The AI Agent node is a root node in n8n's LangChain-based cluster. It is not a model wrapper that takes text in and gives text out once. It is a loop. You hand it a model, a list of tools, and a task, and it decides which tools to call, in what order, reads each result, and keeps going until it thinks it is done or runs out of iterations.
That loop is the whole point and the whole risk. A Basic LLM Chain node answers once and is predictable. The Agent node can chain five tool calls to answer one question, which is powerful when the task is genuinely multi-step and wasteful when it is not. If your task is "classify this email into one of three buckets," you do not want an agent. You want an LLM Chain. Reach for the Agent node when the model needs to choose actions based on intermediate results.
The inputs: chat model, memory, tools
The Agent node has three connection points along its bottom edge, and they are not equal.
Chat Model (required)
This is the only required sub-node. Connect exactly one chat model - OpenAI, Anthropic, Google Gemini, Ollama, Groq, or any other supported provider. The model must support tool/function calling for the Tools Agent to work, which in practice means a recent chat model rather than an old completion model. If you connect a model that cannot call tools and wire up tools anyway, the agent will not use them.
Pick the model for the job, not the brand. A capable mid-tier model handles most routing and summarization agents fine; reserve the top-tier reasoning models for agents that genuinely chain many tools or do hard logic. The model is also where your token cost lives, so a chatty agent on an expensive model with Max Iterations set high is how you get a surprising bill.
Memory (optional)
Memory makes the agent remember earlier turns in the same conversation. Without it, every execution is stateless - the agent sees only the current prompt and whatever you passed in. With it, the agent sees prior messages, which is what you want for a chatbot and usually what you do not want for a one-shot batch job.
The options run from Simple Memory (in-process, fine for a single instance and short-lived chats) to Postgres, Redis, and MongoDB chat memory (persistent, survives restarts, works across a queue-mode setup with multiple workers). Use Simple Memory for a quick prototype. Use Postgres or Redis the moment the agent runs on more than one worker or needs to remember across restarts, because Simple Memory lives in the memory of one process and vanishes with it.
The gotcha: memory is keyed by a session ID. If every execution uses the same session key, all your users share one conversation history. If the key is unique per execution when it should be per user, nobody remembers anything. Set the session key deliberately - usually a user ID or chat ID.
Tool (optional, repeatable)
Tools are what the agent can do. Connect as many as you need: HTTP Request tool, Code tool, a sub-workflow as a tool, vector store retrieval, Calculator, Gmail, and so on. Each tool has a name and a description, and the description is not decoration - it is the only thing the model reads to decide whether to call that tool. A vague description ("does stuff with data") gets the tool ignored or misused. A precise one ("Look up a customer's current subscription status by email address; returns plan name and renewal date") gets it called at the right time.
Two practical rules. First, fewer good tools beat many overlapping ones; if two tools could plausibly answer the same request, the model will sometimes pick the wrong one. Second, for HTTP and sub-workflow tools you can let the model fill parameters dynamically with the $fromAI() expression, so the agent decides the argument values at runtime instead of you hardcoding them.
If you are building tools as sub-workflows and want them to be reusable across agents, the skill files approach and reusable tool definitions are worth setting up early rather than copy-pasting node configs.
Agent type: use the Tools Agent
n8n historically shipped several agent types - Conversational, OpenAI Functions, Plan and Execute, ReAct, SQL. The current default and the one to use is the Tools Agent. It relies on the model's built-in tool-calling rather than parsing tool requests out of free-form text, which makes it more reliable across providers. The older types still appear in documentation and old workflows, but for new builds the Tools Agent is the right answer unless you have a specific reason (a SQL-only task, a model with no native tool-calling) to do otherwise.
If you see a tutorial telling you to pick "ReAct" or "Conversational Agent," it is likely written against an older n8n version. Build on the Tools Agent.
The parameters that matter
Open the node and you get a short list of top-level parameters plus an Options accordion. Here is what each one does and what to set it to.
Source for Prompt (User Message)
Two choices: Connected Chat Trigger Node or Define below.
Use Connected Chat Trigger Node when the agent sits behind the Chat Trigger - the user's message flows in automatically and you do not type a prompt. Use Define below for everything else: a webhook-driven agent, a scheduled job, an agent processing rows from a sheet. With Define below you write the prompt yourself and pull data in with expressions, for example:
Summarize the support ticket below and decide if it needs escalation.
Ticket subject: {{ $json.subject }}
Ticket body: {{ $json.body }}
Customer plan: {{ $json.plan }}
This is the most common point of confusion: people leave it on the trigger setting in a non-chat workflow and wonder why the prompt is empty.
Require Specific Output Format
A toggle. Off by default, and the agent returns whatever text it produces. Turn it on when a downstream node needs structured data - then connect an output parser sub-node (Structured Output Parser with a schema, or an auto-fixing parser) and the agent is constrained to return JSON matching it.
Leave this off if the agent's job is to write a human-readable reply. Turn it on if the next node is a Set, an IF, or anything that reads specific fields. The cost of forcing structure is a slightly higher chance the model fights the format on hard inputs, which is why the auto-fixing parser exists - it re-prompts the model to correct malformed output.
System Message
This is the highest-leverage setting in the node. The system message defines the agent's role, its constraints, when to use which tool, and crucially what the final answer should look like. A vague system message is the number one cause of agents that loop pointlessly or call the wrong tool.
Be specific and directive:
You are a support triage agent. For each ticket, decide one action:
RESOLVE (answer directly), ESCALATE (route to a human), or
INFO_NEEDED (ask the customer one clarifying question).
Use the lookup_subscription tool only when the ticket mentions billing,
plans, or renewals. Do not call it otherwise.
Always end with a single line in the form: ACTION: <RESOLVE|ESCALATE|INFO_NEEDED>
Keep your reasoning to two sentences.
Telling the agent exactly what the final answer should look like ("end with a single line in the form...") does more to stop runaway loops than any iteration cap, because the model knows when it is finished.
Max Iterations
The cap on how many reason-and-act loops the agent runs before it stops. Default is 10. Each iteration is roughly one round of "think, optionally call a tool, read the result," so an agent that needs to call three tools in sequence needs at least three or four iterations of headroom.
Set it to the realistic depth of your tool chain plus a small buffer, not to a big round number. A two-tool agent does not need 25 iterations; that just lets a confused agent burn tokens. Watch the failure mode: when the agent hits the cap it returns "Agent stopped due to max iterations." And there is a known sharp edge - if you set the node's error handling to "Continue (using error output)," hitting Max Iterations can route to the success output rather than the error output, so do not assume a max-iterations stop will land in your error branch. Test it.
Return Intermediate Steps
A boolean. When on, the output includes every tool the agent called and what each returned, not just the final answer. Turn it on while building and debugging - it is the fastest way to see why an agent picked a tool or got stuck. Turn it off in production, because the intermediate steps bloat the output payload and you usually only want the final result downstream.
Automatically Passthrough Binary Images
When on, binary image data in the input is passed through to a vision-capable model automatically, so the agent can reason over images without you wiring up the binary by hand. Only relevant when your model supports vision and your input actually carries images; leave it off otherwise.
Streaming and tracing
The Options accordion also exposes streaming (real-time token output, useful for chat UIs where you want the reply to appear as it generates) and tracing metadata (attaches identifiers to executions for observability tooling). Neither changes the agent's logic; they change how you watch it. Enable streaming for interactive chat front-ends, leave it off for batch and webhook agents where you just consume the final payload.
Sane defaults to start with
For a typical tool-using agent behind a webhook or trigger:
-
Agent type: Tools Agent.
-
Chat Model: a capable mid-tier model; upgrade only if it visibly struggles.
-
Memory: none for one-shot tasks; Postgres or Redis chat memory for real conversations on multi-worker setups.
-
System Message: specific role, explicit tool-use rules, explicit final-answer format.
-
Max Iterations: your longest realistic tool chain plus 2-3, often 5-8 rather than the default 10.
-
Require Specific Output Format: on only when a downstream node parses fields.
-
Return Intermediate Steps: on in dev, off in prod.
Common gotchas
The same handful of mistakes account for most broken agents. Tool descriptions that are too vague to be selected correctly. Prompt source left on the trigger setting in a non-chat workflow, leaving the prompt empty. A shared memory session key leaking one user's history into another's. Max Iterations set so high that a confused agent loops expensively instead of failing fast. And expecting a max-iterations stop to hit the error output when, with "Continue (using error output)" set, it can land in the success path instead.
One more architectural note: if you find yourself giving one agent a dozen tools and a sprawling system message, that is usually a sign the work should be split - either into a retrieval-augmented setup where a vector store handles knowledge, or into smaller agents and sub-workflows. A few tools the agent uses well beats a toolbox it navigates badly. For the heavier custom logic some tools need - reshaping data, calling an API with bespoke auth - a Code node wrapped as a tool is cleaner than stretching a generic node to fit.
FAQ
What is the difference between the AI Agent node and the Basic LLM Chain node?
The LLM Chain node calls the model once and returns the result - predictable and cheap. The Agent node loops, choosing and calling tools based on intermediate results until it finishes or hits Max Iterations. Use the chain for single-shot tasks like classification or rewriting; use the agent when the model must decide which actions to take.
Which agent type should I use in n8n?
The Tools Agent. It uses the model's native tool-calling and is the current default, replacing older types like Conversational, ReAct, and OpenAI Functions for most use cases. Only deviate for a specific reason, such as a SQL-only task or a model without native tool-calling support.
What is the default Max Iterations and what happens when it's hit?
The default is 10. When the agent reaches the cap it stops and returns "Agent stopped due to max iterations." Note that with the node's error setting on "Continue (using error output)," a max-iterations stop can route to the success output rather than the error output, so test your error branch rather than assuming.
Why isn't my agent using the tools I connected?
Three usual causes: the chat model does not support tool-calling (use a recent tool-capable model), the tool descriptions are too vague for the model to know when to call them (write precise, action-oriented descriptions), or the system message does not tell the agent when each tool applies. Turn on Return Intermediate Steps to see what the agent is actually deciding.
Do I need to add a Memory sub-node?
Only if the agent should remember across turns or executions. For one-shot tasks (process a row, answer a single webhook), skip it. For chatbots, add chat memory - Simple Memory for a single-instance prototype, Postgres or Redis for anything persistent or multi-worker. Set the session key per user or chat, not globally.
How do I get clean JSON out of the agent for the next node?
Turn on Require Specific Output Format and connect a Structured Output Parser sub-node with your schema. For inputs where the model occasionally returns malformed output, use the auto-fixing parser, which re-prompts the model to correct the format. Leave the toggle off when you only need a human-readable text reply.
If you are wiring up your first production agent and want a second set of eyes on the system message, tool descriptions, and iteration limits before it goes live, that review is the cheapest insurance you can buy - reach out and we are happy to look.
