In 2011, engineers at Heroku published a document called the "12-Factor App." It wasn't code or a framework, but a methodology—a guide on how to build scalable, maintainable SaaS applications.
This document later became the de facto standard for the cloud-native era. Docker, Kubernetes, and various microservice frameworks all carry the 12-Factor DNA in their core.
Now, someone wants to do the same for AI Agents.
humanlayer/12-factor-agents, 21,600 stars, 273 commits. The author, Dex, puts it bluntly:
I've tried every Agent framework out there—from out-of-the-box solutions like CrewAI and LangChain, to those claiming to be "minimalist" like SmolAgents, to those touting themselves as "production-grade" like LangGraph and Griptape. But most products that call themselves "AI Agents" aren't actually that agentic. They are mostly deterministic code with a few LLMs sprinkled in at the right spots.
It might sound harsh, but if you think about it carefully, it's true.
Core Idea: A Good Agent Isn't "Just Give It a Goal and Let It Run"
The very first principle of 12-Factor Agents overturns many people's understanding of what an Agent is:
Factor 1: Natural Language to Tool Calls
The core capability of an LLM isn't "thinking," but translating natural language into structured tool calls. This means the design focus of an Agent should be on "providing the right tools" and "defining the correct call formats," rather than letting the LLM fumble around in boundless freedom.
Factor 8: Own your control flow
This one is even more critical. The pattern many people use to write Agents is: "Give it a prompt, hand it a bunch of tools, and loop until it's done." 12-Factor explicitly states: This doesn't work.
For an Agent that can truly run in production, the control flow must be defined by the developer—which steps are deterministic, which steps can be delegated to the LLM for decision-making, when human intervention is needed, and how to roll back when errors occur. The LLM is the engine, but you must hold the steering wheel.
A Quick Overview of the 12 Principles
These 12 principles cover every aspect of Agent development:
- Factor 1-4 cover the underlying logic of "tool calls": natural language → structured output → context management → tool definition
- Factor 5-7 cover "execution state": how to uniformly manage business state and execution state, how to pause/resume, and how to introduce human intervention
- Factor 8-10 cover "architecture design": control flow ownership, error compression, and Agent granularity
- Factor 11-12 cover "integration and deployment": triggering from anywhere, and turning the Agent into a stateless reducer
I've picked out a few of the most practical ones to discuss separately.
Factor 3: Own your context window
Context windows are not infinite. 12-Factor emphasizes that you must manage context strategically—what information to keep, what to compress, and what to discard. Otherwise, as conversations grow longer, the LLM's performance will drop off a cliff.
Factor 7: Contact humans with tool calls
This one is highly practical. When an Agent encounters uncertainty, it shouldn't "guess blindly," but should instead use a tool call to request human intervention. It sounds simple, but most Agent frameworks haven't designed this as a first-class citizen.
Factor 12: Make your agent a stateless reducer
This is arguably the most "engineering-minded" principle. Think of the Agent as a reducer function: give it an event and the current state, and it returns a new state. Being stateless means it can be horizontally scaled, retried, and monitored.
Why Is This Guide Worth Your Attention?
Because the biggest problem in AI Agent development right now isn't "the technology isn't strong enough," but rather "the methodology hasn't been established yet."
Everyone is experimenting, stumbling into pitfalls, and reinventing the wheel. The value of 12-Factor Agents lies in its attempt to systematize these scattered experiences into a set of principles that can be discussed, iterated upon, and passed down.
It doesn't tie you to any framework or recommend any specific tech stack. It answers a more fundamental question: When you want to use an LLM to build a product that actually works, what principles should you follow?
Primary Source: GitHub - humanlayer/12-factor-agents