2011 年，Heroku 的工程师们发布了一份叫"12-Factor App"的文档。它不是代码，不是框架，而是一套方法论——关于如何构建可伸缩、可维护的 SaaS 应用。
这份文档后来成了云原生时代的事实标准。Docker、Kubernetes、各种微服务框架，骨子里都带着 12-Factor 的基因。
现在，有人想为 AI Agent 做同样的事。
humanlayer/12-factor-agents，21,600 星，273 次 commit。作者 Dex 写得很直接：
我试过每一个 Agent 框架——从开箱即用的 CrewAI、LangChain，到号称"极简"的 SmolAgents，再到标榜"生产级"的 LangGraph、Griptape。但大多数自称"AI Agent"的产品，其实并不那么 agentic。它们大部分是确定性代码，只是在恰当的位置撒了几把 LLM。
这话听起来刺耳，但你仔细想想，确实如此。
核心观点：好 Agent 不是"给个目标让它自己跑"
12-Factor Agents 的第一条原则就颠覆了很多人对 Agent 的认知：
Factor 1: Natural Language to Tool Calls
LLM 的核心能力不是"思考"，而是把自然语言转成结构化的工具调用。这意味着，Agent 的设计重心应该是"提供正确的工具"和"定义正确的调用格式"，而不是让 LLM 在漫无边际的自由中摸索。
Factor 8: Own your control flow（掌控你的控制流）
这条更关键。很多人写 Agent 的模式是："给个提示词、给一堆工具、循环直到完成。"12-Factor 明确指出：这不行。
真正能上生产环境的 Agent，控制流必须由开发者定义——哪些步骤是确定的、哪些步骤可以交给 LLM 决策、什么时候需要人介入、出错时怎么回退。LLM 是引擎，但方向盘必须在你手里。
12 条原则快速扫一遍
这 12 条原则涵盖了 Agent 开发的方方面面：
- Factor 1-4 讲的是"工具调用"的底层逻辑：自然语言→结构化输出→上下文管理→工具定义
- Factor 5-7 讲的是"执行状态"：如何统一管理业务状态和执行状态、如何暂停/恢复、如何引入人工干预
- Factor 8-10 讲的是"架构设计"：控制流归属、错误压缩、Agent 粒度
- Factor 11-12 讲的是"集成与部署"：从任何地方触发、把 Agent 变成无状态的 reducer
其中最实用的几条，我挑出来单独说。
Factor 3: Own your context window（掌控你的上下文窗口）
上下文窗口不是无限的。12-Factor 强调，你必须有策略地管理上下文——什么信息该保留、什么该压缩、什么该丢弃。否则，随着对话变长，LLM 的表现会断崖式下降。
Factor 7: Contact humans with tool calls（用工具调用联系人类）
这一条很实在。当 Agent 遇到不确定的情况，不应该"瞎猜"，而是应该用工具调用来请求人类介入。这听起来简单，但大多数 Agent 框架都没有把这个作为一等公民来设计。
Factor 12: Make your agent a stateless reducer（让 Agent 成为无状态的 reducer）
这可能是最具"工程师思维"的一条。把 Agent 想象成一个 reducer 函数：给它事件和当前状态，它返回新的状态。无状态意味着可以水平扩展、可以重试、可以监控。
为什么这份指南值得关注？
因为 AI Agent 开发目前最大的问题不是"技术不够强"，而是**"方法论还没形成"**。
每个人都在试、都在踩坑、都在重复发明轮子。12-Factor Agents 的价值在于，它试图把这些零散的经验系统化，变成一套可以讨论、可以迭代、可以传承的原则。
它不绑定任何框架，不推荐任何技术栈。它回答的是一个更基础的问题：当你想用 LLM 构建一个真正能用的产品时，你应该遵循哪些原则？