12-Factor Agents — Detailed introduction
12-Factor Agents is an opinionated, practical guide and GitHub project that defines a set of engineering principles for building reliable, maintainable, and production-grade applications powered by large language models (LLMs). Unlike toy agent patterns that rely heavily on an LLM to orchestrate every decision, this project emphasizes software engineering practices that combine deterministic code with well-scoped LLM responsibilities so the resulting systems are robust enough for real customers.
What it is
- A documented manifesto of 12 principles (the "12 factors") that help teams design LLM-enabled features with production quality.
- A collection of essays, examples, and recommended patterns (hosted in the repository) explaining each factor in detail.
- A community resource: the repo links to talks, demos, and discussions and is licensed to encourage reuse (code: Apache 2.0; content: CC BY-SA 4.0).
Who it's for
- Engineers and technical founders building customer-facing products that embed LLMs or agent-like flows.
- ML/MLops engineers who want guidelines to integrate LLM steps into existing software systems while preserving observability, retryability and maintainability.
- Architects designing workflows where LLMs act as components (e.g., generating structured tool calls) rather than full runtime orchestrators.
Core themes and highlights
The project distills recurring problems and practical solutions into 12 concise factors. Key themes include:
- Own your prompts and context: explicitly manage and version prompts; prefetch and compact context so model context windows are used efficiently.
- Treat tools as structured outputs: prefer schema-aligned outputs or function-like tool calls to reduce parsing failures.
- Unify execution and business state: keep the agent's execution state and the application's business state synchronized for easier debugging and resumption.
- Simple lifecycle APIs: provide clear launch/pause/resume semantics so long-running flows are observable and controllable.
- Contact humans via tool calls and keep control flow explicit: avoid pushing all control to the model; encode deterministic edges when reliability matters.
- Compact errors into context windows and design small, focused agents: keep each agent narrowly scoped and handle errors in a way that fits into the model's context budget.
- Make agents stateless reducers: encode state transitions so agents can be resumed or replayed deterministically.
The 12 factors (short list)
- Natural Language to Tool Calls
- Own your prompts
- Own your context window
- Tools are just structured outputs
- Unify execution state and business state
- Launch/Pause/Resume with simple APIs
- Contact humans with tool calls
- Own your control flow
- Compact Errors into Context Window
- Small, Focused Agents
- Trigger from anywhere, meet users where they are
- Make your agent a stateless reducer
Formats and resources
- The repo contains individual markdown pages for each factor, diagrams and code snippets demonstrating patterns.
- It links to conference talks and videos for live walkthroughs, and it references related OSS projects and community threads for discussion.
Origin and metadata
- Published on GitHub by the HumanLayer organization (author/maintainer: Dex Horthy and contributors).
- Created: 2025-03-30 (repository creation date).
- Popular and community-driven: the project has gained significant attention (many stars) and community contributions.
Why it matters
As LLM capabilities increase, the temptation is to hand more responsibility to models. 12-Factor Agents provides an engineering-first counterbalance: it helps teams keep the LLM as a reliable component within a larger, well-engineered system. The guidance is practical and intended to reduce surprises when moving from prototypes to customer-facing deployments.
License
- Code: Apache 2.0
- Content and images: CC BY-SA 4.0
(For hands-on usage, examples, and to contribute, see the repository on GitHub.)
