humanlayer/12-factor-agents

What are the principles we can use to build LLM-powered software that is actually good enough to put in the hands of production customers?

Summary

12-factor-agents is a design guide for building reliable, customer-facing LLM software, inspired by the 12-factor application methodology. It argues that strong agents are mostly conventional software with carefully placed LLM steps, and defines 12 principles covering prompts, context, tools, state, control flow, errors, and agent boundaries.

What it is useful for

The guide is useful when designing an LLM feature, reviewing an existing agent implementation, or deciding whether an agent framework fits a product requirement. Its central example is a contrast between an open-ended “prompt, bag of tools, loop until the goal” agent and a controlled workflow where the model produces a structured next action, deterministic code executes it, and the result is added to an explicitly managed context.

The factors also provide practical design prompts:

• Keep prompts and context construction under application ownership.
• Treat tools as structured outputs rather than opaque integrations.
• Unify execution state with business state.
• Support launching, pausing, and resuming work through simple APIs.
• Represent contact with humans as a tool call.
• Keep control flow in ordinary code and compact errors into context.
• Prefer small, focused agents and design an agent as a stateless reducer.

This makes the repository useful to teams adding focused agent behavior to an existing product rather than committing to a framework and rebuilding the application around it.

The README does not describe a plug-and-play runtime or provide installation or quick-start commands for an application. Its examples lean toward TypeScript, although the author notes that the principles apply in Python or other languages. MCP is also intentionally outside the guide’s scope.

How engineers can use it

1. Start with the README’s factor index. Read the brief history of software, then use the 12 factors as an architecture-review checklist. For context-management work, go directly to content/factor-03-own-your-context-window.md.

2. Choose one narrow workflow. Instead of opening with a general-purpose autonomous agent, identify a step where an LLM can provide useful judgment while the surrounding application retains deterministic behavior.

3. Make the LLM boundary explicit. Store the prompt separately, assemble the context deliberately, request a structured tool call, and execute that call in normal application code. Add business and execution state to the same persisted record when the workflow needs pause/resume or human involvement.

4. Apply the remaining factors during review. Check whether control flow remains inspectable, errors are compacted for the next model call, human handoffs use tool calls, and the agent has a focused responsibility.

Because no setup instructions are documented in the supplied README, engineers should use the factor pages as implementation guidance and consult the repository README for current project instructions rather than assuming there is an installable agent package.