# 12-factor-agents

> A written guide to twelve principles for building reliable LLM-powered software

- Repository: https://github.com/humanlayer/12-factor-agents
- Category: Learning & resource lists
- Stars: 26,835 · Forks: 2,011 · Language: TypeScript · License: not stated
- Experience: Some experience
- Page: https://ir.adyog.com/repos/humanlayer/12-factor-agents/

This is a guide, not a library. Its author, Dex of HumanLayer, tried many agent frameworks and talked to over 100 founders building AI features. They found that many products sold as agents are mostly ordinary code with LLM steps placed where they help.

The guide starts from the common agent loop. The LLM picks the next step as structured JSON, normal code runs it, the result is added to the context window, and the loop repeats until the LLM says it is done. The author says this pattern alone tends to stall at around 70-80% quality, and that getting further means reverse-engineering the framework.

The answer is twelve principles in the spirit of the 12 Factor App. They cover owning your prompts, context window and control flow, treating tools as structured output, pausing and resuming, contacting humans, and keeping agents small and focused. Each factor has its own page. Examples are mostly TypeScript, and the README says the ideas apply in Python or any other language.

## What it does

- **Twelve named factors**: Each factor is a separate page, from natural language to tool calls through to making an agent a stateless reducer.
- **Own your context window**: Factor 3 covers how to build and manage what goes into the model's context. The README points readers here first if they want context engineering.
- **Own your control flow**: Argues for writing the loop and branching logic yourself instead of handing it to a framework.
- **Pause, resume and human contact**: Describes launching, pausing and resuming agents through simple APIs, and asking humans for input through tool calls.
- **Background and talks**: Includes a short history of software, from flow charts to DAG orchestrators to agents, plus a 17-minute conference talk and a longer YouTube deep dive.

## What you could build

- Review an existing agent design against twelve concrete principles before shipping it to customers.
- Decide which parts of an agent to write yourself and which to leave to a framework.
- Restructure a prompt-and-tools loop so context, errors and state are managed in your own code.
- Design agents that pause for human approval and resume later through an API.
- Teach a team how production LLM software differs from a demo agent.

## Who it's for

Software developers building customer-facing LLM features, who should already know the basics of prompts, tool calling and at least one agent framework.

## Get started

There is nothing to install. Read the short list of twelve factors in the README, then open the factor pages that match your problem. Factor 3 is the place to start for context engineering.



Tags: agents, llm, prompt-engineering, context-engineering, best-practices