humanlayer/12-factor-agents

What this is

12-Factor Agents is a written guide, not a library, that answers one engineering question: what principles let you ship LLM-powered software that holds up in front of production customers? It builds on the structure of the classic 12 Factor Apps methodology and argues that most successful "agents" are mostly ordinary software with LLM calls inserted at carefully chosen points, rather than a prompt-plus-tools loop that runs until the model declares victory.

The material is organized as twelve independent factors, plus an appendix entry. Each factor has its own page, and the set covers topics such as converting natural language into tool calls, owning your prompts and context window, treating tools as structured outputs, unifying execution state with business state, launch/pause/resume APIs, contacting humans through tool calls, owning control flow, compacting errors into context, keeping agents small and focused, triggering from anywhere, and modeling the agent as a stateless reducer.

The intended reader is a working software engineer or technical founder who wants to add agent-like capability to an existing product incrementally, rather than adopting a full agent framework and rewriting around it. The author states the guide is mostly illustrated in TypeScript but that the ideas are language-agnostic.

How to use it

There is no install step: read the guide. Start at the README, which links every factor from the short-version list 12-Factor Agents README. A sensible first pass is the opening history section, which explains why naive agent loops stall, and then the factors that correspond to problems you currently have. Readers specifically interested in context construction are pointed straight to the third factor page on owning your context window Factor 3: Own your context window.

To go deeper rather than read, the project records a conference talk and a longer video walkthrough, both linked from the README header AI Engineer talk, deep-dive video. A discussion thread covers contributing to an npx/uvx create-12-factor-agent scaffolding effort scaffolding discussion.

Scope and constraints

The factors are guidance, not an enforcement mechanism: nothing checks whether your code follows them. The code samples are illustrative and primarily TypeScript, so readers working in Python or other languages need to translate the examples themselves.

The repository explicitly does not address MCP; the author states this as a deliberate omission. Content and images are licensed under CC BY-SA 4.0 while code is under Apache 2.0, so reuse of the prose carries attribution and share-alike obligations Apache 2.0, CC BY-SA 4.0.

HotRepo's take

The project was posted to Hacker News in April 2025 as "12-factor Agents: Patterns of reliable LLM applications" and drew 475 points and 78 comments, making that thread the main substantive discussion for the repository HN discussion. The exchange is mostly about the guide's central stance: one commenter argued models are better used as libraries than frameworks and cited a 2015 essay on library patterns comment; another suggested owning the low-level planning loop and baking in a workflow engine rather than letting the model maintain an implicit workflow comment. A question about how DSPy fits under the "own your prompts" factor drew a reply favoring the ability to open the box and edit prompts directly comment.

The guide's framing — small, modular agent concepts folded into an existing product instead of a greenfield framework rewrite — is consistent with what these readers discuss, and it is the reason the repository reads as a design reference rather than a runnable toolkit. Since 2025 it has grown to around 27,000 stars, and in the daily TypeScript ranking on 8 November 2026 it placed 16th with a modest 26 stars gained that day, a snapshot that reflects sustained visibility rather than a current surge.