You have an LLM API key and a list of things you want automated. The gap between the two is tooling: wiring the model to your database, your Slack channel, your internal API, with retries, logging, and a way to see what the model actually did. Hand-written LangChain glue works until you are maintaining five automations instead of one. Managed platforms charge per task and sit between you and your data. n8n sits in the middle: a self-hosted workflow automation platform with native AI agent nodes.
n8n has existed since 2019 and is one of the most-starred automation projects on GitHub, with around 200,000 stars. It is distributed under the Sustainable Use License, which the project describes as fair-code: the source is public and self-hosting is free, but it is not an OSI-approved open source license. Good to know before you build on it.
By the end of this tutorial you will have an agent that answers questions by calling a real API, decides on its own when to call it, and remembers the conversation. Everything runs on your machine. No cloud account, no per-task billing.
Prerequisites
- Docker Engine 24+ (check with
docker version) - About 2 GB of free RAM
- An API key for OpenAI, Anthropic, or another provider n8n supports. Using Ollama? Then no key at all.
- 20 minutes
Step 1: Install n8n with Docker
The official quickstart is a volume plus one docker run:
docker volume create n8n_data
docker run -it --rm \
--name n8n \
-p 5678:5678 \
-e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
-e N8N_RUNNERS_ENABLED=true \
-v n8n_data:/home/node/.n8n \
docker.n8n.io/n8nio/n8n
Open http://localhost:5678 and create your owner account. Workflows, credentials, and execution history live in the n8n_data volume, mapped to /home/node/.n8n inside the container.
Two flags in that command come from the official docs and are worth keeping. N8N_RUNNERS_ENABLED=true moves code execution into separate task runner processes. N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true tightens permissions on the settings file. Both are safe defaults.
Updates are boring, which is good:
docker compose pull
docker compose down
docker compose up -d
The docs assume a docker-compose.yml. If you want to start with one, the official n8n-hosting repo has ready-made compose files, including a variant that pairs n8n with Postgres. SQLite is fine for a single user. Postgres starts paying off when a team shares one instance.
Step 2: Create a credential
Left sidebar, Credentials, Add credential. Pick your model provider and paste the API key. n8n ships chat model nodes for OpenAI, Anthropic, Google Gemini, Groq, DeepSeek, Mistral, OpenRouter, xAI Grok, and AWS Bedrock, among others. There is also an Ollama node if you want the whole stack on your own hardware.
Step 3: Build an agent that calls an API
Three nodes: Manual Trigger, then an AI Agent node with an Anthropic Chat Model and an HTTP Request tool attached.
The AI Agent node is where the loop runs. The docs put it plainly: connect a chat model and one or more tools, and the agent decides which tools to call to complete a task. You do not write that loop. The node calls the model, checks whether the model asked for a tool, runs the tool, and feeds the result back, repeating until the model produces a final answer. It also refuses to run with zero tools connected, which is a useful nudge.
Set the HTTP Request tool to GET https://api.github.com/repos/n8n-io/n8n. Public GitHub repos need no token, which makes this the cheapest possible test: the agent can check stars, forks, open issues, and recent activity for any repo.
Give the tool a description that says what it does and what the data looks like, for example: "Fetches public metadata for a GitHub repository, including stargazers_count, forks_count, and open_issues_count." The model reads that description when deciding whether to call the tool. This is the most important text in the whole workflow.
One tool-only option is worth turning on: Optimize Response, then JSON, then Include fields with stargazers_count, description, forks_count, open_issues_count, pushed_at. The GitHub API returns a large JSON document. Filtering it before it goes back to the model cuts tokens on every call, which cuts cost, and keeps the model from getting distracted by fields it does not need.
Execute the workflow and ask something like "How many stars does n8n have?" Watch the run: the agent calls the API, gets the filtered JSON, and answers with a real number. Then ask a follow-up the tool cannot answer, like "What does the repo description say?" Different question, same flow.
Version note: if you open an old template that mentions agent types like ReAct or Plan and Execute, those options were removed in version 1.82.0. Every AI Agent node now behaves as a Tools Agent.
Step 4: Give the agent memory
Out of the box the agent is stateless. Each run starts with an empty conversation. For a chat-style agent, add the Simple Memory sub-node so the model keeps recent messages in context. If conversation history needs to survive restarts, n8n has Postgres, Redis, and MongoDB chat memory nodes.
Step 5: Beyond the demo
The same pattern scales in a few directions.
Replace the Manual Trigger with a Webhook trigger and add a Respond to Webhook node, and the agent becomes an HTTP endpoint you can call from anywhere. This is how most people put agents in front of real users.
The Call n8n Workflow Tool lets an agent run another workflow and use its output. That is a clean way to draw a permission boundary: the sub-workflow checks auth, validates input, or writes to a system, while the agent only sees the result.
The MCP Client Tool connects the agent to any MCP server, so tooling you already have from other agent projects can be reused.
For retrieval, vector store nodes exist for PGVector, Chroma, Qdrant, Pinecone, and others, so a RAG setup inside n8n does not require leaving the platform.
When to use vs alternatives
- n8n vs Zapier/Make: n8n is self-hosted, so data and execution history stay on infrastructure you control, and the price is your server bill instead of per-task fees. Zapier and Make win on breadth of consumer app integrations and zero-maintenance hosting.
- n8n vs writing LangChain code: code gives you full control, unit tests, and no UI tax. n8n gives you a visual canvas, built-in retries, per-run logs, and a cheaper way to hand automations to non-engineers. My rule of thumb: if the thing is a pipeline with branches, use n8n. If it is an algorithm with unusual control flow, write the code.
- n8n vs Dify/Flowise: Dify is an LLM app platform, strongest when the product is a RAG chatbot. Flowise is an agent builder. n8n is a general automation platform where AI is one node type among 400+ integrations. If your agent also has to send invoices and sync CRM records, n8n wins by being the same tool for both jobs.
Verdict
The trade-off is simple. You trade a little control and a non-open-source license for the fastest path to an agent doing real work, with free observability on top. For internal tools, prototypes, and automations that touch many systems, that trade usually works out. If you need a fully open-source stack or unusual control flow, write the code.
Next steps
- Put the workflow behind a Webhook trigger and call it from a test script.
- Swap the GitHub tool for one of your own APIs and write a description that matches your data.
- Read the AI Agent docs page to learn about common issues and vector store options.