12-Factor Agents: Principles for Building Reliable LLM Applications
by HumanLayer (Dex Horthy)
Twelve production-tested principles for shipping LLM agents customers can actually rely on.
Overview
Written by Dex Horthy of HumanLayer, 12-Factor Agents is a design-and-review checklist rather than a framework or library. It argues that the best production 'agents' are mostly well-engineered software with LLMs inserted at key decision points, and codifies that into twelve factors: (1) Natural language to tool calls, (2) Own your prompts, (3) Own your context window, (4) Tools are just structured outputs, (5) Unify execution state and business state, (6) Launch/Pause/Resume with simple APIs, (7) Contact humans with tool calls, (8) Own your control flow, (9) Compact errors into the context window, (10) Small, focused agents, (11) Trigger from anywhere and meet users where they are, and (12) Make your agent a stateless reducer. The repo pairs each factor with explanations, diagrams, and TypeScript code, and is meant to be applied on top of whatever framework or custom harness you already use. Content is CC BY-SA 4.0 and code is Apache 2.0.
At a Glance
- Topic
- Agentic
- Level
- Advanced
- Format
- Guide
- Cost
- Free
- Duration
- ~1-2 hour read, self-paced
- Provider
- HumanLayer (Dex Horthy)
- Hands-on
- No
- Certificate
- None
What You’ll Learn
- ✓Twelve concrete principles for architecting agents that survive real production traffic
- ✓How to own your prompts, context window, and control flow instead of ceding them to a framework
- ✓Modeling agents as stateless reducers with launch/pause/resume APIs for durability
- ✓Designing small, focused agents and folding errors back into the context window
- ✓Using human-in-the-loop tool calls to keep agents safe and correctable
Highlights
- •A vendor-neutral checklist you can apply on top of any framework or custom harness
- •Distilled from interviews with dozens of teams shipping agents to production
- •Reached the front page of Hacker News and thousands of GitHub stars in 2025
Who It’s For
Best For
- ✓Engineers moving an agent from prototype to production
- ✓Technical founders integrating agentic features into an existing product
- ✓Teams doing architecture reviews of an LLM agent design
Prerequisites
- •Working experience building LLM apps with tool/function calling
- •Familiarity with an agent framework or a custom agent loop
FAQ
What is 12-Factor Agents: Principles for Building Reliable LLM Applications?
An open-source engineering guide, modeled on Heroku's 12-Factor App, that distills twelve design principles for building reliable, production-grade LLM agents. It is for engineers who have moved past demos and need agents robust enough to put in front of real customers.
Is 12-Factor Agents: Principles for Building Reliable LLM Applications free?
12-Factor Agents: Principles for Building Reliable LLM Applications is free to access.
What level is 12-Factor Agents: Principles for Building Reliable LLM Applications for?
12-Factor Agents: Principles for Building Reliable LLM Applications is aimed at a advanced audience. Recommended background: Working experience building LLM apps with tool/function calling, Familiarity with an agent framework or a custom agent loop.
How long does 12-Factor Agents: Principles for Building Reliable LLM Applications take?
Expect roughly ~1-2 hour read, self-paced. Most learners work through it at their own pace.
What will I learn from 12-Factor Agents: Principles for Building Reliable LLM Applications?
You'll learn: Twelve concrete principles for architecting agents that survive real production traffic; How to own your prompts, context window, and control flow instead of ceding them to a framework; Modeling agents as stateless reducers with launch/pause/resume APIs for durability; Designing small, focused agents and folding errors back into the context window; Using human-in-the-loop tool calls to keep agents safe and correctable.