背景：为什么我要聊这个项目
2025年3月，一个叫 Dex 的开发者（HumanLayer 创始人）在 GitHub 上发了一个项目，叫 12-Factor Agents。短短几个月，19,400 颗星，1,474 个 Fork。
这个数字什么概念？比同期的 LangChain 官方 repo 增长还快。
它不是框架，不是代码库，是一套构建生产级 LLM 应用的工程原则。灵感来自 Heroku 的经典 12-Factor App。
核心问题是这个：
什么样的 LLM 应用，才真正值得放到用户手里？
核心立场：Agent 其实大部分是软件
Dex 观察到一个反直觉的现象：
大多数标榜自己是"AI Agent"的产品，其实大部分是确定性代码，只是在关键节点嵌入了 LLM，让体验变得"神奇"。
好的 Agent 不是"给你一个 prompt + 一袋工具 → 循环到天荒地老"这个模式。
好的 Agent 是：大部分是软件，只在真正需要推理的地方，让 LLM 做决策。
这个立场，值 19,400 颗星。
12条原则，核心是这3条
项目里有 12 条原则，但真正构成骨架的只有 3 条：
Factor 3：Own Your Context Window
上下文工程，比模型选择重要。
LLM 是无状态的函数：输入 → 输出。想得到好输出，就得给好输入。
"好输入"包括：
- Prompt 和指令
- RAG 检索来的外部数据
- 工具调用历史
- 跨会话的记忆
- 关于输出格式的说明
文档里有一句很扎心的话："At any given point, your input to an LLM is 'here's what's happened so far, what's the next step'"。
这就是 Agent 的全部本质。
更重要的是：文档建议你不用标准 message 格式，可以自定义 context 格式，把整个 context window 压成一个 custom user message， token 效率和注意力分配由你控制。
Factor 8：Own Your Control Flow
控制流是软件的责任，不是 LLM 的。
Agent 框架最大的诱惑，是让 LLM 决定下一步做什么、怎么循环。但这个模式的失败率在生产环境高得离谱。
12-Factor Agents 提倡的是：LLM 只负责"决策"，软件负责"控制"。
while True:
next_step = await llm.determine_next_step(context)
# 这里的判断全是软件逻辑
if next_step.intent == 'request_clarification':
await send_to_human(next_step)
break # 退出循环，等待人类响应
elif next_step.intent == 'fetch_data':
result = await execute(next_step)
context.append(result)
continue # 同步步骤，继续循环
elif next_step.intent == 'high_stakes_action':
await request_approval(next_step)
break # 高风险操作，退出等审批
LLM 给出 intent，软件决定怎么处理。这才是合理的分工。
Factor 12：Make Your Agent a Stateless Reducer
Agent 是无状态 reducer：输入 thread → 输出 event → 追加到 thread。
这条原则把整个 Agent 架构推到最干净的形式：
- 状态 = thread（一个有序的事件列表）
- Agent = pure function: thread → event
- Thread 可序列化、可恢复、可 fork
这就是为什么 Factor 5 强调 unify execution state and business state：执行状态和业务状态不需要分开管理，thread 就是唯一真相源。
在 2026 年的今天，还有意义吗？
核心工程原则依然正确。
- 上下文工程 > 模型调参 ✓
- 控制流归软件 ✓
- 小而专注的 Agent（3-20步）✓
- Thread as source of truth ✓
- Compact errors，不要盲目重试 ✓
需要自己补全的。
- MCP：文档写于 MCP 出现之前，README 直言 "I'm not going to talk about MCP"，但 2025 年下半年 MCP 已是事实标准
- Reasoning Models：OpenAI o-series / Claude extended thinking 的 API 设计（reasoning ID 传递、thinking block 处理），GitHub 上有人提了 Issue 但没有合并进正文
- 多 Agent 协作：只有单 Agent 模式，复杂场景需要自己设计
最大的问题是：项目已经 7 个月没更新了。
最后一次 commit 是 2025 年 9 月。Reasoning models 的问题、MCP 的整合，这些 2025 下半年出现的新范式，文档都没有覆盖。
怎么用这个项目
把它当作工程思维读物，而不是 API 手册。
重点读这三篇：
- Factor 3 — Context Engineering
- Factor 8 — Control Flow
- Factor 12 — Stateless Reducer
Factor 1 和 Factor 2 相对基础，有经验的开发者可以跳过。
然后结合两份材料一起看：
- Anthropic 的 Building Effective Agents
- MCP 文档（Model Context Protocol）
Dext 的博客 The Outer Loop 也值得订阅。
一句话评价
12-Factor Agents 的核心思想依然是最清醒的 Agent 工程声音：Agent 是软件，控制流归软件，LLM 只做决策。
但文档本身已经落后于 2025 年下半年出现的 MCP 和 Reasoning Models 范式。
把它当作思维框架来读，结合最新的行业实践来用。
项目地址：https://github.com/humanlayer/12-factor-agents
作者：Dex (@dexhorthy)，HumanLayer 创始人