Production agents are mostly code, not prompt loops

What it does

This repository lays out twelve engineering principles for building LLM-powered applications that can survive contact with production customers. It treats an agent not as an open-ended reasoning loop, but as deterministic software where LLM calls are deliberate, bounded transitions. Each factor covers a specific failure mode—from context-window bloat to state management—with the blunt practicality of an incident post-mortem.

The interesting bit

The author argues that the hype-cycle image of an agent—“here’s your prompt, here’s a bag of tools, loop until goal”—is largely fiction. The systems actually handling real traffic are directed graphs with LLM-powered edges, and the twelve factors are designed to keep them debuggable, pausable, and framework-agnostic.

Key highlights

• Twelve specific factors ranging from owning your prompts and context window to treating human contact as just another tool call
• Explicit pushback against black-box orchestration frameworks; the author notes that most strong founders roll their own stack
• Agents modeled as stateless reducers over a context window, with execution state unified to business state
• Guidance to keep agents small and focused rather than monolithic
• Content is CC BY-SA licensed, code is Apache 2.0

Caveats

• This is a methodology repository, not an installable framework—though there is an open discussion about a future create-12-factor-agent CLI
• The advice is opinionated and explicitly positions itself against popular frameworks like LangChain and LangGraph

Verdict

Read this if you’re shipping LLM features to real users and need a sanity check on architecture. Skip it if you are hunting for a drop-in library or a quick-start notebook.