humanlayer/12-factor-agents

12-Factor Agents is a guide, modeled after the well-known "12 Factor App" methodology for web applications, that proposes twelve concrete engineering principles for building AI-powered software that is reliable enough to deploy to real production customers. The core argument is that most successful AI agent products are not fully autonomous loops of an LLM calling tools until something works, they are mostly conventional software with AI steps embedded at precisely the right moments. The twelve factors cover the full lifecycle of building a production-grade AI agent. Several focus on controlling how information flows into the language model: own your prompts (write and version them yourself rather than relying on framework defaults), own your context window (carefully curate what the model sees rather than feeding it everything), and compact errors back into context rather than crashing. Others address architecture: keep agents small and focused on a single task, make agents stateless so they can be paused and resumed like a pure function, and treat tool calls as structured data outputs rather than magical actions. Factor 7 specifically addresses human oversight, designing the agent to contact a human through a tool call when it encounters uncertainty, rather than guessing. A developer or founder building LLM-powered features into a product, whether a coding assistant, customer support bot, or workflow automation, would use this guide to avoid common pitfalls and architectural dead ends. The content lives in Markdown files in the repository and the code examples are in TypeScript. It is published under Apache 2.0 (code) and Creative Commons BY-SA 4.0 (content).