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, creatively applies proven software engineering best practices to LLM-driven agent development. Its core goal is to bridge the gap between prototype agents and production-grade applications, so that agents reach enterprise standards in 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 LLM 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 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 agents.
7. Contact humans via tool calls — The LLM should interact with humans explicitly through tool calls, not by outputting natural-language requests directly.
8. Own your control flow — Developers should fully control the agent's control flow, rather than relying on a framework's predefined pipeline.
9. Compact errors into the context window — Compress and integrate error information into the context 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 wherever users are.
12. Make your agent a stateless reducer — Design the agent as a stateless reducer that receives an input state and returns a new state.
Conclusion
This set of principles is not a ready-made "toolbox" like LangChain, but a methodology that helps developers build production-grade LLM applications.