The 12-Factor App, Reborn for AI Agents: What Changes When the App Is a Harness

TL;DR

The 12-Factor App, written by Adam Wiggins and the Heroku team around 2011, is the checklist that taught a generation how to build cloud software that survives contact with production: config in the environment, stateless processes, logs as streams, strict build/release/run separation. In 2025 Dex Horthy of HumanLayer published 12-Factor Agents, a deliberate remix of the same idea for LLM-powered software. The punchline that matters for DevOps: a production agent is not a magic autonomous being, it is mostly ordinary, well-engineered software with the model called at a few key points. The 12 factors still apply. They just get new names like "own your context window" and "make your agent a stateless reducer."

What the original 12 factors were for

The 12-Factor App was a reaction to a specific pain: apps that ran fine on a developer laptop and fell apart in the cloud. Its rules made software portable and disposable. Keep one codebase in version control. Declare dependencies explicitly. Push config into the environment instead of baking it into the build. Treat databases and queues as attached resources you can swap. Run stateless processes you can kill and restart at will. Emit logs as a stream and let the platform route them. The reward was continuous deployment, horizontal scaling, and no snowflake servers.

None of that went away. If your agent's API service is not itself 12-factor in the original sense, you have a deployment problem before you have an AI problem. The agentic factors sit on top, not instead.

What changes when an agent and a harness are involved

The new variable is the LLM and the loop around it, usually called the harness: the code that builds the prompt, calls the model, parses the response into an action, runs the tool, folds the result back in, and decides whether to continue. Traditionally your control flow was deterministic code. Now part of it is a probabilistic token generator. The 12-Factor Agents framework is mostly about keeping the deterministic parts deterministic and giving you, not a framework, ownership of the risky parts.

A few of the mappings are worth spelling out:

• Config in the environment becomes "own your context window." The prompt and the context are the agent's real runtime config. Traditionally you tuned behavior with env vars and feature flags. Now you tune it by deciding, explicitly, what tokens go into the window: which instructions, which history, which tool results. Hand that to a black-box framework and you have lost control of your most important config surface.
• Stateless processes become "make your agent a stateless reducer." The old rule said do not keep state in the process, keep it in a backing store so any worker can handle any request. The agentic version is the same shape: the agent is a pure function of (state, new event) to (next state). Persist the conversation and execution state outside the agent, and any worker can resume any run. That is what makes launch, pause, and resume with simple APIs possible.
• Backing services become "tools are just structured outputs." A 12-factor app treats a database as a swappable attached resource behind a clean interface. A 12-factor agent treats every tool call as plain structured data (typically JSON) that your own code validates and executes. The model proposes, your deterministic code disposes.
• Logs as event streams become "compact errors into context." You still stream events, but now some of them go back into the model. When a tool fails, you do not dump a stack trace, you compact the error into a short signal the model can actually act on, and you keep control of how many failures it sees before you escalate.
• Admin one-off processes become "contact humans with tool calls." The old escape hatch was an operator running a one-off script. The new one is the agent pausing to ask a human for approval or input, modeled as just another tool call, so human-in-the-loop is a first-class step rather than a bolt-on.

What this means for DevOps

If you operate agents, the factors translate into concrete pipeline changes:

• Prompts are code. Version-control every prompt and template, review them in pull requests, and deploy them through build/release/run like any other artifact. No opaque prompt library you cannot diff.
• Evals are tests. Dev/prod parity in the original was about matching environments. For agents it extends to behavior: you need an eval suite in CI that catches a regression when a model or prompt changes, because "it compiles" tells you nothing about whether it still reasons correctly.
• Observability includes the reasoning. Logs as event streams now means capturing the full trace: prompt, tokens, tool calls, and outcomes, so a bad run is reproducible. The context window is the new stack trace.
• Rollback covers models and prompts, not just code. A model version bump is a deploy. Treat it like one, with the ability to pin and revert.
• Keep agents small and focused. The framework's blunt advice is fewer than roughly 100 tools and under about 20 steps per agent. Compose small agents the way you compose small services, rather than building one omniscient loop.

The honest caveats

12-Factor Agents is a manifesto, not a framework or an SDK. It is language-agnostic guidance, and like the original it is opinionated, not gospel. Some teams will reasonably break a factor when a real constraint demands it. The numbers (under 100 tools, under 20 steps) are rules of thumb from one team's production experience, not laws, so measure on your own workloads. And none of it removes the underlying uncertainty: you are still wrapping a probabilistic component, and good engineering shrinks the blast radius rather than eliminating it. The point is not that agents are easy. It is that they are software, and decades of hard-won software discipline still apply.

Key Takeaways

• The 12-Factor App (Heroku, ~2011) made cloud software portable and disposable. Those rules still apply to the service your agent runs in.
• 12-Factor Agents (Dex Horthy, HumanLayer, 2025) remaps the same discipline onto LLM software: own your prompts, own your context window, treat tools as structured outputs.
• A reliable agent is mostly deterministic software wrapping one probabilistic call in a harness you control, not an autonomous black box.
• The cleanest mental model is the stateless reducer: agent state lives outside the process so any worker can launch, pause, and resume a run.
• For DevOps it means prompts are code, evals are tests, traces are the new logs, and a model bump is a deploy you can roll back.

Sources: 12factor.net (The Twelve-Factor App), humanlayer/12-factor-agents (GitHub), HumanLayer: 12-Factor Agents