12-Factor Agents: Principles for Building Reliable LLM Applications
by HumanLayer
Twelve production patterns arguing that good agents are mostly ordinary software with a few LLM calls.
Overview
Dex Horthy's collection of production patterns for LLM applications, published as markdown chapters in the humanlayer/12-factor-agents repository, with content under CC BY-SA 4.0 and code samples under Apache 2.0. Its opening question is deliberately unfashionable: what principles can we use to build LLM-powered software that is actually good enough to put in the hands of production customers? The answer it argues for is that successful production AI applications are mostly just software with strategic LLM integration points, rather than a pure autonomous agentic loop. The twelve factors are: 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 Context Window, 10) Small, Focused Agents, 11) Trigger from anywhere, meet users where they are, and 12) Make your agent a stateless reducer. Several cut directly against framework defaults — factors 2 and 8 are explicit arguments against letting an agent framework own your prompts or your loop. Each chapter carries navigation diagrams and code examples. The repository has passed 25,000 stars; a companion 17-minute AI Engineer World's Fair talk covers the same material, and the original Hacker News thread drew 475 points and 78 comments.
At a Glance
- Topic
- Agentic
- Level
- Intermediate
- Format
- Guide
- Cost
- Free
- Duration
- ~2 hours to read all twelve chapters
- Provider
- HumanLayer
- Hands-on
- No
- Certificate
- None
What You’ll Learn
- ✓Model an agent as a stateless reducer over its own execution state
- ✓Own your prompts and control flow instead of delegating them to a framework
- ✓Unify execution state with business state so agents become pausable and resumable
- ✓Model human approval and escalation as a tool call rather than an out-of-band interrupt
- ✓Compact errors back into the context window so an agent can self-correct
- ✓Decompose one large agent into small, focused agents with narrow responsibilities
- ✓Design launch, pause and resume APIs so long-running agents survive process restarts
Highlights
- •Over 25,000 GitHub stars and a 475-point Hacker News thread — this is the shared vocabulary for agent design
- •Argues explicitly against agent frameworks owning your prompts and control loop, with reasoning
- •Free markdown under CC BY-SA with Apache 2.0 code, so you can fork and adapt it internally
- •Companion 17-minute AI Engineer World's Fair talk covers the same twelve factors
- •Written from HumanLayer's production experience rather than a framework vendor's documentation
Who It’s For
Best For
- ✓Engineers whose agent demo works but falls over in production
- ✓Teams deciding how much of the loop to delegate to an agent framework
- ✓Tech leads who need shared vocabulary for reviewing agent architectures
Prerequisites
- •Have built at least one LLM application that uses tool calling
- •Familiarity with the original twelve-factor app methodology helps but is not required
FAQ
What is 12-Factor Agents: Principles for Building Reliable LLM Applications?
Dex Horthy's twelve principles for LLM applications that survive real customers, published as free markdown chapters with diagrams and code. Its thesis cuts against the autonomous-loop default: own your prompts, own your control flow, keep agents small, and model the whole thing as a stateless reducer you can pause and resume.
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 intermediate audience. Recommended background: Have built at least one LLM application that uses tool calling, Familiarity with the original twelve-factor app methodology helps but is not required.
How long does 12-Factor Agents: Principles for Building Reliable LLM Applications take?
Expect roughly ~2 hours to read all twelve chapters. 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: Model an agent as a stateless reducer over its own execution state; Own your prompts and control flow instead of delegating them to a framework; Unify execution state with business state so agents become pausable and resumable; Model human approval and escalation as a tool call rather than an out-of-band interrupt; Compact errors back into the context window so an agent can self-correct; Decompose one large agent into small, focused agents with narrow responsibilities; Design launch, pause and resume APIs so long-running agents survive process restarts.
Topics
Sources
This page was written from 2 sources, 1 on domains other than github.com.