12-Factor Agents — Design Principles for Production LLM Apps

Introduction

12-Factor Agents adapts the classic 12-Factor App methodology for LLM-powered software. It provides a set of principles, patterns, and reference implementations for building AI agents that are reliable enough for production customer-facing use.

What 12-Factor Agents Does

• Defines 12 principles for building production-grade LLM applications
• Provides reference implementations in TypeScript for each principle
• Includes patterns for context management, memory, and tool orchestration
• Offers guidance on error handling, observability, and human-in-the-loop design
• Supplies runnable example agents demonstrating each principle

Architecture Overview

The project is organized as a documentation-first framework with companion code. Each of the 12 factors is documented with rationale and accompanied by a reference implementation. The examples use TypeScript and demonstrate patterns like deterministic routing, structured context windows, human approval gates, and graceful degradation.

Self-Hosting & Configuration

• Clone the repository and install dependencies
• Browse the docs directory for principle documentation
• Run individual examples with their own setup instructions
• Adapt reference implementations to your agent architecture
• No runtime or server required: it is a learning and reference framework

Key Features

• Actionable principles derived from real production agent deployments
• TypeScript reference implementations for every factor
• Patterns for context window management and token budgeting
• Human-in-the-loop approval gate design patterns
• Observability and debugging guidance for agent systems

Comparison with Similar Tools

• LangChain — framework with abstractions; 12-Factor focuses on principles over libraries
• CrewAI — multi-agent framework; 12-Factor is design guidance, not a runtime
• OpenAI Agents SDK — SDK; 12-Factor teaches patterns applicable to any SDK
• Semantic Kernel — enterprise SDK; 12-Factor is lightweight and vendor-neutral

FAQ

Q: Is this a library I install? A: No. It is a set of principles and reference code. You apply the patterns to your own agent architecture.

Q: Do I need to follow all 12 factors? A: No. Each factor is independent. Adopt the ones that address your specific production challenges.

Q: What language are the examples in? A: TypeScript. The principles themselves are language-agnostic.

Q: Who created this? A: The HumanLayer team, based on experience building production agent systems with human approval workflows.

Sources

• https://github.com/humanlayer/12-factor-agents