12 principles. That's the core of the 12-Factor Agents manifesto, a compact checklist designed to take LLM systems from the 70-80 percent demo quality many teams reach to customer-ready production. The guidance lives in the humanlayer/12-factor-agents GitHub repository and was distilled from interviews with more than 100 founders and engineering teams. Start by picking one high-pain workflow, then follow the sequence: own prompts, output typed JSON, make steps stateless, curate context and add suspension points for human review.

Here's the short answer up front: the single best move an engineering team can make is to treat agents as software and to build them with the same engineering discipline you apply to any production system. That framing isn't rhetorical. It's the explicit thesis Dexter Horthy set out when he framed the 12-Factor Agents material, and it's the practical lesson drawn from interviews with more than 100 founders and engineering teams whose work fed the repository.

1. Design and scope: pick a thesis, own prompts, and keep agents small

1. Start with a production thesis and pick one high-pain workflow to fix. Multiple practitioner accounts that fed the 12-Factor synthesis converge on this first move. The advice is simple and specific: don't build a single general-purpose agent. Pick a narrowly scoped problem where customers feel real pain, and design an agent whose end-to-end responsibility maps to that problem. Teams that shipped successfully split work into micro-agents with narrow responsibilities. Typical micro-agents handle a few steps each, and are easy to test and observe.

Worked example: instead of a single agent that both understands customer intent and executes external actions, split the job into an intent classifier, a retriever for data, an action executor and a response generator. Each agent is limited to roughly three to ten steps so it remains debuggable.

2. Own your prompts and treat JSON extraction as the foundation. The authors of the manifesto place prompt engineering under explicit developer control rather than leaving it hidden inside a framework. The recommended pattern is prompt leads to typed output, then deterministic code routes and executes that output. In practice teams make the core LLM responsibility structured output generation: translate natural language into typed, machine-readable data such as JSON that downstream code validates and runs. The pattern reads: prompt, typed output, switch or routing logic, function execution.

Thing is, worked example: write prompts that ask the model to return a strict JSON object containing fields like intent, parameters and confidence. Keep those prompts in version control and pair them with schema validators so the runtime never accepts freeform text as a command.

3. Keep agents small and focused, not monolithic. The guidance repeats a clear operational rule. Small, focused agents produce more predictable outcomes than monolithic agents that try to do everything. Design each agent around a single vertical of work and coordinate across agents with clear contracts and typed messages. That narrowness lowers failure modes and narrows the testing surface.

2. Runtime and observability: stateless steps, context curation, and error hygiene

4. Own the control flow and adopt a stateless reducer design. Production agents separate execution state from business state and implement each agent step as a pure function. Given an input state, return an output state. This stateless approach enables pause, resume and horizontal scaling because the runtime doesn't depend on in-process memory. The recommended architecture passes a single serialisable state object through each step rather than letting the agent accumulate state internally. That design also makes retries and deterministic replay far simpler.

Worked example: represent the execution state as a JSON object held in a canonical execution store. Each step consumes that object and returns a new version. If a step fails, you can re-run the same input state and reproduce the behavior.

5. Curate and pre-fetch context, and keep the LLM attention budget explicit. The framework treats context window management as the linchpin. Analysis in the sources points to a "dumb zone" that appears when the context window fills and model recall and reasoning degrade. The practical remedy is to pre-fetch relevant documents and metadata before execution begins, trim or compress prior interactions, and keep only high-fidelity items in the active prompt. The manifesto treats pre-fetching as an appendix factor that deserves parity with other factors because fetching context mid-execution reduces determinism and adds flakiness.

Worked example: before running an invoice-processing agent, load the relevant invoice PDF, customer account record and a condensed policy summary into the execution context. Strip or compress chat history to a short decision trail instead of sending the entire conversation.

6. Separate business state from execution state and unify storage semantics. The guidance insists systems should avoid dual, unsynchronised state systems. Business entities, user records and durable events should live in the application’s canonical stores. Execution state, the transient variables needed for a single task or to resume after an interrupt, should be serialisable and small. That separation reduces race conditions and simplifies audits and observability.

7. Treat tool use as code and structure tool calls. The manifesto reframes tools from an opaque bag of APIs to typed operations the agent calls by name with structured parameters. That improves testability because agent outputs are validated against a schema before execution. When tool calls fail, teams map failures to compact, structured error objects that can be re-queued, transformed into alternative attempts, or surfaced to operators.

Mastheads

8. Implement explicit error handling and compact error context.

Rather than dumping verbose logs into the model context, successful teams compact failure signals into minimal diagnostics the model can reason over in the next step. The aim is to preserve just enough signal to inform corrective action without overwhelming the attention budget.

Worked example: if a payment API returns an authentication error, translate the raw response into a short error object such as {"type":"auth","code":401,"hint":"refresh-token"} and feed only that into subsequent model prompts.

3. Integration, triggers, human-in-the-loop and measurement

9. Support triggers and multi-channel interfaces. Agents should be triggerable from webhooks, cron, user actions, email, chat and other external events. Designs that limit the activation surface to a single channel impede adoption. Because agents are composed of deterministic code with LLM decision points, teams should normalise incoming triggers into a canonical task representation before running the agent pipeline.

Worked example: normalise a chat command, an email, and a webhook into a canonical task object with fields for requestor, payload and priority, then feed that object to the same agent stack so behaviour remains consistent regardless of the channel.

10. Make human integration a first-class capability. Human handoffs aren't an edge case. Teams that succeeded made contacting humans and exposing tool calls to operators an explicit, supported operation. The recommended pattern is for the LLM to produce a structured tool call and then require a controlled execution gate where a human can inspect, modify, approve or reject the call. Human review points should be suspendable and resumable without losing execution context.

Worked example: an agent proposes a refund. The agent outputs a structured action {"action":"refund","amount":350.00,"currency":"AUD"}. The runtime pauses, an operator reviews the payload, and then approves or rejects without re-running earlier steps.

11. Make suspension, pause and resume a core operational feature. Production-quality agents must support suspension points where operators can inspect intermediate state and resume execution without losing determinism. Stateless reducers plus serialisable execution state make this possible. Teams reported that pause and resume at scale materially reduced catastrophic errors and made audits straightforward.

12. Measure goal completion and engineer where models fail. The framework’s origin story includes a common empirical observation: many teams reach 70-80 percent functionality quickly using frameworks and off-the-shelf stacks, then stall. The recommended response is to instrument goal completion metrics and concentrate engineering effort on the bleeding edge cases where the model almost succeeds but requires deterministic code or better context curation. This sources use enterprise analyses and industry estimates showing high failure rates for AI projects that never reach production to justify focusing scarce engineering time on the last mile.

Worked example: track a goal completion metric such as "task success rate within three attempts". Use that signal to decide whether to invest in improved prompts, additional deterministic checks, or a human approval gate for specific failure modes.

Cross-cutting engineering practices. The 12-Factor material repeats several tactical prescriptions across the factors. Keep prompt text under version control. Use schema validation for LLM outputs. Limit model context to the most relevant items and prefetch documents. Implement deterministic routing logic that consumes structured outputs. Make tool execution idempotent and observable. Design a thin orchestration layer that enforces retries, timeouts and human approval gates. The sources make an explicit case for preferring a small, custom orchestration layer rather than adopting frameworks that hide prompt, control flow or state semantics.

Community provenance and evidence. The 12-Factor Agents guidance is documented in the humanlayer/12-factor-agents GitHub repository and discussed across practitioner channels and conference talks. The repository was framed explicitly as a synthesis of interviews with production teams. Dexter Horthy, the author of the original material, presented the framework in a 2025 MLOps Community talk where he outlined the failure pattern the factors address. Those community discussions are part of why the checklist reads like a playbook that teams used in 2025 and 2026 to push LLM systems across the finish line.

How to get started, step by step. The sources are prescriptive about execution order. First, pick your single highest-pain workflow. Second, own the prompts and convert outputs to structured JSON validated against schemas. Third, enforce stateless step functions and pass a single serialisable execution state through the pipeline. Fourth, curate and prefetch context so the model sees only what matters. Fifth, add a suspension point for human review. Finally, instrument goal completion and iterate on the failure modes that matter most.

Operational trade-offs. The manifesto doesn't promise that following the 12 factors will eliminate all failures. What it does promise is a reproducible engineering sequence that narrows where engineering effort yields the largest returns: deterministic routing, tight schemas, context curation and human gates. Those are the places teams reported moving from 70-80 percent demo quality to reliable customer service.

Practical checklist to carry to a stand-up meeting. First, pick the agent and name its production thesis. Second, identify the exact JSON schema you expect the model to output. Third, design the serialisable execution state and decide where it will be stored. Fourth, list the context items you must prefetch. Fifth, set the human approval gate and define the resume path. Sixth, add metrics for goal completion. Do these in order and iterate.

Quick summary

1. The 12-Factor Agents manifesto, published in the humanlayer/12-factor-agents GitHub repository and presented by Dexter Horthy in a 2025 MLOps Community talk, condenses practical moves teams used in 2025 and 2026 to reach production.

2. Start with one narrowly scoped agent, own prompts, and require typed, machine-readable outputs such as JSON.

3. Make steps stateless, prefetch and curate context, expose human review gates, and instrument goal completion to focus engineering on the last-mile failures.

Related Articles

In short: - Pick one high-pain workflow and scope the agent narrowly so it's testable and debuggable. - Own your prompts in version control and require structured, typed JSON outputs that downstream code validates. - Implement stateless step functions, curate context before execution, and add a suspendable human review gate. Start with one agent, own the prompts and treat agents as software. That single piece of discipline is what turns demos into customer-ready systems.

This article was created with AI assistance.