How to Build Your First n8n AI Agent (Step by Step)

Most “beginner” n8n AI agent tutorials have the same annoying problem: they show a neat workflow screenshot, tell you to “connect the model,” and then jump straight to the finished result. Sounds easy. Until you open n8n for the first time and realise you don’t know which plus button to click, what belongs in each field, or why the AI Agent node refuses to run.

This guide fixes that. We’ll build a small but real AI agent that accepts a chat message, decides when a calculation is needed, calls n8n’s Calculator tool, and returns an answer. You’ll see the exact nodes, the connections between them, what to type, how to test the workflow, and what to check when it fails.

Before you start

You need an n8n workspace and access to a supported chat model. If you use n8n Cloud, your workspace may offer n8n-managed model access or trial credits. Otherwise, create a credential for the model provider you want to use. This walkthrough uses the OpenAI Chat Model node because its setup is straightforward, but the workflow structure is the same if you choose another supported chat model.

• n8n: a current n8n Cloud account or self-hosted instance.
• Model access: n8n-managed access where available, or your own OpenAI API credential.
• Time: roughly 15–20 minutes if this is your first workflow.

One small warning before we touch the canvas: an OpenAI ChatGPT subscription and an OpenAI API account are not the same product. If n8n asks you for an API key, a normal ChatGPT Plus login does not automatically provide one.

Step 1: Create a new workflow and add Chat Trigger

1. Sign in to n8n and click Create Workflow or New Workflow.
2. Rename the workflow at the top-left to My First AI Agent.
3. Click Add first step in the centre of the canvas.
4. Search for Chat Trigger.
5. Select the node shown as When chat message received.

Leave the Chat Trigger settings at their defaults for now. Most importantly, keep Make Chat Publicly Available turned off while you build and test. You do not want an unfinished agent exposed through a public URL.

The Chat Trigger has a simple job: it takes whatever you type in the chat window and sends that message into the workflow. In n8n, every chat message runs the workflow once, so five messages normally mean five executions.

Step 2: Add the AI Agent node

1. Close the Chat Trigger panel if it is open.
2. On the canvas, click the small + on the right side of the Chat Trigger node.
3. Search for AI Agent.
4. Select AI Agent.

You should now have a normal left-to-right connection:

When chat message received → AI Agent

Open the AI Agent node. For the prompt source, use the incoming chat message. In current n8n versions, the default option is usually phrased as Connected Chat Trigger Node or is already mapped from the chat input. If your version displays a prompt field instead, switch it to an expression and map the incoming chatInput value.

Add this as the system message or system instruction:

You are a careful assistant. Answer clearly and briefly. When the user asks for arithmetic, percentages, totals, averages, conversions, or other calculations, use the Calculator tool instead of doing the maths in your head. If the request is unclear, ask one short follow-up question. Never invent a tool result.

Why bother with that instruction? Because a language model can produce plausible-looking arithmetic that is still wrong. The system message gives the agent a clear rule: calculations go through the calculator.

Step 3: Connect the OpenAI Chat Model

This is the bit many tutorials describe too quickly. The chat model is not placed in the main left-to-right line. It connects underneath the AI Agent through the agent’s Chat Model connector.

1. Look at the bottom of the AI Agent node.
2. Find Chat Model and click its small +.
3. Search for OpenAI Chat Model and select it.
4. Open the new model node.
5. Under Credential to connect with, choose an existing OpenAI credential or click Create New Credential.
6. If your n8n Cloud workspace offers managed model access, choose that option instead of entering a separate key.
7. Choose a model that supports tool calling. For a basic test, use a smaller, lower-cost chat model available in your account.

Step 4: Give the agent a Calculator tool

Current n8n AI Agent workflows need at least one tool. Without one, you have connected a model, but you have not really built an agent—it has nothing it can choose to do.

1. Return to the AI Agent node on the canvas.
2. At the bottom of the node, find the connector labelled Tool.
3. Click the small + beside Tool.
4. Search for Calculator.
5. Select Calculator.

The Calculator tool does not need a credential and normally does not require any extra field configuration. The important part is the connection: its line must go into the AI Agent’s Tool port, not the normal input on the left side.

Step 5: Run the first test

1. Click Chat, Open chat, or the chat bubble button near the bottom of the editor. The label varies slightly by n8n version.
2. If n8n asks you to start the workflow, click Execute Workflow.
3. Type this exact message:

What is 17.5% of 240, plus 12? Show the result in one sentence.

The correct calculation is:

17.5% of 240 = 42
42 + 12 = 54

Your wording may differ, but the final number should be 54. More importantly, the execution should show that the AI Agent called the Calculator tool.

How to confirm the tool was actually used

1. After the reply appears, close or minimise the chat panel.
2. Open the latest execution from the workflow canvas or the Executions area.
3. Click the AI Agent node.
4. Expand the intermediate steps or logs, if your n8n version shows them.
5. Look for a Calculator tool call and its returned value.

If the answer is 54 but there is no tool call, the model probably calculated it by itself. Strengthen the system message to say, “You must use Calculator for every arithmetic request,” then run the same test again.

Step 6: Test the decision-making, not only the happy path

One successful message is encouraging, but it does not prove the workflow is reliable. Run these three tests before you add more nodes.

That third test matters. A useful agent knows when it does not have enough information. If it confidently invents revenue and cost figures, your prompt needs tightening before the workflow goes anywhere near customers or business data.

Optional: Add short-term memory

Once the basic workflow works, you can add memory so the next message can refer to the previous one.

1. Under the AI Agent node, click the + beside Memory.
2. Search for and select Simple Memory.
3. Keep the default context window for your first test.
4. Run the chat and send: My monthly software budget is 200 dollars.
5. Then send: What is 15% of that?

If memory is connected and the same chat session is still open, the agent should understand that “that” means 200 and return 30.

Common errors and the exact fix

“A chat model sub-node must be connected”

The OpenAI Chat Model is missing or attached to the wrong connector. Add it from the Chat Model plus button underneath the AI Agent.

The AI Agent has no usable tools

Add Calculator through the AI Agent’s Tool connector. Do not place Calculator after the agent in the main left-to-right workflow.

Authentication failed or the model list is blank

Open the OpenAI Chat Model node, re-select the credential and save it. If you use your own OpenAI account, confirm that the API key is active and the API account has billing or credit available. Your ChatGPT subscription alone may not cover API calls.

The chat window waits forever

Click Execute Workflow before sending the message. In manual testing, the Chat Trigger must be listening. Also check the latest execution: a red node usually shows where the run stopped.

The agent gives an answer but never uses Calculator

First confirm Calculator is connected to the Tool port. Then make the system message unambiguous: “For every arithmetic or percentage request, you must use Calculator.” Run the same numeric test and inspect the execution again.

The second message forgets the first

That is expected unless you connect memory. Add Simple Memory for local testing, keep both messages in the same chat session, and avoid Simple Memory on queue-mode production systems.

What to improve next

You now have the smallest workflow that genuinely demonstrates an AI agent: it receives a request, decides whether a tool is needed, calls that tool, and uses the result in its answer. That’s much more useful than starting with ten nodes and having no idea which one broke.

Your next upgrade should depend on the job you want the agent to perform:

• Add an HTTP Request Tool when the agent needs live data from an API.
• Add Google Sheets tools when it needs to read or update structured records.
• Add a persistent memory service when conversations must survive across sessions.
• Add human approval before any action that sends messages, changes records or spends money.

But don’t rush. Keep the calculator version, save it, and duplicate the workflow before experimenting. When the larger version breaks—and yes, eventually it will—you’ll still have a clean working baseline to compare against.

Official references used for this tutorial

• n8n Chat Trigger documentation
• n8n AI Agent documentation
• n8n OpenAI Chat Model documentation
• n8n Calculator tool documentation
• n8n Simple Memory documentation

Interface labels can shift slightly between n8n versions. The workflow structure and node connections in this guide follow the current official n8n documentation.