How to Build an AI Agent with n8n: A Step-by-Step Guide

To build an AI agent with n8n, connect a trigger (a chat message, webhook or Telegram message) to the AI Agent node, attach a chat model, a memory store and one or more tools, and let the model decide which tool to call for each request. For answers grounded in your own documents, add a vector store such as PGVector that the agent can search. The rest of the work is guardrails, testing and running the workflow on a server that stays online.

The example used throughout: a support agent for a small online shop that answers policy questions from documents, looks up orders in PostgreSQL and logs leads to Google Sheets.

How the AI Agent node is put together

The AI Agent node is a root node with slots for sub-nodes. You don't hand-write a prompt chain; you plug components into it:

• Chat model (required): the LLM that reasons and writes replies, for example an OpenAI or Anthropic model through an API credential, or a local model through Ollama.

• Memory: stores previous turns so the agent remembers what the user said three messages ago.

• Tools: actions the model can choose to call, such as an HTTP request, a database query, a Google Sheets append or another n8n workflow.

• Output parser (optional): forces structured output when other nodes consume the result.

On each request the model reads the system message, history and tool descriptions, then answers or calls tools until it has an answer or reaches the iteration limit.

Step 1: Choose the trigger

The trigger decides how messages arrive and, just as important, what you use as the session ID for memory.

• Chat Trigger ("When chat message received"): a test chat in the editor plus an embeddable website chat, with a session ID supplied automatically.

• Webhook: your own frontend or app sends a POST with the message and a user or conversation ID. Use that ID as the memory key.

• Telegram Trigger: every incoming message carries a chat ID, which works well as the session key.

Whichever you choose, map a stable per-user value to the memory session key. If every user shares one key, they see each other's context.

Step 2: Attach the chat model

Add a chat model sub-node and create a credential with your provider's API key. n8n stores credentials encrypted with the instance's encryption key, so back that key up together with the database. A few practical choices:

• Pick a model that is reliable at tool calling. Smaller, cheaper models are fine for routing and simple lookups; harder reasoning may need a stronger one.

• Set a maximum output token limit and a low-to-moderate temperature for support-style answers.

Step 3: Add memory that survives restarts

The simplest memory option keeps history inside the n8n process. That is fine for testing, but it is lost on every restart. For production, use Postgres Chat Memory, which writes each conversation to a table keyed by session ID. Keep the context window length (how many recent messages are sent back to the model) modest, for example the last 10 to 20 messages; every extra message costs tokens on every call.

If n8n already runs on PostgreSQL, the memory can use the same server, ideally in a separate database or schema.

Step 4: Give the agent tools

Tools are what make an agent useful. For the shop example:

1. Order lookup: a Postgres tool running a parameterised, read-only query that returns status and shipping date for an order number. Connect it with a database user that can only SELECT from the orders table.

2. Lead capture: a Google Sheets tool that appends name, email and question when a visitor asks about bulk pricing.

3. External API: an HTTP Request tool that checks the courier's tracking endpoint.

4. Sub-workflow: for multi-step logic (validate input, call two APIs, format the result), build a separate workflow and expose it to the agent as a tool.

Write each tool's description as if briefing a new colleague: what it does, when to use it and what input it expects. The model picks tools mostly from these descriptions. In recent n8n versions you can also let the model fill specific parameters with the $fromAI() expression instead of mapping them by hand.

Step 5: Add RAG with a PGVector vector store

To answer questions about return policies or product specs without making things up, store your documents as embeddings and let the agent search them. This takes two workflows.

Ingestion workflow (on a schedule or when a file changes): load the documents, split them into chunks with a text splitter, create embeddings with an embeddings sub-node and insert them with the PGVector Vector Store node. Enable the extension once on the database:

CREATE EXTENSION IF NOT EXISTS vector;

Retrieval: in the agent workflow, attach the PGVector Vector Store as a tool, using the same embeddings model you used for ingestion. Mixing embedding models, or changing vector dimensions, makes search results meaningless. Describe it clearly, for example "Search the shop's policy documents for questions about returns, shipping or warranties."

Our guide to RAG with pgvector and PostgreSQL covers chunk sizes, indexes and similarity search in more depth.

Step 6: Guardrails

An agent with tools can loop, overspend or do something you didn't intend. Build limits in from the start:

• System message: state the agent's role, what it may and may not do, the tone, and what to say when it doesn't know. Tell it to search the documents before answering policy questions.

• Max iterations: the agent node has an iteration limit. Keep it low enough that a confused model stops instead of calling tools again and again.

• Least privilege: read-only database users, narrowly scoped API keys, and no tool that deletes data or issues refunds without a human step.

• Cost controls: cap output tokens, keep the memory window short and set a spending limit with your model provider.

• Error handling: attach an error workflow that alerts you when executions fail.

A system message for the shop agent might look like this:

You are the support assistant for an online shop.
- Answer only questions about orders, shipping, returns and products.
- For policy questions, always search the documents tool first.
- For order status, ask for the order number, then use the order lookup tool.
- Never invent prices, dates or policies. If unsure, say so and offer to pass
  the question to a human.
- Keep answers under 120 words.

Step 7: Test before you activate

Use the chat panel in the editor and open each execution to see the agent's tool calls. Test normal questions, edge cases (a wrong order number, an off-topic request) and attempts to make it ignore its instructions. Check that it picks the right tool, refuses what it should, and note the tokens a typical conversation uses.

Step 8: Deploy it properly

An agent connected to a website or messaging app has to be reachable at all times, so it shouldn't live on a laptop. For production:

• Run n8n on PostgreSQL behind HTTPS on its own domain, and use the production webhook URL (not the test URL) once the workflow is active.

• Back up the database and the encryption key. Without the key, stored credentials can't be decrypted.

• Size the server for your load. AI nodes mostly wait on the model API, but large documents and many concurrent chats add RAM and CPU use; see n8n RAM and CPU requirements.

• If many conversations arrive at the same time, move to n8n queue mode with Redis workers so executions are spread across workers.

When to move the agent out of n8n and into code

n8n suits prototypes and agents whose value lies in connecting systems. Consider rewriting the agent in Python or Node.js when:

• You need fine control over the agent loop, streaming responses, or custom retry and fallback logic between models.

• Several agents hand work to each other with shared state that is awkward to express as workflows.

• You want unit tests, code review and versioned deployments for the agent logic itself.

A common middle ground: n8n keeps the triggers and integrations and calls an agent service running in Docker on a separate server through an HTTP Request node. For ideas on what to automate around the agent, see these n8n automation examples for small businesses.

Frequently asked questions

Which memory should an n8n agent use in production?

A persistent store such as Postgres Chat Memory, keyed by a stable user or chat ID. In-process memory is lost whenever n8n restarts.

Can an n8n agent use a local model instead of an API?

Yes, through the Ollama chat model sub-node, but it needs enough hardware to answer quickly, and small models are usually weaker at tool calling. Most production agents call a model API.

Why does my agent ignore its tools?

Usually the tool description is vague, the system message doesn't say when to use the tool, or the model is weak at tool calling. Rewrite the descriptions first, then try a stronger model.

Running your n8n agent on IM HOST

IM HOST n8n Hosting gives you your own n8n on a dedicated NVMe KVM server, installed with PostgreSQL, HTTPS and free SSL on your domain, with free daily backups and queue mode with Redis workers on Pro plans and above. When an agent grows into its own codebase, AI Agent Hosting provides always-on servers with Docker, Node.js, Python and PostgreSQL with pgvector pre-installed.