12-Factor Agents Explained

Why “Just Use LangChain” Stopped Working #

AI Agent Skills Explained: The 2026 Developer’’s Guide to Production-Grade Agent Workflows • TradingAgents: The 82,000-Star LLM Multi-Agent Trading Framework — A Practical 2026 Guide Every engineer who has shipped an LLM-powered feature to real users hits the same wall: the prototype works beautifully in a notebook, then collapses the moment a paying customer hits it from a different angle. The agent hallucinates a tool call, the context window blows up halfway through a session, errors silently swallow themselves, retries spin forever, and the postmortem reveals that nobody — not even the engineer who built it — actually understands what the agent was doing when it failed.

The agentic AI ecosystem in 2025–2026 produced dozens of frameworks promising to “make agents production-ready” — LangChain, LangGraph, CrewAI, AutoGen, OpenAI Agents SDK, Pydantic AI, the list goes on. Each one solves the demo problem (compose tool calls, route between sub-agents). Almost none of them solve the production problem (predictable behavior under unexpected inputs, observable failure modes, recoverable sessions).

12-Factor Agents (GitHub: humanlayer/12-factor-agents, 22,000+ stars as of May 2026) is Dex Horthy’s and HumanLayer’s answer to the gap. Modeled on Heroku’s 12-Factor App methodology from 2011, it is a methodology — not a framework, not a runtime, not a SaaS — for thinking about LLM-powered software that real customers will use.

Apache 2.0 for the code samples, CC BY-SA 4.0 for the prose. 273 commits and counting, mostly TypeScript with Python and Jupyter examples for accessibility.

核心洞察框架抽象出了代理崩溃时实际上最重要的四件事：1. 发送的提示。 #

2. 处于活动状态的上下文窗口。
3. 决定下一步做什么的控制流。
4. **需要在崩溃中幸存下来的执行状态。**12-Factor Agents 逐行认为，“其中的每一个"都应该是您自己的代码，而不是框架隐藏的魔法。 结果是，当凌晨 3 点发生事件时，您的存储库中的代码会增多，而祈祷的次数也会减少。以下是所有十二个因素，以及每个因素在实践中的实际含义。—

12 个因素### 1. 自然语言到工具调用法学硕士的工作是将用户意图转化为结构化工具调用，仅此而已。 不要要求法学硕士"做这件事”。 要求它发出"描述"执行该操作的 JSON，然后让确定性代码执行它。 这一单一约束消除了整个类别的幻觉驱动事件。### 2. 拥有你的提示提示是代码。 它们属于您的存储库、版本控制、代码审查。 埋藏在框架的提示库中的模板是技术债务，等待着您升级时默默地改变行为。 如果您的代理的行为取决于某个字符串，那么该字符串就属于您。### 3. 拥有你的上下文窗口当前模型上下文中的消息集是行为的最大决定因素。 自动总结、自动修剪或自动注入内存的框架非常好，但事实并非如此。 构建您自己的上下文组装逻辑。 您应该能够打印进入每个 LLM 调用的确切消息数组。### 4. 工具只是结构化输出"工具"并不是一个神奇的 Function 对象——它是一个约束 LLM 输出的 JSON 模式。 一旦你内化了这一点，你就可以构建法学硕士实际上不会调用的"工具"：状态转换、决策分支、升级请求。 任何需要法学硕士致力于塑造的东西都可以是工具。### 5.统一执行状态和业务状态您的代理有两个状态机：一个用于"我在对话中的位置"，另一个用于"用户的订单/票据/项目在做什么"。 12-Factor Agents 认为这些应该是相同的状态机。 将它们分开是"代理认为已完成但订单仍待处理"错误的最常见来源。### 6. 使用简单的 API 启动/暂停/恢复您的代理必须能够在运行中暂停并稍后恢复 - 可能在另一台机器上，可能在人工批准之后。 这意味着整个会话状态必须是可序列化的。 没有局部变量闭包的魔力。 没有"LLM 客户端对象使对话在内存中保持活动状态"。 普通数据，写入持久的地方。### 7. 通过工具调用与人类联系当代理需要人工输入（批准、丢失信息、升级）时，它应该发出工具调用，而不是停止运行。 工具调用进入人类监控的同一队列/UI/收件箱。 与因素 4 相同的模式，适用于人机交互案例。 HumanLayer的产品就是这一原则的产品化版本。### 8. 拥有你的控制流决定"调用LLM→运行工具→再次调用LLM→检查是否完成→再次调用LLM"的for循环是每个代理的核心。 隐藏它的框架（“只需让出，我们将处理循环”）剥夺了您在您需要的地方添加自定义逻辑（速率限制、预算上限、人工检查点、重试）的能力。 编写循环。 一共二十行。### 9. 将错误压缩到上下文窗口中当工具调用失败时，正确的做法是将"简短的、结构化的"错误消息反馈给 LLM 的下一轮并让它做出反应。 不崩溃。 不要默默地重试。 不要记录并祈祷。 200 个字符的"TOOL_FAILED：来自 /api/orders 的 HTTP 503，有效负载太大"足以让 LLM 做出合理的下一步行动 - 后退，尝试较小的有效负载，升级为人类。### 10. 小型、专注的代理一个"包办一切"的巨型代理是一场调试噩梦。 十二个小代理，每个代理有三种工具和一项工作，是可测试和可恢复的。 该模式与微服务相匹配，具有相同的权衡：更多的协调开销，更好的故障隔离。### 11. 随时随地触发，随时随地与用户见面代理的输入不应耦合到单个通道。 Slack 消息、电子邮件、Web 表单、GitHub 问题、Telegram 机器人、cron 作业 — 都是同一个代理。 这需要因素 2（拥有您的提示）和因素 5（统一状态）首先是可靠的，但回报是能够添加新的输入源而无需重写代理。### 12.让你的代理成为无状态Reducer代理是一个纯函数：“状态，事件→新状态，输出”。 没有隐藏突变。 没有"代理记得，因为它有 self.history 属性。" 影响输出的一切都在输入中。 这是让其他一切成为可能的因素——没有它，因素 5、6 和 10 都是理想的。— #

将其应用于实际堆栈### 至 Claude Code 工作流程Claude Code 已在设计上实现了因素 1、4 和 7 — 工具调用是结构化输出，MCP 服务器添加了人机交互，并且工具目录归您所有（您项目的 MCP 配置）。 需要注意的因素是 2（系统提示是您通过 CLAUDE.md 自定义的）、3（上下文窗口组件部分是 Claude 的，但 pagefind/CodeGraph 集成可以让您塑造它）和 9（当工具返回错误时，确保其紧凑且结构化）。### 至 MCP-Based 代理堆栈MCP 确定了因素 4（通过标准化协议作为结构化输出的工具），并帮助解决了因素 11（任何 MCP 感知客户端都可以驱动任何 MCP 服务器）。 MCP 本身对因素 5、6、8 和 12 保持沉默——这些因素是你必须在 MCP 之上构建的。### 到 Hermes Agent / OpenCode / 自定义堆栈这些可以让您在因素 1、4 和 8（内置代理循环、结构化工具调用）方面取得领先。 您仍然需要携带自己的因素 2（提示）、因素 3（上下文塑造）、因素 5-6（状态持久性）和因素 12（无状态）。— #

12 因素代理商与主流营销框架的不同之处宣言中的一些原则强烈反对"使用我们的框架，忘记细节"的主张：- 因素 2 与提示库：大多数代理框架都附带提示库。 12-Factor 说：将提示复制到您的存储库中，然后它们就是您的了。 #

• 因素 3 与自动记忆：框架喜欢提供自动记忆（“开箱即用的 RAG”）。 12-Factor 说：这是"代理为什么要这样做？“的最大来源。 谜团。 自己构建组件。
• 因素 8 与代理运行时：隐藏循环的托管运行时很方便，直到您需要注入自定义逻辑。 12-Factor 说：编写你自己的循环，它很小。这不是与框架的斗争——而是与"隐藏太多"的框架的斗争。 使用框架作为库，而不是黑匣子。—

12 因素代理不是什么设定期望：- 不是运行时。 没有"pip install December-factor-agents”。 它是散文、例子和模式。 #

• 不是单一语言的事情。 示例是 TypeScript 和 Python，但原理与语言无关。
• 不是宗教。 某些因素（尤其是 10 个 - 小型集中代理）涉及true正的权衡。 宣言对此很诚实。
• 未完成。 273 次提交并且还在不断增加。 开放的问题和讨论积极地迭代措辞。—

谁应该阅读本文是的，请从头到尾阅读，如果您： #

• 正在向付费客户提供（或即将提供）LLM 支持的功能。
• 在过去 60 天内调试过"但它在演示中有效"代理事件。
• 正在手动滚动代理循环和采用 LangGraph/CrewAI/Agents SDK 之间进行选择。
• 正在进行 像 Cursor 与 Claude Code 这样的供应商比较，并想要一份"生产就绪"实际含义的清单。如果您符合以下条件，则可能会略读：
• 仍处于"第一特工"演示阶段。 （阅读因素 1 和因素 2，稍后再回来。）
• 仅使用托管无代码平台（n8n、Zapier），无需自行编写代理循环。—

判决《12-Factor Agents》成为 2026 年 LLM 软件被引用次数最多的宣言，原因是：它阐述了过去两年运输生产代理的工程师独立得出的模式。 Heroku 的 12 因素并行并不自命不凡——两个文档都规定了一旦true正的用户依赖它，什么就不再是可选的。宣言推动的一个最大的思维转变：代理就是软件，而软件需要被运行它的团队理解。 掩盖该契约的框架是技术债务，而不是生产力。将 12 个因素与 代币高效符号层（如 CodeGraph）、具有成本意识的 LLM 代理（如 rtk）和 统一 CLI 控制平面（如 CC）相结合 Switch，您就拥有了 2026 年生产 AI 堆栈的架构骨干。### 制作代理实际居住的地方这 12 个因素描述了生产代理的"样子"； 你仍然需要它运行的地方。 两个值得捆绑的基础设施选项：- 用于协调器的 VPS — 当自托管基础设施不稳定时，因素 4（“支持服务”）最常中断。 HTStack 是香港 IDC dibi8 本身运行生产的亚洲延迟低于 50 毫秒。- 早期部署的云信用 — 如果您在承诺某个区域之前证明 12 因素架构，DigitalOcean 将为新帐户提供 200 美元的 60 天信用额度，足以运行多因素代理原型几周。> 附属披露：通过这些链接注册，dibi8 会收到少量佣金，无需您支付额外费用。 我们仅列出适合文章主题的工具，而不列出付费展示位置。—GitHub： humanlayer/12-factor-agents · 许可证：Apache 2.0（代码）/ CC BY-SA 4.0（内容） · 星星：22K+ · 作者：Dex Horthy / HumanLayer #

参考文献和来源- 12 因子药剂 #

• LangChain
• LangGraph
• CrewAI
• AutoGen
• OpenAI Agents SDK
• Pydantic AI
• 模型上下文协议（MCP）