The n8n AI Agent node turns a language model into an autonomous workflow participant. Instead of a single prompt → response, the Agent can use tools, loop through reasoning steps, consult memory, and produce a structured result — all without you writing orchestration code.
This guide covers every configuration option, the gotchas that trip people up, three production-ready patterns, and a free workflow JSON.
What the AI Agent node does
The AI Agent node implements a ReAct-style loop:
- Reason — the model reads the task and decides which tool to use
- Act — it calls that tool (an n8n sub-workflow, HTTP Request, calculator, code, etc.)
- Observe — the tool result feeds back in
- Repeat — until the model decides it has enough to answer
The loop runs inside n8n with full observability — every step appears in the execution log.
Agent types
| Agent type | When to use |
|---|---|
| Tools Agent | General purpose. Model picks tools from a list you provide. Best default choice. |
| Conversational Agent | Maintains a multi-turn chat history. Use for chatbots and support flows. |
| ReAct Agent | Explicit reasoning + acting steps. Use when you want the scratchpad visible. |
| SQL Agent | Specialised for querying a connected database. Generates and runs SQL. |
| Plan and Execute Agent | Breaks big tasks into a plan, then executes each step. Use for complex multi-step tasks. |
For most automation work, start with Tools Agent.
Connecting a model
The AI Agent node requires a Chat Model sub-node. Supported providers include:
- OpenAI Chat Model (
gpt-4o,gpt-4o-mini) - Anthropic Chat Model (
claude-opus-4,claude-sonnet-4-6) - Google Gemini Chat Model
- Ollama Chat Model (self-hosted)
- OpenRouter Chat Model (any model via OpenRouter API)
Connect the Chat Model node to the Model input of the AI Agent node. Each Chat Model node has its own credential and model selector.
Gotcha — model capability: ReAct and tool-use agents work best with models that support function calling natively (GPT-4o, Claude 3+, Gemini 1.5+). Older or smaller models may hallucinate tool calls or loop indefinitely.
Tools
Tools are what give the Agent its power. Attach them to the Tools input:
| Built-in tool | What it does |
|---|---|
| Calculator | Arithmetic — prevents the model from hallucinating math |
| Code Tool | Run arbitrary JavaScript or Python in the workflow |
| HTTP Request Tool | Call any external API |
| Think Tool | A reasoning scratch-pad — model "thinks out loud" before acting |
| Wikipedia | Look up factual information |
| Wolfram Alpha | Computation and data lookup |
| SerpApi / Google Search | Real-time web search |
| n8n Workflow Tool | Call another n8n workflow as a tool — this is the big one |
The n8n Workflow Tool lets you wrap any existing n8n workflow as a callable tool. The Agent describes what it needs in natural language, the tool executes the workflow, and the result comes back into the Agent's reasoning loop. This means your Agent can send emails, query databases, create Notion pages, or call Stripe — anything you can do in n8n.
Memory
Memory lets the Agent retain context across calls. Connect a memory node to the Memory input:
| Memory type | Storage | Use case |
|---|---|---|
| Window Buffer Memory | In-process (RAM) | Single session, no persistence |
| Postgres Chat Memory | Postgres DB | Persistent, multi-session chat history |
| Redis Chat Memory | Redis | High-throughput, TTL-based sessions |
| Zep Memory | Zep server | Semantic search over conversation history |
For simple single-run workflows, omit memory. For chatbots or workflows that need to remember previous runs, wire in Postgres or Redis memory.
Core configuration
| Field | Notes |
|---|---|
| System Message | The Agent's standing instructions — role, constraints, output format, tool guidance |
| Human Message | The task input — usually an expression referencing upstream node data |
| Return Intermediate Steps | Toggle on to see the full reasoning chain in the output (useful for debugging) |
| Max Iterations | Hard cap on the reasoning loop. Default 10; lower it for cost control |
| Output Parser | Force structured JSON output (useful when downstream nodes expect specific fields) |
Gotchas & common errors
1. Infinite loops
If the model can't satisfy the task with available tools, it loops until hitting Max Iterations. Set Max Iterations to a low value (5–8) during development. Add a Think Tool so the model can reason explicitly about whether it's stuck.
2. Tool description quality determines performance
The Agent picks tools based on their descriptions. Write tool descriptions like you're writing docs for a colleague:
- Bad:
"Database tool" - Good:
"Query the customer Postgres database. Input: SQL SELECT statement. Output: array of row objects. Use this to look up customer records, orders, or subscription status."
3. Credential access
The Agent runs tools using whatever credentials those nodes have. Make sure each sub-workflow and tool node has credentials wired — the Agent itself doesn't have credentials, its tools do.
4. Cost runaway
Each tool call burns tokens. A complex task with 5 iterations on GPT-4o can cost $0.10+. Use gpt-4o-mini or claude-haiku for tasks that don't need maximum capability. Monitor token usage via the OpenAI/Anthropic dashboard, not n8n's execution log.
5. Return Intermediate Steps output shape
When Return Intermediate Steps is on, the output includes an intermediateSteps array. If downstream nodes expect a flat output field, you may need a Code node to normalize:
return [{ json: { result: $input.first().json.output } }];
6. Structured output vs free text
By default the Agent returns a output string. If you need JSON, add an Output Parser (Structured Output Parser or Auto-Fixing Output Parser) and define a Zod schema. This prevents parsing errors in downstream nodes.
3 workflow patterns
Pattern 1: Customer support triage agent
Webhook (incoming support ticket)
→ AI Agent (Tools Agent, GPT-4o-mini)
System: "You are a support triage agent. Classify the issue, check if it's a known problem, and draft a response. Use the CRM tool to look up the customer. Use the knowledge base tool to find relevant docs."
Tools:
- n8n Workflow Tool: "Look up customer by email in CRM" → calls CRM workflow
- n8n Workflow Tool: "Search knowledge base for docs" → calls Notion search workflow
- HTTP Request Tool: call internal status page API
→ Switch node (route on Agent output classification: billing | technical | general)
→ Branch: assign to correct Zendesk queue + send draft response
Use case: Auto-triage and pre-draft 80% of tickets before a human agent sees them.
Pattern 2: Research and summarise agent
Schedule Trigger (every morning 07:00)
→ HTTP Request (fetch today's Hacker News top 20 via API)
→ AI Agent (Tools Agent)
System: "You are a tech news analyst. For each story, search for more context and summarise it in 2 sentences. Focus on items relevant to AI, automation, and developer tools."
Tools:
- SerpApi Tool (web search for context)
- Calculator (for any stats/numbers)
Human Message: "Summarise these stories: {{ $json.stories }}"
→ Gmail / Slack / Telegram node (send digest)
Use case: Daily personalised news digest without reading 20 tabs.
Pattern 3: Data enrichment agent
Webhook (new lead from form)
→ AI Agent (Tools Agent, gpt-4o-mini)
System: "Enrich the lead. Find the company's website, LinkedIn page, and estimated employee count. Look up the person on LinkedIn. Assess fit for our ICP (B2B SaaS, 10-500 employees). Return a JSON object with: company_website, linkedin_url, employee_estimate, icp_fit (high/medium/low), fit_reason."
Tools:
- SerpApi Tool (search for company + person)
- HTTP Request Tool (fetch company website metadata)
Output Parser: Structured JSON
→ Airtable / HubSpot node (update lead record with enrichment data)
→ IF node: icp_fit = high → notify sales channel on Slack
Use case: Automated lead enrichment and ICP scoring at the top of the funnel.
Free workflow JSON
Here's a starter research-and-summarise agent:
{
"name": "AI Research Agent Starter",
"nodes": [
{
"parameters": {
"rule": { "interval": [{ "field": "hours", "hoursInterval": 24 }] }
},
"name": "Schedule Trigger",
"type": "n8n-nodes-base.scheduleTrigger",
"position": [240, 300]
},
{
"parameters": {
"url": "https://hacker-news.firebaseio.com/v0/topstories.json",
"options": {}
},
"name": "Fetch HN Stories",
"type": "n8n-nodes-base.httpRequest",
"position": [460, 300]
},
{
"parameters": {
"agentType": "toolsAgent",
"systemMessage": "You are a tech news analyst. Summarise the top 5 Hacker News story IDs provided. For each one, fetch the item from https://hacker-news.firebaseio.com/v0/item/{id}.json and write a 2-sentence summary. Return a Markdown list.",
"humanMessage": "Top story IDs: {{ $json.data.slice(0,5).join(', ') }}",
"maxIterations": 10,
"options": {}
},
"name": "Research Agent",
"type": "@n8n/n8n-nodes-langchain.agent",
"position": [680, 300]
},
{
"parameters": {
"url": "={{ $json.url }}",
"options": {}
},
"name": "HTTP Request Tool",
"type": "@n8n/n8n-nodes-langchain.toolHttpRequest",
"position": [680, 480]
}
],
"connections": {
"Schedule Trigger": { "main": [[{ "node": "Fetch HN Stories", "type": "main", "index": 0 }]] },
"Fetch HN Stories": { "main": [[{ "node": "Research Agent", "type": "main", "index": 0 }]] },
"HTTP Request Tool": { "ai_tool": [[{ "node": "Research Agent", "type": "ai_tool", "index": 0 }]] }
}
}
Import via Settings → Import from URL/Clipboard. Wire a Chat Model node (OpenAI or Anthropic) to the Model input before activating.
Next steps
- Add the n8n OpenAI node for direct completions when you don't need tool use
- Use the n8n Webhook node to trigger agents from external events
- Pair with n8n Telegram node for a conversational agent interface over chat
- Browse the full n8n Workflow Starter Pack for pre-built automation patterns
What are you building with the n8n AI Agent node? Drop your use case in the comments.
Top comments (1)
Are you using the AI Agent node for support triage, research digests, or lead enrichment? Which agent type (Tools, ReAct, Conversational) are you running — and what tools or memory nodes have you wired in? Drop your setup in the comments.