12-Factor Agents

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 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).