n8n AI Agent Tutorial: Build Your First Agent Without Code

An n8n AI agent is a workflow built around the AI Agent node. You give it a goal (the user's message), a model, and a set of tools. The model reads the request, decides whether it needs a tool, calls it, reads the result, and repeats until it can answer. That repeat-until-done cycle is the agent loop.

The AI Agent node is a cluster node: a root node with sub-nodes plugged in underneath. It has four slots:

• Chat Model (required): the LLM. n8n supports OpenAI, Anthropic, Google Gemini, Mistral, Groq, Ollama and more.
• Memory (optional): stores recent messages per session. Simple Memory keeps them inside n8n; Postgres, Redis and MongoDB chat memory nodes persist them in a database.
• Tool (at least one required): any action the model may take. Most app nodes (Gmail, Google Sheets, Slack, Notion, Postgres) work as tools, plus tool nodes like HTTP Request, Call n8n Workflow Tool and MCP Client Tool.
• Output Parser (optional): turn on Require Specific Output Format to force structured output.

One loop, step by step. A user asks "Am I free Thursday at 3pm? If so, book a call with Dana." The model gets the message, system message and tool list, and replies with a tool call (Google Calendar: get Thursday's events). n8n runs it and returns the result. The model then calls create event, gets the confirmation, and writes the answer. Max Iterations (default 10) caps how many rounds this can take before the agent stops.

Agent vs plain LLM chain. n8n also has a Basic LLM Chain node. A chain is one model call: no tools, no memory. Use it for fixed steps like "summarize this email." Use an agent only when the model has to decide what to do next. Chains are cheaper and more predictable.

Since n8n 1.82.0 every AI Agent node works as a Tools Agent. Tutorials that have you pick "Conversational Agent" or "ReAct Agent" are out of date.

n8n Cloud is the fastest start. A new trial gives you 14 days of Pro features with 1,000 executions, no credit card required. After that, the pricing page lists (in euros where we checked; your region may show another currency):

• Starter: €20/month billed annually (€24 monthly) for 2,500 workflow executions, 5 concurrent executions, and 1,600 Assistant credits a month.
• Pro: €50/month billed annually (€60 monthly) for 10,000 executions, with higher tiers above that.
• Business (self-hosted only) and Enterprise cost more and add SSO, environments and Git version control.

All plans include unlimited workflows and users, and "Agents, MCP and AI nodes" are included from Starter. n8n bills per execution (one full run of a workflow, however many steps it has), not per step.

Self-hosted Community edition is free with almost the full feature set, but n8n recommends self-hosting only if you're comfortable managing servers, security and updates. Public chats, webhooks and OAuth logins also need a publicly reachable URL.

The quickest setup in the current docs is the one-line installer (Docker Compose v2, plus the sandbox services n8n Assistant needs). Plain docker run still works. Skip npx n8n for anything lasting: npm installs are deprecated from n8n 3.0 and don't get n8n Assistant. Then open http://localhost:5678.

We'll build a team assistant: a chat agent that checks your calendar, looks up customers in a Google Sheet, and files support tickets through an API. One tool takes a real action, so you'll add a safety check too.

1. Create a new workflow. Add the Chat Trigger node (search "chat"). Leave Make Chat Publicly Available off while you build; you'll test from the editor's chat panel.
2. Click + after the trigger and add the AI Agent node. Leave Prompt on Take from previous node automatically: it reads the chatInput field the Chat Trigger sends.
3. In the Chat Model slot, add OpenAI Chat Model or Anthropic Chat Model with your API key, or on n8n Cloud select Use Gateway credits. A current mid-size model is usually enough for tool routing.
4. Click the Memory slot and add Simple Memory. Set Context Window Length to about 10 interactions. Keep the default session key, which the Chat Trigger provides per conversation.

Warning from the docs: Simple Memory doesn't work in queue mode. Self-hosting at scale? Use Postgres or Redis Chat Memory.

Open the AI Agent node, go to Options, add System Message, switch the field to Expression, and paste something like this. It tells the agent its job, which tool to use for what, and what it must never do on its own. The {{ $now }} expression gives the model today's date, which it otherwise doesn't know.

Three rules that matter more than clever wording:

• Name every tool and say when to use it. The model picks tools by name and description, so the system message and the tool descriptions should agree.
• Say what to do when a tool fails or returns nothing. Otherwise the model will guess, and guesses sound confident.
• Keep it short. The system message is sent on every loop iteration, so a long one costs tokens on every step.

Add three tools through the Tool slot. Write each description for the model, not for yourself.

Tool 1: Google Calendar (check_calendar). Add the Google Calendar node as a tool, connect your Google account, and choose the operation that gets many events. On the time range fields, click "Let the model define this parameter" so the agent fills them in. Description:

Get events from the team calendar between two dates. Use this to check availability or list meetings. Input: start and end date-times in ISO 8601.

Tool 2: Call n8n Workflow Tool (lookup_customer). Build a second workflow that is triggered by another workflow, reads your customers sheet with Google Sheets, and returns the matching row. In the main workflow, add Call n8n Workflow Tool, pick it under Source: Database, and let the model fill the email input. Description:

Look up a customer by email address. Returns name, plan, and account ID, or nothing if the customer doesn't exist.

Sub-workflows are the most underrated trick here: the agent sees one simple tool, while the sub-workflow runs ten deterministic steps behind it. Gotcha: in production the sub-workflow must be published, or the call fails with "Workflow is not active and cannot be executed", an error that's easy to miss in the agent's reply.

Tool 3: HTTP Request (create_ticket). Use the HTTP Request tool for any API without its own node. Method POST, URL your helpdesk's ticket endpoint (or a webhook.site test URL while you build), API key in a credential, and a JSON body in Expression mode. Each $fromAI() marks a value the model supplies (key, description, type). Description:

Create a support ticket. Only call this after lookup_customer has returned an account ID and the user confirmed the summary.

Gate the risky tool. In the AI Agent's Tools panel, add a Human review step (approval via n8n chat, Slack, Telegram and others) and connect create_ticket to it. The workflow pauses until someone approves or denies, and a denial is reported back to the agent.

Open the chat panel at the bottom of the canvas and try prompts that should hit each tool:

1. "What's on the calendar next Tuesday?" (check_calendar)
2. "Find the customer dana@example.com." (lookup_customer)
3. "Dana's exports have been failing since Monday, file a high-priority ticket." (lookup_customer, then create_ticket after confirmation and approval)
4. "What did I just ask you to do?" (memory)

After each run, open the execution logs to see which tool it called, with what input, and what came back. Most bugs are a vague tool description (wrong tool picked), a badly filled parameter (tighten the $fromAI() description), or a tool that failed quietly (check the sub-workflow's executions).

When it works, publish the workflow. To share it, turn on Make Chat Publicly Available in the Chat Trigger, choose Hosted Chat (n8n's chat page) or Embedded Chat (your own UI or n8n's chat widget), and set authentication: none, basic auth, or n8n user login. For anything internal, don't leave it on none.

n8n supports the Model Context Protocol in both directions:

• MCP Client Tool (a tool sub-node): plug any MCP server into your AI Agent. Set the endpoint URL and authentication (bearer, header, or OAuth2), then choose Tools to Include: all, selected, or all except. For popular services like Notion or Linear, the tools panel has an MCP servers registry: pick one, sign in, and n8n creates the credential. A plain MCP Client node also calls one MCP tool as a normal workflow step.
• MCP Server Trigger (a trigger node): turn a workflow into an MCP server. Attach tool nodes or Call n8n Workflow Tools to it, and n8n exposes them at a test URL and a production URL (live once you publish). It supports SSE and streamable HTTP, not stdio.
• Instance-level MCP: n8n also has a built-in MCP server for the whole instance, so Claude, ChatGPT or a coding agent can search, build, edit and run your workflows.

n8n's own advice: an app node as a tool gives tighter control (you fix the operation and pin parameters); an MCP server gives many actions from one connection, at the cost of control and more context per call. For a first agent, prefer app nodes.

To use an MCP Server Trigger from Claude Desktop, which speaks stdio, the n8n docs use the mcp-remote bridge. Replace the URL and token with values from your trigger node. Want to build an MCP server in code instead? See our Python MCP server tutorial.

"n8n AI agent builder" can mean two newer features. Neither replaces understanding the nodes above.

Agent Builder (Preview). A separate place in n8n to build agents without a canvas. You give an agent a model, instructions, and capabilities: tools (n8n integrations, your workflows, custom tools, MCP servers), web search, skills, a knowledge base (csv, pdf, markdown, txt), memory, and sub-agents. Agents can run on a schedule, connect to Slack, Telegram, Linear and Microsoft Teams, and require approval before sensitive tools run. It's on all n8n Cloud plans and on self-hosted n8n from 2.32.3. Each agent turn counts as one execution, from the same quota as your workflows. Workflows can call these agents with the Message an Agent node.

n8n Assistant (Preview). A chat-based builder: describe what you want, and it plans the workflow, builds it, tests it, and helps fix errors. It can also draft agents (instructions, tools and skills). The result is a normal workflow you can open and edit. It's on Cloud Starter and Pro (1,600 Assistant credits a month on Starter, 4,000 or 9,600 on Pro depending on tier; Enterprise on request), and on self-hosted Community, Registered Community and Business editions with your own model API key. Older tutorials call the prompt-to-workflow feature AI Workflow Builder; the current docs and pricing page call it n8n Assistant.

Our take: let the Assistant draft version one, then read every node it created. You'll debug much faster.

Four agents that are genuinely useful and small enough to finish in an afternoon:

1. Inbox triage agent. Trigger: new Gmail message. The agent classifies it, drafts a reply with the Gmail tool (as a draft, not sent), and posts urgent ones to Slack. Use a Text Classifier node for the sorting and the agent only for drafting.
2. Meeting scheduler in Telegram. Telegram Trigger, AI Agent, Google Calendar tools (get events, create event), Simple Memory. You text "find 30 minutes with Sam next week" and it proposes slots. Put Human review on event creation.
3. Docs Q&A agent. Load your help docs into a vector store (Simple, Pinecone, Qdrant, Supabase and others), attach it as a Vector Store Question Answer Tool, and serve it through the Chat Trigger's hosted chat. Tell it to say "I don't know" when retrieval comes back empty.
4. Lead research agent. Trigger: new row in a Google Sheet. The agent uses an HTTP Request tool to fetch the company website or a search API, writes a three-line summary and a fit score back to the sheet. Add an output parser so the score is always a number.

Before starting from scratch, search n8n's template library for AI Agent workflows to import and adapt.

What it costs. Two bills: n8n executions (each chat message or trigger run counts once, however many tool calls happen inside) and model tokens (each loop iteration resends the system message, memory and tool results). 2,000 messages a month fits Starter's 2,500 executions; a busy team chat won't. Concurrency is capped too (5 on Starter), so heavy traffic queues.

Limits you'll hit:

• Execution time. Cloud caps a single execution at 5 minutes on Starter and 40 minutes on Pro. Long research loops can hit that.
• Testing. Agents are non-deterministic, so "it worked once" isn't a test. n8n has evaluations (light evaluations on every Cloud plan; metric-based ones on one workflow on Starter, unlimited on Pro), but you build the test set yourself.
• Version control and review. Workflows are JSON. Git-based version control and environments need Business or Enterprise.
• Complex logic. Multi-agent branching, custom retries and typed data contracts get awkward on a canvas.

When to move to code. Stay in n8n while your agent is mostly glue: one model, a handful of tools, and lots of integrations n8n already has. Move to a code framework when you need unit tests in CI, typed structured outputs you can rely on, multi-agent orchestration, or an agent embedded in your own product. Our AI agent frameworks comparison covers the options, and our free PydanticAI course teaches you to build the same kind of tool-using agent in Python, step by step. Many teams use both: n8n for integrations, a coded agent behind an HTTP endpoint for the hard part.

1. Build the agent above with one tool first (Google Calendar), then add the other two one at a time.
2. Take n8n's free Quickstart for a guided version with a certificate, then N8N103 In Practice for testing and error handling.
3. Read the docs that matter most: the AI Agent node, Tools Agent options, and Human-in-the-loop for tools.
4. Compare learning paths in our best vibe coding courses guide if you also want to build apps, not just automations.
5. Ready for code? Start the free PydanticAI course.