# 12-Factor Agents — Principles for Production LLM Software

> A practical guide to building LLM-powered applications that are reliable enough for production use, covering twelve design principles for AI agent architecture.

## Install

Save as a script file and run:

# 12-Factor Agents — Principles 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 example implementations
ls content/
```

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

---
Source: https://tokrepo.com/en/workflows/asset-800fc231
Author: Script Depot