12 Factor Agents
StaleDescription
What are the principles we can use to build LLM-powered software that is actually good enough to put in the hands of production customers?
Key Features
- 12 core principles framework — systematic best practices from NL-to-tool-calls to stateless reducer pattern
- Own your context window (Factor 3) — build and manage LLM context yourself, not via framework black box
- Tools as structured outputs (Factor 4) — treat tool calls as structured outputs, simplify agent interaction
- Stateless reducer pattern (Factor 12) — design agents as pure function reducers for testability
- Human contact via tool calls (Factor 7) — reach humans through tool calls for Human-in-the-loop collaboration
- Compact errors into context window (Factor 9) — distill errors into context for autonomous recovery
Use Cases
💡 Evaluating and improving existing agent framework architecture
💡 Architecture reference for building production-grade LLM applications from scratch
💡 Understanding why most agent frameworks are unsuitable for production
💡 Designing testable, maintainable, and scalable agent systems
💡 Implementing Human-in-the-loop enterprise agent workflows
Strengths & Limitations
✅ Strengths
- • High community interest (25.7k stars)
- • Responsive to issues, low backlog
⚠️ Limitations
- • No updates in over 11 months
- • No clear open-source license
Categories
Quick Start
git clone https://github.com/humanlayer/12-factor-agents.git
cd 12-factor-agents
# Read the core principles
cat content/factor-01-natural-language-to-tool-calls.md
cat content/factor-03-own-your-context-window.md
cat content/factor-12-stateless-reducer.md
# Build your own agent following the principles
# 1. Use natural language to tool calls pattern
# 2. Own your context window
# 3. Design agent as a stateless reducer