# 12-Factor Agents — Architecture Patterns for Production LLM Software

> A practical guide to building reliable, maintainable AI agent software by applying twelve battle-tested principles from real-world deployments.

## Install

Save as a script file and run:

# 12-Factor Agents — Architecture Patterns for Production LLM Software

## Quick Use
```bash
git clone https://github.com/humanlayer/12-factor-agents.git
cd 12-factor-agents
# Browse the principles and reference implementations
cat README.md
```

## 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

---
Source: https://tokrepo.com/en/workflows/12-factor-agents-architecture-patterns-production-llm-be4b6e90
Author: Script Depot