# 12-Factor Agents — Design Principles for Production LLM Apps

> An open-source framework of principles and patterns for building reliable, production-grade LLM-powered software, with reference implementations in TypeScript.

## Install

Save as a script file and run:

# 12-Factor Agents — Design Principles for Production LLM Apps

## Quick Use
```bash
git clone https://github.com/humanlayer/12-factor-agents.git
cd 12-factor-agents
npm install
# Browse the examples directory for reference implementations
```

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


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