12-Factor Agents
Principles for building reliable LLM applications
In the spirit of 12 Factor Apps
Hi, I'm Dex. I've been hacking on AI agents for a while.
I've tried every agent framework out there, from the plug-and-play crew/langchains to the "minimalist" smolagents of the world to the "production grade" langraph, griptape, etc.
I've talked to a lot of really strong founders, in and out of YC, who are all building really impressive things with AI. Most of them are rolling the stack themselves. I don't see a lot of frameworks in production customer-facing agents.
I've been surprised to find that most of the products out there billing themselves as "AI Agents" are not all that agentic. A lot of them are mostly deterministic code, with LLM steps sprinkled in at just the right points to make the experience truly magical.
Agents, at least the good ones, don't follow the "here's your prompt, here's a bag of tools, loop until you hit the goal" pattern. Rather, they are comprised of mostly just software.
So, I set out to answer:
What are the principles we can use to build LLM-powered software that is actually good enough to put in the hands of production customers?
Welcome to 12-factor agents.
The 12 Factors
| # | Principle | Description |
|---|---|---|
| - | How We Got Here | A Brief History of Software |
| 1 | Natural Language to Tool Calls | Convert natural language to structured tool calls |
| 2 | Own Your Prompts | Don't outsource prompt engineering to a framework |
| 3 | Own Your Context Window | Control how you structure and present information |
| 4 | Tools Are Structured Outputs | Tools are just structured output that triggers deterministic code |
| 5 | Unify Execution State | Simplify by unifying execution and business state |
| 6 | Launch/Pause/Resume | Simple APIs for agent lifecycle |
| 7 | Contact Humans with Tools | Model human interaction as tool calls |
| 8 | Own Your Control Flow | Build your own control structures |
| 9 | Compact Errors into Context | Let the LLM read and recover from errors |
| 10 | Small, Focused Agents | Do one thing well |
| 11 | Trigger from Anywhere | Meet users where they are |
| 12 | Stateless Reducer | Your agent is a fold function |
Why 12-factor agents?
At the end of the day, the "loop until you solve it" approach doesn't work as well as we want it to.
In building HumanLayer, I've talked to at least 100 SaaS builders (mostly technical founders) looking to make their existing product more agentic. The journey usually goes something like:
- Decide you want to build an agent
- Product design, UX mapping, what problems to solve
- Want to move fast, so grab $FRAMEWORK and get to building
- Get to 70-80% quality bar
- Realize that 80% isn't good enough for most customer-facing features
- Realize that getting past 80% requires reverse-engineering the framework, prompts, flow, etc.
- Start over from scratch
The fastest way I've seen for builders to get good AI software in the hands of customers is to take small, modular concepts from agent building, and incorporate them into their existing product.