12-factor-agents
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?
A practical guide proposing twelve engineering principles for building reliable AI agents that work in production, treating them as conventional software with targeted AI steps, not fully autonomous loops.
12-Factor Agents is a guide — modeled after the well-known "12 Factor App" methodology for web applications — that proposes twelve concrete engineering principles for building AI-powered software that is reliable enough to deploy to real production customers. The core argument is that most successful AI agent products are not fully autonomous loops of an LLM calling tools until something works; they are mostly conventional software with AI steps embedded at precisely the right moments.
The twelve factors cover the full lifecycle of building a production-grade AI agent. Several focus on controlling how information flows into the language model: own your prompts (write and version them yourself rather than relying on framework defaults), own your context window (carefully curate what the model sees rather than feeding it everything), and compact errors back into context rather than crashing. Others address architecture: keep agents small and focused on a single task, make agents stateless so they can be paused and resumed like a pure function, and treat tool calls as structured data outputs rather than magical actions. Factor 7 specifically addresses human oversight — designing the agent to contact a human through a tool call when it encounters uncertainty, rather than guessing.
A developer or founder building LLM-powered features into a product — whether a coding assistant, customer support bot, or workflow automation — would use this guide to avoid common pitfalls and architectural dead ends. The content lives in Markdown files in the repository and the code examples are in TypeScript. It is published under Apache 2.0 (code) and Creative Commons BY-SA 4.0 (content).
Where it fits
- Apply the 12 factors to audit your LLM agent and fix common architectural mistakes before deploying to real customers.
- Use Factor 7 to add a human-approval checkpoint so your agent pauses and asks for help when it hits uncertainty instead of guessing.
- Restructure a chaotic LLM pipeline by making each agent stateless and versioning your prompt templates in git.
- Build a customer support bot that contacts a human via a tool call when confidence is low rather than hallucinating an answer.