12-Factor Agents: Design Principles for Building Reliable LLM Applications
12-Factor Agents is a methodology that, like the classic "12-Factor App" principles in software development, brings proven best practices from traditional software engineering to LLM-driven agent development. Its core goal is to bridge the gap between prototype and production-grade agents, so that agents meet enterprise standards for reliability, scalability, maintainability, debuggability, and security.
The 12 Principles
1. Natural Language to Tool Calls — Structure user natural-language instructions into API calls, leveraging the LLM's intent-recognition capabilities.
2. Own Your Prompts — Developers should have full control over prompts; prompts should be designed, version-controlled, and tested like code.
3. Own Your Context Window — Actively manage and construct the context passed to the LLM, containing everything the LLM needs for its decisions.
4. Tools Are Just Structured Output — Tool calls are essentially structured data generated by the LLM, triggering deterministic code execution.
5. Unify Execution State and Business State — Simplify and unify execution state and business state; agent execution state can be inferred from the context window.
6. Start / Pause / Resume via Simple APIs — Provide simple, intuitive API interfaces so various systems can easily interact with the agent.
7. Contact Humans via Tool Calls — The LLM interacts with humans explicitly through tool calls, rather than emitting natural-language requests directly.
8. Own Your Control Flow — Developers should have full control over the agent's control flow, instead of relying on a framework's predefined flow.
9. Compress Errors into the Context Window — Compress error information and integrate it into the context window so the LLM can understand and handle errors.
10. Small, Focused Agents — Build small, focused agents, each responsible for a specific task, rather than large multi-purpose agents.
11. Trigger from Anywhere, Meet Users Where They Are — Agents should be triggerable from various channels and interact with users wherever they are.
12. Make Your Agent a Stateless Reducer — Design the agent as a stateless reducer that receives input state and returns new state.
Conclusion
These principles are not a ready-made "toolbox" like LangChain, but a methodology that helps developers build production-grade LLM applications.