12-Factor Agents — Principles for Production LLM Software

Introduction

12-Factor Agents is a set of design principles for building LLM-powered software that is reliable enough for production customers. Inspired by the original Twelve-Factor App methodology, it addresses the unique challenges of shipping AI agent software at scale.

What 12-Factor Agents Does

• Defines twelve actionable principles for building production-grade AI agents
• Provides reference implementations in TypeScript and Python
• Covers patterns for tool orchestration, context management, and error recovery
• Addresses real-world concerns like cost control and latency budgets
• Includes working examples that demonstrate each principle in practice

Architecture Overview

The project is organized as a content-driven guide with companion code. Each factor is a standalone principle with its own explanation and code sample. The principles cover the full lifecycle of an AI agent: from how it receives work, manages state, calls tools, handles failures, and returns results. The examples use common frameworks like LangChain and OpenAI SDKs but the principles are framework-agnostic.

Self-Hosting & Configuration

• Clone the repository and read the principles in the content directory
• Example implementations require Node.js 18+ or Python 3.10+
• Set API keys for your LLM provider (OpenAI, Anthropic, etc.) as environment variables
• Each example is self-contained with its own dependency file
• No server or database required; the guide is purely educational with runnable code

Key Features

• Framework-agnostic design principles applicable to any LLM agent stack
• Concrete code examples, not just abstract theory
• Covers failure modes unique to LLM applications (hallucination, token limits, tool errors)
• Community-driven with contributions from production AI teams
• Regularly updated as best practices evolve with the fast-moving AI landscape

Comparison with Similar Tools

• LangChain docs — framework-specific tutorials vs. universal design principles
• OpenAI Cookbook — provider-focused recipes vs. architectural guidance
• DSPy — compiler-driven optimization vs. human-readable design patterns
• CrewAI/AutoGen — opinionated frameworks vs. principles you apply to any framework

FAQ

Q: Do I need to use a specific framework to apply these principles? A: No. The principles are framework-agnostic and can be applied to any LLM agent stack, whether you use LangChain, plain SDK calls, or a custom setup.

Q: Are the code examples production-ready? A: They are reference implementations meant to illustrate each principle. Adapt them to your own codebase and requirements.

Q: How does this differ from the original 12-factor app? A: It addresses challenges unique to LLM software: non-deterministic outputs, token budgets, tool orchestration, and graceful degradation when the model fails.

Q: Is this only for chatbots? A: No. The principles apply to any LLM-powered system including code agents, data pipelines, and autonomous workflows.

Sources

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