Resources · n8n integration

n8n AI Agent Tool nodeConfigure AI Agent Tool in n8n.

An agent that another agent can call. The n8n AI Agent Tool node generates an action plan and executes it, using external tools of its own. It exposes 12 parameters and 4 input ports, and plugs into a parent agent as a tool. For builders splitting one big prompt into specialists.

Try the AI Agent Tool node on n8nSee the 12 parameters

Verified Trustpilot reviews · AI, automation & growth agency

Why automate

What does the n8n AI Agent Tool node actually do?

The AI Agent Tool node is an agent packaged as a tool. It takes a prompt, generates an action plan and executes it, and it can call external tools while doing so. Instead of sitting at the root of a workflow, it hangs off the ai_tool port of a parent node, so a bigger agent can delegate a job to it and read the answer back.

A sub-node is a node that never runs on its own: it waits to be called through a port on a root node. That is exactly what this one is. The root nodes that accept it are AI Agent and MCP Server Trigger, and the whole point is separation of duties. One specialist rewrites text, another looks things up, and the parent decides which to call.

First scenario, a research assistant that stops guessing. The parent agent handles the conversation and holds the history. A child AI Agent Tool gets a tight Description like "answers questions about current pricing pages", its own System Message, and a couple of lookup tools on its ai_tool port. Because the parent reads the description before choosing, a sharp description does more for reliability than a longer prompt ever will. Pair it with a research-flavored source like Perplexity on the parent side and the split gets obvious fast.

Second scenario, a support triage chain. The child agent receives a ticket body through Prompt (User Message) as {{ $json.body }}, classifies it, and returns a clean verdict because Require Specific Output Format is on and a parser is wired to the ai_outputParser port. The parent then routes the result to Slack or writes a row to Google Sheets. Structured output is what makes the hand-off survive.

Third scenario, a batch job that respects a rate limit. A list of 150 records arrives, the child agent enriches each one, and Batch Processing caps how many run in parallel with a pause between groups. Without it, a large run hammers the model provider and starts failing halfway through.

When to prefer the alternative: if nothing is being delegated, use the root AI Agent node directly and skip the extra hop. This node earns its place only when a parent agent picks it out of several tools at runtime. Known limits worth knowing before building: it has nothing to authenticate itself, the credential lives on the chat model sub-node, so an OpenAI key or another provider key is still required somewhere. The page describes version 3 of the node, and an older workflow can show fewer options. And nesting agents multiplies model calls, which the provider bills on its own terms.

Connections

What do you plug into it?

n8n splits AI work between a root node and sub-nodes: the root receives the workflow items, and each sub-node attaches to one port, one type per port.

Ports (what plugs in)

  • Chat Modelai_languageModelrequired
  • Memoryai_memoryoptional
  • Toolai_tooloptional
  • Output Parserai_outputParseroptional

Output (what it plugs into)

  • Toolai_tool
01Chat ModelThis port carries the language model that does the reasoning. Leave it empty and the node cannot run at all.

This port carries the language model that does the reasoning. Leave it empty and the node cannot run at all.

Key parameters

  • Required: the agent has no model of its own, so the sub-node here decides what it can do and who bills the calls.
  • OpenAI Chat Model: the usual starting point, one credential and a model picker.
  • Anthropic Chat Model: same wiring, different provider account.
  • Ollama Chat Model: for a model running on your own machine or server.
Use cases
a self-hosted instance that must keep ticket text in-house wires Ollama Chat Model here instead of a hosted provider.
02MemoryMemory keeps earlier turns of a conversation available to the agent, so a follow-up question does not start from nothing.

Memory keeps earlier turns of a conversation available to the agent, so a follow-up question does not start from nothing.

Key parameters

  • Optional: skip it for one-shot jobs where every call is independent.
  • Simple Memory: stored by n8n, fine for a prototype or a short chat.
  • Postgres Chat Memory: survives restarts, the sane choice once the agent goes live.
  • Redis Chat Memory: for conversations that churn fast and stay short-lived.
Use cases
a chatbot that answers "and the second one?" needs this port; a nightly enrichment run does not.
03ToolTools are what turn a text generator into something that acts. Each one attached here becomes an option the agent can choose during its plan.

Tools are what turn a text generator into something that acts. Each one attached here becomes an option the agent can choose during its plan.

Key parameters

  • Optional: an agent with zero tools still answers, it just answers from the model alone.
  • Calculator: arithmetic the model should not be improvising.
  • Think Tool: gives the agent a step to reason before it commits.
  • Vector Store Question Answer Tool: answers from indexed documents rather than memory.
Use cases
a quoting assistant gets Calculator so the totals match the line items instead of being guessed.
04Output ParserAn output parser forces the answer into a shape the rest of the workflow can read, instead of a paragraph someone has to slice apart later.

An output parser forces the answer into a shape the rest of the workflow can read, instead of a paragraph someone has to slice apart later.

Key parameters

  • Optional: only consulted when Require Specific Output Format is switched on.
  • Structured Output Parser: describe the fields you expect and get them back as data.
  • Item List Output Parser: for answers that are naturally a list.
  • Auto-fixing Output Parser: sends a malformed answer back to the model for a second try.
Use cases
a lead scorer returns a score and a reason as fields, so the next node can branch on the number.
Parameters

Which parameter does what?

The AI Agent Tool node has 12 parameters. For each one: the node as you configure it in n8n, what the parameter changes, and our field notes.

01

Description

toolDescription

What you see in n8n

Notes & use cases

This is the text the parent agent reads when it decides whether to call this tool. No other field weighs as much on how the whole setup behaves.

Key parameters

  • Description: required text. n8n's own guidance is blunt about it, a good specific description lets the model produce the expected result far more often.
Use cases
"looks up the delivery status of an order from its reference" gets picked correctly; "helps with orders" gets called for everything, including questions it cannot answer.
02

Prompt (User Message)

text

What you see in n8n

Notes & use cases

Whatever goes here is the request the agent works on. It is the equivalent of the message a person would type.

Key parameters

  • Prompt (User Message): required text, with a placeholder that shows the tone expected, e.g. Hello, how can you help me?. Point it at incoming data with an expression such as {{ $json.question }}, the n8n syntax for reading a field off the current item.
Use cases
a form submission lands in the workflow and its message field feeds the prompt directly, no copy step in between.
03

Require Specific Output Format

hasOutputParser

What you see in n8n

Notes & use cases

Switch this on when free text is not good enough and the answer has to come back as fields.

Key parameters

  • Require Specific Output Format: a boolean. Turning it on is what makes the node pay attention to whatever sits on its ai_outputParser port.
Use cases
an agent that classifies inbound email returns a category and a confidence, and the following node branches on them. The trap: switching this on without attaching a parser gives the agent a rule and no shape to follow.
04

Enable Fallback Model

needsFallback

What you see in n8n

Notes & use cases

A second model, standing by for the moment the first one refuses to answer or stops responding.

Key parameters

  • Enable Fallback Model: a boolean that adds a second chat model slot to fill.
Use cases
an agent embedded in a customer-facing chat keeps answering when its main provider has a bad hour. Worth remembering that the backup is a different account being called, so the fallback provider bills those attempts under its own terms.
05

System Message

options.systemMessage

What you see in n8n

Notes & use cases

Instructions handed to the agent before the conversation starts, setting its role, its tone and what it must refuse.

Key parameters

  • System Message: text sent to the agent ahead of everything else.
Use cases
a triage agent is told to answer in the language of the ticket and to escalate anything mentioning a refund. Keep it separate from Description: one steers the agent's behavior, the other tells the parent when to call it.
06

Max Iterations

options.maxIterations

What you see in n8n

Notes & use cases

An agent loops: it thinks, calls a tool, reads the result, thinks again. This caps how many times that loop runs before it stops.

Key parameters

  • Max Iterations: a number, the maximum the agent runs before stopping.
Use cases
a research agent with several tools attached can chase its own tail, and each extra lap is another paid model call. Lowering this is the fastest way to stop a runaway loop from quietly draining a provider account.
07

Return Intermediate Steps

options.returnIntermediateSteps

What you see in n8n

Notes & use cases

Normally the node hands back only the final answer. Flip this and the output also carries the steps taken to get there.

Key parameters

  • Return Intermediate Steps: a boolean deciding whether the output includes the intermediate steps the agent took.
Use cases
debugging an agent that calls the wrong tool, where seeing which tool it reached for and what came back is the whole diagnosis. Leave it off in production, the payload gets noticeably heavier.
08

Automatically Passthrough Binary Images

options.passthroughBinaryImages

What you see in n8n

Notes & use cases

Images travelling through the workflow as binary data get handed to the agent as image messages rather than being dropped.

Key parameters

  • Automatically Passthrough Binary Images: a boolean controlling whether binary images pass through to the agent as image type messages.
Use cases
a screenshot arrives with a support request and the agent needs to look at it, not at a filename. Only useful when the chat model on the ai_languageModel port actually accepts images.
09

Tracing Metadata

options.tracingMetadata

What you see in n8n

Notes & use cases

Custom key and value pairs stapled to the tracing events the run produces, so a call can be tied back to the customer or campaign behind it.

Key parameters

  • Key: the label under which the value is recorded.
  • Type: what kind of value it is, from stringValue, numberValue, booleanValue, arrayValue or objectValue.
  • Value: the content itself, entered in the field matching the chosen type.
Use cases
tagging every run with a tenant id so traces can be filtered per account later.
10

Auto-save highlighted data

options.autoSaveHighlightedData

What you see in n8n

Notes & use cases

Highlighted data is saved automatically so executions can be filtered on it afterwards in the Executions view.

Key parameters

  • Auto-save highlighted data: a boolean that defaults to true. It is available on Pro and Enterprise plans in n8n Cloud, and on Enterprise or registered Community Edition when self-hosted.
Use cases
finding every execution tied to one order reference without scrolling through a day of runs. On a plan that does not include it, the switch simply has nothing to act on.
11

Enable Streaming

options.enableStreaming

What you see in n8n

Notes & use cases

Rather than waiting for the complete answer, the agent streams its response in real time as the text is generated.

Key parameters

  • Enable Streaming: a boolean deciding whether this agent streams the response as it generates text.
Use cases
a chat surface where words appearing progressively feel far better than a spinner. For an agent called by a parent that only reads the finished result, streaming buys nothing.
12

Batch Processing

options.batching

What you see in n8n

Notes & use cases

Batch processing exists for rate limiting: it controls how many items the node works through at once and how long it waits between groups.

Key parameters

  • Batch Size: how many items run in parallel. Useful for rate limiting, though it can affect the ordering of the log output.
  • Delay Between Batches: a pause in milliseconds between two groups, again for rate limiting.
Use cases
enriching a long import without the provider cutting the run off partway through.
Need help

Need help automating AI Agent Tool with n8n?

A person reads every message.

FAQ

Questions builders ask next

01Is the n8n AI Agent Tool node included in n8n, on Cloud and self-hosted?
Yes. It ships inside n8n's AI package, @n8n/n8n-nodes-langchain, which comes with n8n itself. Nothing to install, no extra cost on the n8n side, and it behaves the same on n8n Cloud, the hosted offer run by n8n, as on an instance you host yourself with Docker or npm under the Community Edition and its Sustainable Use licence. A workflow built in one place runs in the other. The cost that does exist sits elsewhere: the provider behind the chat model you attach bills its own API calls under its own terms, and n8n adds nothing on top. One exception on features, not price: Auto-save highlighted data is available on Pro and Enterprise plans in n8n Cloud, and on Enterprise or registered Community Edition when self-hosted.
02What credentials does the AI Agent Tool node need?
None of its own. The node has no credential and no Authentication selector, so there is nothing to connect on the account side and nothing to rotate. That is genuinely convenient, but it does not mean the setup is credential-free. The chat model sub-node wired to the ai_languageModel port carries the provider credential, and that port is required: leave it empty and the node cannot run. So the key you need is the one belonging to whichever model you attach, whether that is a hosted provider or a local model served through Ollama Chat Model. The same applies to any tool you hang on the ai_tool port, each brings its own credential when it needs one.
03What are the limits of the AI Agent Tool node?
It is not a root node. It runs only when a parent calls it through a tool port, and the root nodes that accept it are AI Agent and MCP Server Trigger. On its own it does nothing at all. It also has no authentication of its own, so everything depends on the sub-nodes attached to its 4 input ports, and an empty Chat Model port stops the run. This page describes version 3 of the node, the highest in the catalogue: an older workflow may show an earlier version with fewer options. Finally, nesting an agent inside an agent multiplies model calls, which is why Max Iterations and Batch Processing matter more here than on a simple chain.
04What is the minimum to attach, and which sub-node should you start with?
A chat model, and nothing else. The ai_languageModel port is the only required one, so a working setup is a model plus a Description and a Prompt (User Message). OpenAI Chat Model is the usual first pick because it is one credential and a dropdown, and Ollama Chat Model is the equivalent when the data has to stay on your own machine. Add Simple Memory next if the agent is holding a conversation, then move to Postgres Chat Memory once it goes live and restarts must not wipe the history. Tools come last: start with one, such as Calculator, and confirm the agent actually reaches for it before adding more.
05n8n or Make for an AI agent setup like this?
It depends on where you want the workflow to run and how you want to pay for it. Make, formerly Integromat, is a hosted platform with no self-hosting option and pricing counted per operation, which suits a team that wants nothing to maintain and has a predictable volume. n8n runs the same workflow on Cloud or on your own server, which is what matters when the prompts and the data going into the model have to stay somewhere specific. The agent model also differs: here the sub-node ports are visible on the canvas, so which model, which memory and which tools an agent uses is something you read rather than infer. Both approaches are defensible, the deciding factors are hosting, data control and how your volume grows.
Hack'celeration Lab

Get our weekly integration tips.

No spam. Unsubscribe anytime.

Same platform

Other docs you might need on this stack.

Browse all integrations