Best practices for building reliable, maintainable AI agents in n8n
Nate B Jones shares a practical guide to building AI agents in n8n without breaking them.
Summary
Nate B Jones addresses a common frustration among non-developer professionals who want to build custom AI agents using n8n: the tool's visual workflow builder is highly accessible, but that same accessibility becomes a trap that leads to unmaintainable, fragile, and eventually abandoned automation projects. He argues that building agents in n8n is genuinely building software, and that non-technical builders must adopt core software engineering principles — particularly simplicity, separation of concerns, and documentation — to succeed. He recommends using LLMs to generate JSON-based workflow configurations rather than relying purely on drag-and-drop, because JSON forces clarity and can be paired with auto-generated documentation. He closes by warning that when agents built without these principles break, businesses draw the wrong conclusion — that AI agents don't work — when the real problem is that they were built badly.
Key Takeaways
FULL TRANSCRIPT
The n8n Goldilocks problem: who this is for
Nate B Jones: Today I want to give you a key to one of the most persistent questions I get in the AI space. It's about AI agents, and specifically: I need to get started building AI agents. I'm not sophisticated enough. I don't have enough coding background to do it with just code. So these people are not going to use LangChain. They're not going to use LangSmith. They want simple agents — agents they can use — and they want custom agents.
A tool like Lindy.ai, which has a lot of out-of-box agents and some composability, feels limiting to a lot of the people I talk to in this situation. A tool like n8n feels just about right because it's more composable, more customizable. You can bring some code, and so they feel like they're in a playground.
But if you are getting started with agents, you need to recognize that that composability, that configurability, the power you feel with n8n — is the trap. That is the trap. And that is why this video exists.
People get started with something like n8n and they get so excited. The stars come out in their eyes. They feel the AGI. They feel the AI agents. They know they can do all this cool stuff. And then they find out that the AI agent breaks. They find out they have 556 of them across the business and God knows what's happened to 332 of them, and only 50 of them are being used regularly, and it's all adding up to a big bill. They find out the person that built the agent went on vacation, and now they don't know how to fix it because this drag-and-drop thing has created a tangled mess and it's impossible to see. Those are all real-life examples. I have seen it over and over again.
This video is going to help you get from "I want to do custom agents" to "I can do custom agents. I can use n8n. It's a great tool, but I know how to do it well. I know how to follow best practices when building agents, and I don't have to be a custom coder to do it."
I have written comprehensive guides to agents. This is more narrowly focused — very comprehensive, but more narrowly focused on what I call the Goldilocks use case. It's not "I am so out-of-box, I just want a pre-built agent for my calendar." It's also not "I am so freestyle, I'm a developer and I can do anything." It's in between. It's the people who want customizability without committing to a code-only lifestyle.
The two truths about n8n
So the first truth to understand if you're in this bucket is that n8n has a visual workflow builder that genuinely democratizes automation, and that's part of why people gravitate to it. For the first time, it is really genuinely possible — and this does work for non-programmers — to build sophisticated AI agents just by dragging and dropping little nodes into a little tree.
The second truth, which I've already hinted at, is that the same visual builder is a complexity trap. It has killed so many n8n implementations. Ironically, the very feature that makes you want to use it is the feature that becomes unmaintainable at scale.
But worry not — I'm going to give you a way through.
The honeymoon phase and the trough of disillusionment
I want to map out how to get from that honeymoon phase — where you install n8n, you start to build your first node, you start to see data flowing across the screen, it feels so cool, it works, you feel like you've unlocked superpowers, you want to build ten more of them — through the trough of disillusionment, where you have to add error handling, you have to add conditional logic, that's even more nodes, the edge cases pile up, you tell yourself it's manageable, but the clean workflow now looks like the subway map of Manhattan. It looks ridiculous, like a pile of spaghetti.
At a certain point, if you are serious and you are only using the nodes and dragging and dropping, you are going to get to a point where you have 12 workflows and 633 nodes and it fails at 2 a.m. and you're spending three hours debugging it and you feel like you are in hell. It is an incredible pain. You can't simulate inputs correctly. There are nodes that have failed. There's an LLM call that's different because LLMs have updated. You have error objects when they fail and you don't know what that means.
This is where you can actually shift your approach. You don't have to go down that path. You can actually build agents that are useful.
Real-world scale: what success looks like
As an example, a real company — StepStone — runs 200 mission-critical workflows in n8n. They achieved approximately a 25x speed-up in API integration time. Two hundred workflows takes focus. If you are going to do it at the scale of a company, you almost need to treat n8n like a hub of excellence where your product, marketing, and customer success teams meet your technical teams, and everybody can focus on creating reliable, simple, clear, followable workflows.
That's something I'm going to emphasize again and again: when you are building, make sure they're reliable, simple, and clear.
JSON as a simplifier
And you might say, "Nate, is this whole video about you telling me that my workflows in n8n are complicated? I already knew that." No. This is about suggesting to you that you can get farther with your workflows if you put them into JSON representations, because JSON representations tend to force simplicity. When you build them in LLMs, those LLMs tend to obsess over making workflows as simple as possible.
JSON representations of workflows are like kitchen instructions. They tell the chef what to make. One of the things that makes them powerful is that yes, you can drag and drop a workflow, but you can also do this programmatic kitchen-instruction approach where you just hand the chef the JSON workflow and say "do this," and it will work.
I want to suggest that JSON representations are useful here — not because LLMs have some magic power with JSON (I saw that circulating around the web and I kind of rolled my eyes — that's not what I'm trying to say). It's just that JSON is a good ingestion method that this particular tool, n8n, happens to understand, that LLMs can write well, and that you can use as a carrier or a vessel for the clarity of vision that you have. JSON acts as a simplifier for you.
If you work with Claude, if you work with ChatGPT to build a JSON workflow for your n8n automation, you are so much more likely to have a workflow that works — especially if you are invoking the documentation that n8n publishes about their workflows and their tool calls, because then the LLM will know that when it's writing the workflow and it will be less likely to have errors.
You are building software — even if you're not a developer
I also want to suggest to you that if you are in the business of building agents, it is probably better to understand that you are in the business of building software, even if you're not a developer. I don't want that to scare you, but I try to convey it honestly because I don't want people to be surprised.
Effectively, instead of programming, you're configuring — so it feels easier, but it's actually going to be more strategic. It's going to require more thinking and intent on your part. And it's going to require you to understand some things that most software engineers have built into their DNA that doesn't come built into other job families. I am here to bridge that gap for you so your agents work better.
The simplicity principle
Let's start with a simplicity principle. You need to build workflows that are as ruthlessly simple as they can possibly be in order to maintain them. Simple, simple, simple. Drill it into your head.
The reason why is that simple is maintainable. This is why engineers will tell you they need to refactor the back end of the codebase, and you wonder what they're doing. Engineers out here are nodding their heads — they know. They have to refactor the back end of the codebase because they have to make it simple, maintainable, and scalable. Simple is scalable. Simple is maintainable. Simple is readable.
Effectively, what you have with n8n and agents is a combination of function and documentation in one format. That spaghetti code that looks like the subway map of Manhattan is both the actual diagram of the workflow and also your only documentation. That is why it hurts so bad.
The advantage of composing these workflows in JSON is you can not only be more accurate and more likely to be simple — if you're working with an LLM that has a bias toward simplicity, you can tell it to be simple and it will help you get there. You can also use that exact same LLM to write the documentation for the JSON you're generating. "Here is the documentation so I can save it, maintain it, and know why I made the decisions I did." I would encourage you to do that, because you want to be in a place where you're not the only one maintaining it — unless you're a solo builder, which, by the way, it is possible to have a solo business that works this way.
The Bordr example: 18 nodes for Portuguese bureaucracy
As an example of a small business that did this, a company called Bordr — B-O-R-D-R, they dropped the E — built a real business helping people navigate Portuguese bureaucracy. This is part of the expatriate workers movement, the nomad movement, where you can work around the world. They used n8n to do it. The entire operation runs on n8n workflows.
I want you to guess how many of those little boxes on n8n they have for their core workflows. Go ahead. Guess.
They have 18. Not 180, not 18,000. Eighteen.
They understand that complexity compounds risk. Complexity also compounds exponentially in automation — this is just basic graph theory. Every node you add does not just add one more thing to maintain. It adds interactions with so many other nodes. A 10-node workflow has something like 45 possible interaction points. A 20-node workflow — just 10 more — would have 190. A 50-node workflow would have over 1,200.
Now, Portuguese bureaucracy is legendarily complex, which is why the business exists. Their workflows are simple not because the problem is simple, but because they understood how to decompose complicated problems into composable parts. Every workflow does one thing. It does it well. And it can be understood quickly. That is a principle of software engineering that I don't think is widely enough understood by people getting started with n8n and building agents.
People in that Goldilocks bucket almost all overwhelmingly tend to come from the non-technical side. And by the way, if you're an engineer listening to this, this video is kind of your get-out-of-jail-free card when the director of marketing draws this ridiculously complex whiteboard full of nodes and says, "This is what we want for our agent," and you're screaming on the inside. Show them this.
Separation of concerns and the microservices lesson
The simplicity principle really matters. And I said "composable parts" on purpose. One of the fundamental aspects of software engineering is the idea of separation of concerns — another way to put it is: things go in their proper place. You keep your concerns neat and tidy so that you can manage them well later. This is where, at a larger scale, we get the idea of microservices.
I'm going to take a tiny diversion here because I worked at Amazon, and Amazon is where the idea of microservices and APIs originated. Yes, we invented them, along with lots of other things. I don't know if you consider that a curse or a blessing, but you've got it anyway.
Microservices are the idea that the separation of concerns is so important in software that you cannot scale at a certain point unless you have it. We started off in coding by building monoliths — what we would call the subway map of Manhattan for n8n. That was software. Even at Amazon, 15 or 20 years ago, everything was one giant codebase. Well, that makes it really hard to maintain as you get bigger and bigger. You don't know what a piece of code touches. Only the senior engineer who never takes a vacation knows, and God help him if he gets hit by a bus.
Microservices existed because we had to have them exist to actually build. We had to separate concerns. And now every engineer knows about it because it's just such an obviously good idea. You separate out the components of the software. You standardize how those components exchange data and business rules — that's what we call APIs. And then you have separate concerns you can manage cleanly.
Apply that principle when you are building agents. Don't build a monolith agent that does everything. Separate out your concerns cleanly so that you only have to do one or two things in a particular agent. It's really, really critical to focus.
The Delivery Hero example: one well-defined process
Here's another real example. Delivery Hero saved hundreds of hours a month with their n8n automation. They handle hundreds of requests automatically. And notice what they automated: IT account recovery. Not the whole IT department, not all employee requests — just one well-defined process.
This reinforces what I'm saying. If you want to be successful in an agent implementation, you must focus radically. Identify one process. It needs to be painful. It needs to be frequent. It needs to be really well-defined with good edges. Automate it all the way. Run it. Obsess over it. Learn what breaks. Fix the breaks. Only when it's mature, sustainable, and well-documented do you move to the next process.
The typical failure pattern I see is the opposite. Teams don't clearly define the pain. They don't know where the edges are. They had a seminar, the seminar said "use AI agents," they got all excited, and they try to automate everything at once. They build giant sprawling workflows that touch multiple systems. It looks incredible, and on day one it all works, and they have a CEO announcement. They're creating dependencies they don't understand. And when something breaks — and it always breaks, plan for it to break — they can't isolate the problem because nobody can read the map anymore, because everyone's on to the next project because the CEO declared victory on AI agents.
AI agents are not a tickbox. If you want to implement AI agents, implement them this way. AI agents are just a new way of doing software for everybody. And it is possible to do software for everybody. I firmly believe that if you work with your favorite LLM — whether that's Claude, ChatGPT, Gemini, or even Grok — you can get to a point where you build this yourself, and it builds in line with what I'm suggesting. It's simple. It's composable. It fixes real pain points. You don't have to have an engineer to do that. But let's recognize that you are doing real engineering work. You are actually building software.
This is part of the magic of the AI era. If you're willing to think this way, with this kind of clear intent, you too can do the work of building software and you can generate the magic — the real ROI — that comes from true automation. Remember when I said Delivery Hero saves 200 hours a month? They do. It's real. Because it turns out that at scale, a lot of people need their IT accounts recovered, and that's a very predictable workflow. Bordr can maintain their scale and navigate Portuguese bureaucracy because they built these agents effectively. And it's not the tool that's the difference — these companies are using n8n too. They just know how to use it.
So if you're in this Goldilocks use case, you should be encouraged. Yes, this is a real use case. It really matters. You really can automate it. You don't need to wait for the developers. But you've got to take it seriously.
The team problem: automation is not a solo product
One thing I want to emphasize at this point — we've talked about best practices for coding, best practices for software, the team problem. Your private automation is not a team-level product. Nobody talks about this. n8n likes to market this as individual productivity because, frankly, it gets them more seats and customers.
You can build an agent that works perfectly for you. You might understand its quirks. You know how to restart it when it hangs. You remember to clear the memory cache weekly. You know how it fails on PDFs over 10 megabytes in size. And then you go on vacation. And it turns out this was producing a deliverable your team cared about. Your team can't debug your workflows when they break. They don't know why certain design decisions were made. They're afraid to modify anything because they might break something else. It looks like scared spaghetti on the wall. This is how automation projects die — not really from technical failure, but from knowledge isolation, from silos.
Successful transitions require documentation that's useful. Remember when I said document? I said document because your automation is your team's problem. Don't create huge manuals that nobody reads. Just create very simple, very short runbooks. "When this error appears, check this." "This workflow depends on this webhook." "Clear this cache every Monday or response times degrade." Patterns, patterns, patterns. You don't need to be creative. You need to have clean patterns.
Every workflow, ideally, would follow the same error handling pattern. Every agent, if possible, should use the same memory config. Is it boring? Yes. Is it maintainable? Exactly. That is the point.
The more we make n8n and agent automations a team-level product, the better off we are going to be. And this, by the way, is one of the hidden linchpins in AI strategy and AI work. We typically talk to the C-suite and we talk to individual contributors, and senior managers and directors — people who run teams — are left out of most of the conversations. When we're talking to individual contributors, we implicitly assume they're the leadership with the C-suite. When we're talking to leadership, we implicitly assume they're with the individual contributors. They're neither, and they are critical to the AI revolution.
This kind of example shows why. You cannot make an n8n automation a C-suite problem — it's way too high level. But you also cannot make it an individual contributor problem, because that leads to all kinds of downstream breakages and workflow failures. It's a team problem, which means it's a director problem, a senior manager problem. You people in those positions need to be the ones insisting on a high bar here — insisting that your team, even if they're marketers, learns enough of the basics of good engineering principles that when you touch automations and build agents because the C-suite said you needed to do it, you do it well and you don't give yourself pain down the road. You can make cheap automations that tick that box, and you will give yourself a world of suffering down the line.
LLMs as an accelerant — in multiple directions
So let's get to one last piece here. LLMs are an accelerant in multiple directions for n8n.
One: LLMs enable you to do more. They tie intelligence directly into workflows. For a lot of people who are not developers, n8n represents the first and most accessible front in the integration pathway. You can actually tie your chatbot into real work. You don't have to use the API necessarily, because effectively you're proxying for that through n8n. You can just pretend it's not there and go on with your business. And that is huge, because people want to get real work done. They want to monitor Slack channels for customer complaints. They want to categorize sentiment analysis by urgency. They want to create tickets in Jira. They want to process records in a certain way. They want to send a daily summary to a support lead. This is all real work you can't get done in the chatbot.
Claude, ChatGPT, or other LLMs can generate not just the JSON config for those workflows, but also the design decisions and why they were made, and the documentation. In other words, you access the intelligence inside the workflow — and that's an accelerator. Working with the chatbot is an accelerator as well.
Two: this is the second way LLMs accelerate you. What I am talking about — the reason I am making this video — would not have been possible even eight months ago. n8n wasn't mature enough. Chatbots weren't mature enough. They weren't good enough at checking documentation reliably. We are at a point now where it's mature. n8n is ready. You can get LLMs that reliably pull up the correct documentation. They're going to give you reliable workflows. They're smart enough to give you good documentation and really help with constructing agent ecosystems that work at the team level.
This is actually not as hard as you think. You really can build a couple of simple workflows, monitor the heck out of them, check for errors, and go on and expand from there. You can even get to the point — if you've done this for a couple of months and you know what you're doing because you've been slow and focused — where you can do stuff that's more interesting. I know I said slow. In this case, slow is smooth and smooth is fast. Because you've focused on implementing smoothly and only doing one edge case at a time, you will quickly get to the point where you can do stuff that's more interesting.
Where it may make sense — given the problem is well-defined and you understand it well — to use a complex memory system like retrieval-augmented generation. You can do that in n8n. People jump right to it. I wouldn't recommend jumping right to it. You can use multi-agent orchestration. You can use complicated tool chains. That's all there, but I wouldn't start there. Start with something simple and get to it over time.
The real ROI — and the real danger
There are real savings here. Vodafone saved 2.2 million pounds with an n8n workflow. They're big — that's part of how they got there. But recognize that the real ROI comes from the principles I've talked about.
n8n is simultaneously one of the best, most accessible, and most dangerous tools I have seen for building AI agents. It's accessible in the sense that you can just start right now — you don't even have to listen to this video. It's dangerous in the sense that I see, time after time after time, in real-world situations where I talk with people passionate about agents, that n8n is the thing that burned them out. Because it was so accessible, they felt like they could be non-programmers and not pay attention to good engineering principles.
Please recognize that you are building real software and follow good principles. Emphasize simplicity. Separate concerns. Focus on maintainability. Focus on readability. Get your documentation done. Work with an LLM. Solve a problem that's well-bounded.
Your choice is whether to understand when each approach serves you and to have the discipline to switch between approaches when you need them. Whether you need to take a focused approach on a particular agent, or whether it makes sense to do two agents for a particular problem that requires high intention, high thought, and careful architecture — or you can just follow the marketing and believe that you can throw something up on a canvas in n8n and it will just work. That works great in marketing. It demos okay. It's not going to sustain well over time.
Your choice is between building maintainable software with an approach that serves you — an approach that you have the discipline to scale over time — or starting with what the marketing tells you and doing the multi-agent setup, the RAG, and everything else right now. I understand the appeal. Agents are really cool. I like building with them. But take the time to get into agent building in a way that serves the long-term value of the business, and frankly helps you sleep well at night. No one wants to get interrupted on vacation because their agent broke.
If this works, it's not only going to help you work — it's going to help your team actually use agents. And it's going to do something more than that. It's going to help your business understand what this agent thing is all about.
That's why I call n8n somewhat dangerous, because a lot of the time what I see is that as these agents break, what businesses understand is that AI agents are fake, AI agents aren't real, AI agents aren't delivering the value that was promised. That's not actually true. But it is true if you use them badly.
n8n is like a knife. You can use a knife badly or you can use a knife well. I'm trying to give you the principles to use it well. Good luck with agent building. I know you've got this.