12-Factor Agents — Architecture Patterns for Production LLM Software

Introduction

12-Factor Agents adapts the proven 12-factor methodology to LLM-powered applications. It provides a set of architectural principles that help teams build AI agent software reliable enough for production customers, addressing common pitfalls like brittle prompt chains, uncontrollable loops, and opaque failure modes.

What 12-Factor Agents Does

• Defines twelve guiding principles for structuring LLM-powered software
• Provides reference implementations in TypeScript and Python
• Covers patterns for tool orchestration, context management, and error recovery
• Addresses real-world concerns like cost control, latency, and observability
• Offers anti-patterns to avoid when building agentic workflows

Architecture Overview

The framework is organized around twelve principles that span the full lifecycle of an LLM application: from how prompts are managed and context is composed, to how tool calls are dispatched and failures are handled. Each principle includes a rationale, concrete examples, and code samples showing both the recommended approach and common mistakes.

Self-Hosting & Configuration

• Clone the repository and explore principle-by-principle documentation
• Reference implementations require Node.js 18+ or Python 3.10+
• No external service dependencies for reading the guide itself
• Example agents can be configured with any OpenAI-compatible API endpoint
• Each principle is self-contained and can be adopted incrementally

Key Features

• Battle-tested patterns derived from real production agent deployments
• Language-agnostic principles with TypeScript and Python examples
• Covers the full spectrum from simple chatbots to complex multi-step agents
• Emphasizes deterministic control flow over autonomous agent loops
• Designed for teams shipping LLM software to paying customers

Comparison with Similar Tools

• LangChain — provides abstractions and integrations; 12-Factor Agents provides architectural principles that apply regardless of framework
• DSPy — focuses on optimizing prompt pipelines; 12-Factor Agents covers broader system design concerns
• CrewAI — offers multi-agent orchestration; 12-Factor Agents argues for simpler, more controllable patterns
• AutoGen — enables autonomous agent conversations; 12-Factor Agents favors deterministic workflows
• Semantic Kernel — Microsoft SDK for LLM apps; 12-Factor Agents is framework-agnostic guidance

FAQ

Q: Do I need to adopt all twelve factors at once? A: No. Each principle is independent and can be adopted incrementally based on your application's maturity.

Q: Is this a framework or library I install? A: Neither. It is an architectural guide with reference implementations. You apply the principles in your own codebase.

Q: Does it work with models other than OpenAI? A: Yes. The principles are model-agnostic and apply to any LLM provider.

Q: How does this compare to the original 12-factor app methodology? A: It is inspired by the same philosophy of distilling production experience into reusable principles, but the twelve factors themselves are specific to LLM applications.

Sources

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