# 12-Factor Agents

> A framework-agnostic guide of 12 engineering principles for building reliable, production-grade LLM-powered agents, inspired by the 12 Factor App methodology.

12-Factor Agents is an open-source guide published by HumanLayer that distills practical engineering principles for building LLM-powered software reliable enough for production customers. Created by Dex Horthy and hosted on GitHub, it draws on experience evaluating agent frameworks and conversations with technical founders building AI products. The project is licensed under Apache 2.0 for code and CC BY-SA 4.0 for content, and welcomes community contributions.

## What It Is

12-Factor Agents is a reference guide — modeled after the classic [12 Factor Apps](https://12factor.net/) methodology — that defines twelve concrete engineering principles for building LLM-powered agents. Rather than prescribing a specific framework, it identifies the modular patterns that make agents reliable, scalable, and maintainable. The core argument is that most production-quality AI agents are primarily deterministic software with LLM steps inserted at key decision points, not open-ended "bag of tools" loops.

## The 12 Principles

The guide covers twelve factors organized around the full agent lifecycle:

- **Factor 1:** Natural Language to Tool Calls — translate user intent into structured actions
- **Factor 2:** Own your prompts — keep prompt logic explicit and version-controlled
- **Factor 3:** Own your context window — manage what the LLM sees at each step (also called "Context Engineering")
- **Factor 4:** Tools are just structured outputs — treat tool calls as typed data, not magic
- **Factor 5:** Unify execution state and business state — avoid split state between agent and application
- **Factor 6:** Launch/Pause/Resume with simple APIs — design for interruption and resumption
- **Factor 7:** Contact humans with tool calls — model human-in-the-loop as a first-class tool
- **Factor 8:** Own your control flow — don't cede loop logic to a framework
- **Factor 9:** Compact errors into context window — surface failures as context, not exceptions
- **Factor 10:** Small, focused agents — prefer narrow, composable agents over monolithic ones
- **Factor 11:** Trigger from anywhere — meet users where they are across channels
- **Factor 12:** Make your agent a stateless reducer — design agents as pure functions over context

## Why It Got Attention

The project was presented at the AI Engineer World's Fair (talk available on YouTube) and gained significant traction on GitHub, accumulating over 20,000 stars and 1,500 forks according to the repository metadata. The author frames the guide around a common failure pattern: builders adopt a framework, reach 70–80% quality, then discover that crossing the remaining gap requires reverse-engineering the framework's internals — often leading to a full rewrite. The guide argues that incorporating modular agent concepts into existing products is faster than greenfield framework adoption.

## Audience and Use Case

The guide targets skilled software engineers and technical founders who want to add agentic capabilities to existing products without committing to a full framework rewrite. It is written primarily in TypeScript examples but the author notes the principles apply equally to Python or any other language. The content is especially relevant for teams building customer-facing AI features where reliability and control matter more than rapid prototyping.

## Update: Active Development and Community Contributions

The repository was created in March 2025 and last pushed to in September 2025, with ongoing community contributions from over a dozen contributors. An active discussion thread exists for a planned `npx/uvx create-12-factor-agent` scaffolding CLI. The project also links to related HumanLayer work including `got-agents/agents` (OSS agents built with this methodology) and `kubechain` (a distributed agent runtime for Kubernetes).

## Features
- 12 engineering principles for production LLM agents
- Context window management (Context Engineering)
- Human-in-the-loop via tool calls
- Stateless reducer agent architecture
- Launch/Pause/Resume agent lifecycle APIs
- Small, focused agent composition
- Structured output tool call patterns
- Error compaction into context window
- Framework-agnostic principles
- TypeScript and Python compatible
- Community contributions welcome
- Apache 2.0 licensed code

## Integrations
TypeScript, Python, Airflow, Prefect, Dagster, Inngest, Windmill, BAML, OpenAI, Anthropic

## Platforms
WEB, API, CLI

## Pricing
Open Source

## Version
main

## Links
- Website: https://github.com/humanlayer/12-factor-agents
- Documentation: https://github.com/humanlayer/12-factor-agents
- Repository: https://github.com/humanlayer/12-factor-agents
- EveryDev.ai: https://www.everydev.ai/tools/12-factor-agents