Overview
12-Factor Agents is a methodology for building reliable LLM applications — analogous to the classic "12-Factor App" principles in software engineering, but applied to large language model (LLM) driven agents. Its core goal is to bridge the gap between prototype and production, helping agents achieve enterprise-grade reliability, scalability, maintainability, debuggability, and security.
The 12 Principles
1. Natural language to tool calls — Convert user natural language instructions into structured 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, including everything needed for its decisions.
4. Tools are just structured outputs — Tool calls are essentially structured data generated by the LLM that trigger 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. Launch/pause/resume via simple APIs — Provide simple, intuitive API interfaces so external systems can easily interact with agents.
7. Contact humans through tool calls — The LLM should interact with humans explicitly via tool calls, not by emitting natural language requests.
8. Own your control flow — Developers should fully control the agent's control flow rather than depending on a framework's preset pipeline.
9. Compress errors into the context window — Compress and integrate error information into the context so the LLM can understand and handle failures.
10. Small, focused agents — Build small agents, each responsible for a specific task, instead of large multi-purpose agents.
11. Trigger from anywhere, meet users where they are — Agents should be triggerable from many channels and interact on the user's platform of choice.
12. Make your agent a stateless reducer — Design the agent as a stateless reducer: it takes an input state and returns a new state.
Takeaway
This is not a ready-made toolbox like LangChain — it is a methodology that helps developers build production-grade LLM applications.