12 Factor Agents: patterns for agents that reach production

Agents as software with explicit decisions

HumanLayer’s 12 Factor Agents framework starts from a pragmatic idea: a production agent usually combines deterministic logic with model steps where language, classification or tool selection add value. It does not propose eliminating traditional software or adopting a single architecture; it offers principles to make behavior controllable.

In a bounded cycle, the model proposes a structured output, the program validates the proposal and runs only permitted capabilities, and the result becomes new evidence. The system decides how to handle errors, limits, state and stop conditions.

The 12 factors, grouped by responsibility

The original guide lists these factors. Grouping them helps turn them into design decisions:

1. Interface and inputs: 1) translate natural language into structured calls; 2) own and version the prompts; 3) manage the context window.
2. Tools and flow: 4) treat calls as structured outputs; 5) unify execution and business state; 6) expose simple APIs to launch, pause and resume; 7) contact people through tools; 8) keep flow control in code.
3. Errors and scale: 9) summarize errors so the model can recover; 10) prefer small, focused agents; 11) allow triggering from different events; 12) model the agent as a stateless reducer, with explicit state outside the model.

Inner loop and outer loop

The inner loop processes bounded steps: authorized context, structured decision, deterministic validation, execution and result. The outer loop coordinates the business process: it starts tasks, persists state, applies timeouts, manages retries and decides when a person must review or resume.

Pausing should not be an improvised exception. The system can stop before a sensitive action, present the context and expected effect to a person, and resume with the decision received. Approval must correspond to a specific action and version, not to an open permission for the whole agent.

Controls that make the pattern operable

Validate each output against a schema, enforce permissions in the service that performs the operation, bound the number of steps and keep execution identifiers. Design idempotency for repeatable actions; for impactful actions, ask for explicit authorization and record who decided what.

The factors are design principles, not a security guarantee or a complete recipe. The system must be evaluated with representative scenarios, tool failures, adversarial responses, session loss and real privacy and operational requirements.