That last sentence is the point of this article. The model is the easiest decision you will make. Everything that determines whether the agent survives contact with real work — tool design, output structure, approval gates, testing — is architecture you have to build deliberately. This guide is about that architecture. For the wider picture of AI inside n8n, see n8n for AI automation.
In short
- The node is the Tools Agent. n8n's docs state the agent type setting is deprecated as of 1.82.0 and all nodes now act as a Tools Agent (n8n Docs).
- Chat models are interchangeable sub-nodes. OpenAI, Anthropic, Azure OpenAI, Groq and Mistral Cloud are among the documented options (Tools Agent).
- Fewer tools, sharper boundaries. Every tool added is another wrong path.
- Structured output is not optional for anything downstream of the agent.
- Approval gates belong on irreversible tools, not on the whole agent.
- Choose your model with an evaluation, not with a benchmark someone posted.
Do you actually need an agent?
Start here, because the honest answer is usually no.
An agent earns its complexity when the sequence of steps genuinely depends on the input. A rep asks a question and the system must decide whether to look in the CRM, check a calendar, or read a policy document — that is an agent. Classifying an inbound message into one of four categories is not; it is one model call with a fixed prompt, which n8n calls a chain.
The test we use: can you draw the flowchart? If you can draw it, build the flowchart. It will be cheaper, faster, easier to debug, and it will behave identically on Tuesday and on Friday. AI agents vs automation covers the distinction in depth, and agentic workflows covers the patterns worth using when you do need one.
The MitHub agent contract
Before opening n8n, we write five lines. If any line is hard to fill in, the agent is not ready to build.
| Line | Example answer |
|---|---|
| Job | Answer a rep's question about an account using our own systems |
| Tools | CRM record lookup, last-5-activities lookup, policy document search |
| Hard limits | Read-only. Never contacts a customer. Never writes to the CRM. |
| Output shape | { answer, sources[], confidence, escalate } |
| Escalation | If confidence is low or no source was found, hand to a named human |
The two lines people skip are hard limits and escalation, which are exactly the two that decide what happens on the bad day. An agent without a defined failure behaviour will invent one.
Assembling the agent in n8n
The chat model
Attach a chat model sub-node. n8n's Tools Agent documentation lists OpenAI, Anthropic, Azure OpenAI, Groq and Mistral Cloud chat models among the supported options, and the wider node index includes Google Gemini, AWS Bedrock, DeepSeek, Cohere, OpenRouter and Ollama for locally hosted models. Claude is reached through the Anthropic Chat Model sub-node, and each provider has its own node with its own model list and options.
How to choose between OpenAI and Claude, practically:
- Build the agent with whichever you already have credentials for.
- Assemble 30–50 real inputs, including the ugly ones, and label the correct outcome by hand.
- Run the set. Swap the chat model sub-node. Run it again.
- Compare on three axes: correctness on your labels, how well each follows your output schema, and cost per run at your volume.
- Keep the winner, keep the test set, and re-run it whenever you change the prompt.
This takes an afternoon and replaces an argument with a number. It is also the only comparison that reflects your data, which is the only comparison that matters. Provider model lineups change often, so treat any list of specific model names — including one you read today — as perishable and check the provider's own documentation.
The tools
Tools are what the agent can do. n8n exposes many app nodes as agent tools, and lets the model populate their parameters: the $fromAI() function dynamically fills in parameters for tools connected to the Tools Agent, and each eligible parameter field has a button that hands that field to the model (n8n Docs).
That convenience is also the sharpest edge in the whole build. A field the model fills is a field the model can fill wrongly — including record IDs, recipients and search filters. Three rules:
- Name tools by intent, not by app.
find_account_by_emailbeatsHubSpot. The name is part of the prompt. - One tool, one job. A single tool that can read, update and delete gives the model three chances to pick the wrong one under one label.
- Pin what should never vary. If a tool must always write to one specific list, hard-code it rather than letting the model choose.
n8n's Tools Agent also documents a Max Iterations option that controls how many times the model runs to generate an answer, defaulting to 10. Lower it for narrow agents. It is a cost ceiling and a loop guard at once.
Structured output
An agent that returns a paragraph forces the next node to parse prose. Turn on Require Specific Output Format and connect an output parser; n8n documents Auto-fixing, Item List and Structured parsers for this (Tools Agent).
The Structured Output Parser returns fields based on a JSON Schema. You can define the schema by hand, or generate it from an example JSON object — n8n notes that when generating from an example it uses the property names and types, ignores the values, and treats every field as mandatory (n8n Docs). Note also that $ref references in JSON schemas are not supported.
A schema we would use for the account-question agent:
{
"answer": "string",
"sources": ["string"],
"confidence": "high",
"escalate": false
}Then validate it anyway. If confidence comes back as something outside your allowed values, route to a human rather than letting an unexpected value flow onward.
Memory
Add memory only for conversations. n8n documents Simple Memory, which stores chat history for the current session, alongside memory services including Redis Chat Memory, Postgres Chat Memory, Motorhead, Xata and Zep, plus a Chat Memory Manager node for advanced cases (n8n Docs). The Tools Agent documentation is explicit that memory does not persist between sessions.
Two things worth knowing: memory is for agents, not chains — n8n's documentation notes AI chains cannot use memory. And a growing conversation history is a growing bill, since it is resent as context on every turn.
The system message
Write it as instructions to a competent new hire on their first day, not as a personality description. Cover: what the job is, what to do when data is missing, what it must never do, and the exact output shape. "You are a helpful assistant" is decoration. "If no account matches the email, set escalate to true and stop" is an instruction.
The gate: human approval on risky tools
This is the difference between a demo and something you would let near a customer.
n8n supports requiring human approval before an AI Agent executes a specific tool. The workflow pauses, sends an approval request showing which tool the model wants to use and with what parameters, and the tool runs only if a person approves; if denied, the action is cancelled and the model is informed of the rejection. Available approval channels include n8n's built-in Chat, Slack, Discord, Telegram, Microsoft Teams, Gmail, WhatsApp Business Cloud, Google Chat and Microsoft Outlook, and the review can happen in a different channel from the main interaction (n8n Docs).
The design choice is which tools get a gate. Our rule, borrowed from the risk tiers in human in the loop:
| Tier | Examples | Gate |
|---|---|---|
| Read | Look up a record, search documents | None |
| Internal write | Create a task, post to a team channel | None, but logged |
| External or irreversible | Email a customer, change a stage, delete | Always |
n8n's own guidance suggests starting with review enabled and reducing oversight as confidence grows. Make that a deliberate decision with a date attached, not something that erodes by neglect.
Testing, and the honest version of "it works"
An agent cannot be verified by reading it. n8n's evaluation documentation makes the case directly: code is deterministic and you can reason about it, but LLMs are black boxes, so you must measure output by running data through them. Evaluations let you test across a range of inputs including edge cases, make changes without quietly breaking what worked, and compare models or prompts (n8n Docs). The docs distinguish light evaluation while building from metric-based evaluation after deployment.
Build the test set before you ship, not after something goes wrong. It is also your proof of work: "it matched the human label on 44 of 50 real cases" is a claim a client can check. "It works well" is not. That distinction is the whole idea behind proof of work over credentials.
Pre-launch checklist
- The task genuinely needs decisions, not a flowchart.
- The agent contract is written: job, tools, hard limits, output shape, escalation.
- Every tool has an intent-based name and a single job.
- Nothing irreversible can run without human approval.
- Output is schema-constrained and validated after parsing.
- Max Iterations is set deliberately.
- Memory exists only if the task is conversational.
- Credentials live in n8n's credential store, never in prompts.
- An error workflow is attached and alerts a named person.
- An evaluation set exists, with a current score written down.
Next steps
Go wider with n8n for AI automation, or back to fundamentals with What is an AI agent? If you are choosing between building an agent and building a plain workflow, AI agents vs automation is the shorter answer. And if you want to learn this as a path rather than a tool, the Faculty of Revenue Reverse Engineering starts free.