12-Factor Agents
Core engineering principles for building reliable, scalable, and maintainable LLM-powered software.
- Source repo
- humanlayer/12-factor-agents
- Stars
- ★ 27k
- Last updated
- 1y ago
- License
- NOASSERTION
- Primary language
- TypeScript
- FA score
- 24/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platform
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- Typical use
- A technical founder or engineer designing a production-grade agent can refer to these principles to architect their own system, avoiding common pitfalls.
- Not a fit if
- Teams wanting a ready-to-run tool: this repo is documentation only, with no runnable code
- Developers who want a framework or API to integrate rather than implementing the principles themselves
- Python-first teams needing full Python examples; the examples are mostly TypeScript
- Source review
- 24/100 · Major gaps 8 safety controls not found
What does this agent do, and when should you use it?
12-Factor Agents is a set of guidelines inspired by the classic 12-Factor App methodology, aimed at building LLM applications that are production-ready. The repository contains detailed content for 12 core factors, covering topics like natural language to tool calls, owning your prompts, owning your context window, tools as structured outputs, unifying execution and business state, launch/pause/resume with simple APIs, contacting humans with tool calls, owning your control flow, compacting errors into context, small focused agents, triggering from anywhere, and making your agent a stateless reducer. It also includes a 'Brief History of Software' and an appendix on pre-fetching context. The content is licensed under CC BY-SA 4.0, with code under Apache 2.0, and the community is encouraged to contribute. The guide emphasizes incorporating modular concepts from agent building into existing products rather than adopting full frameworks.
The repository provides a chaptered guide (Markdown files) detailing each of the 12 factors, with design patterns, code examples (mostly TypeScript), and architectural advice. For instance, Factor 1 explains how to translate natural language into tool calls; Factor 2 stresses owning and versioning prompts; Factor 3 discusses owning and controlling the context window; Factor 4 points out that tools are just structured outputs; Factor 5 suggests unifying execution state and business state; Factor 6 recommends simple APIs for launch/pause/resume; Factor 7 covers contacting humans with tool calls; Factor 8 emphasizes owning control flow; Factor 9 advises compacting errors into the context; Factor 10 advocates small, focused agents; Factor 11 discusses triggering from anywhere to meet users where they are; Factor 12 suggests making the agent a stateless reducer. The repo contains no executable code, purely knowledge content, providing architectural guidance for LLM applications.
- A technical founder or engineer designing a production-grade agent can refer to these principles to architect their own system, avoiding common pitfalls.
- A team already using an agent framework but finding it hard to debug or extend can adopt these principles to adjust or replace the framework.
- Developers integrating LLM features into an existing product can learn how to modularly incorporate agent concepts without a full rewrite.
- An architect planning execution state management for LLM apps can learn how to unify execution and business state for reliability.
- Engineers needing to handle long-running tasks can adopt the launch/pause/resume pattern from Factor 6 and the stateless reducer design from Factor 12.
- Teams wanting human-agent collaboration can implement Factor 7's approach of contacting humans via tool calls.
How do you install or deploy this agent?
This repository is a knowledge base, not a software package, so installation is not applicable. It can be accessed directly via the GitHub page in a web browser.
How do you use this agent?
To use, browse the content/ directory for each factor file on the GitHub repository, or follow the visual navigation links in the README. You can also clone the repository locally for offline reading.
What are this agent's strengths and limitations?
- Provides actionable design patterns rather than abstract theory, with detailed explanations and code examples for each factor.
- Emphasizes modularity over full framework adoption, enabling incremental integration of LLM features into existing products.
- Framework-agnostic and language-agnostic; examples are TypeScript but concepts apply to any language.
- Community-driven, with contributions and feedback welcome, ensuring continuous evolution.
- Pure documentation, containing no runnable code or tools, requiring readers to implement principles themselves.
- No concrete codebase or API for integration; needs manual translation of principles into actual code.
- Does not mention modern standards like MCP, potentially missing some ecosystem developments.
- Examples are primarily TypeScript, which may be less friendly to Python developers, although the text notes it applies to Python as well.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| 12-Factor Agents This agent | 24 · Major gaps | Library / SDKFree | ★ 27k | 1y ago | TypeScript | — |
| Claude Code System Prompts Research | 35 · Major gaps | Library / SDK | ★ 2.6k | 6mo ago | — | Claude Code |
| LangChain & LangGraph Agent Course | 32 · Major gaps | CLIFree + model costs | ★ 1.7k | 4d ago | — | — |
| Dify | 55 · Major gaps | Self-hosted serviceFreemium | ★ 159k | today | Python | OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows the repository is primarily a principles guide with no actual code or runtime behavior. Therefore, all trust criteria are unmet: no evidence of least privilege, user confirmation, data flow transparency, sensitive data handling, dependency security, external effects, rollback, or source attribution. Deductions: these aspects are entirely absent.
Self-consistency: The 12 factors listed in README align with content files, but full content is not provided, so only partial support. Dependency availability: No dependency information provided. Failure messages: Test files show CLI has clear error messages for invalid inputs, but actual code is not provided, so only partial support. Deductions: dependency availability missing, failure messages only inferred from tests.
Audience and scenarios: README clearly targets developers building production LLM applications and provides various scenarios. Capability boundaries: Guide discusses limitations of frameworks but does not explicitly state its own boundaries. Trigger precision: Not addressed. Environment fit: Mentions TypeScript and Python but no specific environment requirements. Deductions: trigger precision missing, capability boundaries and environment fit only partially covered.
Information architecture: README provides clear structure and navigation. Install notes: Not provided. Naming stability: Factor names are consistent, but no versioning info. Examples and FAQ: Examples and links provided, but no FAQ. Known limitations: Discusses framework limitations but not its own. License: Apache 2.0 and CC BY-SA 4.0 provided. Versioning and changelog: Not provided. Maintenance responsibility: Contributors listed, but maintainers not explicit. Deductions: install notes, versioning, changelog missing, others only partially covered.
Output usability: Guide provides actionable insights but no actual code or tools. Marginal value: Provides unique perspective but no implementation. Cost-benefit: No cost analysis. Deductions: output usability and cost-benefit only partially supported, marginal value supported but not quantified.
Claim traceability: Claims in README are partially supported by links, but full evidence not provided. Cross-source corroboration: Not provided. Fact-inference separation: Guide distinguishes personal experience and general principles but not explicitly. Deductions: cross-source corroboration missing, others only partially supported.
- Not found in source: least-privilege scopingGrant only what the task needs: a dedicated account or read-only token, scoped to specific directories and repos.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: data-flow disclosureWatch which external services it contacts (proxy or firewall logs) and keep sensitive data out until you know where it goes.
- Not found in source: sensitive-data handlingUse dedicated, low-privilege, revocable API keys — never production credentials — and keep secrets out of logs.
- Not found in source: dependency securityPin versions and run a dependency audit (npm audit, pip-audit) before installing; prefer running it in a container.
- Not found in source: disclosed external effectsEstablish which external systems it writes to, sends to or changes, and verify with test accounts or repos before production.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Not found in source: verifiable attributionInstall from the official repo or registry and check the publisher and URL to avoid look-alike packages.
- The repository is primarily a principles guide with no actual code or executable product, so runtime behavior cannot be assessed.
- No installation instructions, versioning, or changelog provided, which may affect maintainability.
- Trust aspects such as dependency security and data flow transparency are entirely absent, so caution is advised.