0
异步视界/agentic-coding-classics/12-factor-agents
· AGENTIC-CODING-CLASSICS · 2026.05.06 · 9 MIN ·

Dex Horthy《12-Factor Agents》:可靠 LLM 应用的 12 条宪法

GitHub 19.6k stars。仿 Heroku 12-Factor App 的生产级 agent 设计宪法。最反共识的论断:市面上自称 agent 的产品大部分并不那么 agent — 它们就是普通软件。精读 + 译者点评。 · by fancyoung
AI · HERO seed:4020260506 GitHub 19.6k stars。仿 Heroku 12-Factor App 的生产级 agent 设计宪法。最反共识的论断:市面上自称 agent 的产品大部分并不那么 agent — 它们就是普通软件。精读 + 译者点评。
FIG.00 — cover · ai-generated · placeholder

Factor 1: Natural Language to Tool Calls

原文:github.com/humanlayer/12-factor-agents 作者:Dex Horthy(HumanLayer 创始人) 演讲首发:AI Engineer World’s Fair, 2025 早期

🔥 影响力卡片

  • GitHub 19.6k stars,1.5k forks(截至 2026 年初)
  • 登过 Hacker News 头条(item id 43699271)
  • 致敬 Heroku 的经典 12-Factor App 方法论
  • 基于作者亲自访谈 100+ 创业者和 AI 工程师的总结
  • 与 Anthropic 官方指南、NotebookLM 等并列被引用,被称为”agent 工程师的宪法”

🎯 为什么必读

如果说 Anthropic 的文章是”设计模式手册”,这篇是**“生产纪律宪法”**。

它的特别之处在于:不教你怎么用 SDK,反而教你怎么少用 SDK。Dex 的核心洞察来自残酷的现场观察:几乎所有用 agent 框架建的产品都卡在 70-80% 的质量瓶颈,要突破必须从头重写。

读完你会明白:

  1. 为什么”loop until done”是产品不是工程
  2. 为什么 LangChain 等框架在生产里痛苦
  3. 一个”看起来不那么炫”的 agent 设计为什么更可靠

一句话总结

市面上大多数自称”AI agent”的产品,其实并不那么”agent”。 真正成功的生产 agent 主要是精心工程的传统软件,只在关键决策点谨慎注入 LLM 能力。

💎 金句墙

★ “Most of the products out there billing themselves as ‘AI Agents’ are not all that agentic. A good chunk of them are mostly just software.” “市面上自称 ‘AI Agent’ 的产品,其实大部分并不那么 agent —— 它们大部分就是普通软件。”

★ “Agents, at least the good ones, don’t follow the loop-until-goal pattern. Rather, they are comprised of mostly just software.” “好的 agent 不走’循环直到达成目标’的模式 —— 它们主体就是软件。”

★ 典型失败路径(被引用了无数次): “Get to 70-80% quality bar → Realize that 80% isn’t good enough → Start over from scratch.” “做到 70-80% 质量 → 意识到 80% 不够好 → 推倒重来。”

★ “The fastest way I’ve seen for builders to get good AI software in the hands of customers is to take small, modular concepts from agent building, and incorporate them into their existing product.” “让 AI 软件最快上线的办法,是从 agent 建造里取一小段一小段的模块化概念,塞进你已有的产品,而不是从零建一个 agent 系统。”

📋 核心精读 —— 12 条因素逐条点评

(每条:原标题 + 中文意译 + 🟢 译者一句话点评)

Factor 1 — Natural Language to Tool Calls 自然语言转工具调用 🟢 LLM 的核心价值不是”对话”,是”把人话翻译成结构化操作”。

Factor 2 — Own your prompts 掌握自己的 prompt 🟢 不要让框架替你写 prompt。框架的默认 prompt 是给 demo 设计的,不是给你产品设计的。

Factor 3 — Own your context window 掌握自己的 context window 🟢 整篇文章的灵魂。LLM 的输出 = context 决定的。把 context 的构造交给框架 = 把命运交给框架。

Factor 4 — Tools are just structured outputs 工具就是结构化输出 🟢 别神秘化 tool calling。它就是”让 LLM 输出符合 JSON schema 的字符串”,仅此而已。

Factor 5 — Unify execution state and business state 统一执行状态与业务状态 🟢 不要让 agent 内部状态和你的业务数据库脱节。两套状态 = 两套 bug。

Factor 6 — Launch/Pause/Resume with simple APIs 用简单 API 实现启动/暂停/恢复 🟢 长跑 agent 必须能被外部干预。不能被 ctrl+c 安全停下的 agent 是定时炸弹。

Factor 7 — Contact humans with tool calls 用工具调用联系人 🟢 不要把”问人”做成特殊机制。它就是另一个 tool —— 跟 search、browse 一样。HumanLayer 的产品就建在这条原则上。

Factor 8 — Own your control flow 掌握自己的控制流 🟢 与 Factor 3 并列灵魂条款。“agent 就是个 while 循环里调 LLM”这种黑盒 = 你交出了所有 debug 能力。

Factor 9 — Compress errors into context window 把错误压缩进 context window 🟢 错误信息不要全塞回 context —— 压缩成”发生过 X 错误,已重试 N 次”。否则 context rot 让你越错越离谱。

Factor 10 — Small, focused agents 小而专注的 agent 🟢 多个小 agent 用工程方式组合,胜过一个万能大 agent。Anthropic 的 5 种 workflow 是这条原则的具体实现。

Factor 11 — Trigger from anywhere, meet users where they are 任何地方都能触发,在用户在的地方接住他们 🟢 不要逼用户进你的 web app。Slack/邮件/CLI/IM 才是真实工作流的入口。

Factor 12 — Make your agent a stateless reducer 让你的 agent 变成一个无状态归约函数 🟢 函数式编程对 agent 工程的最大贡献。state 在外部,reducer 是 LLM,这种架构无限可扩展。

🟢 译者总评

这 12 条本质上是一句话:

Agent 是软件。当你把它当软件来工程化,你赢;当你把它当魔法 loop,你输。

这跟 Anthropic 的”用最简单的方案就别用 agent”是同一个意思,只是 Dex 更尖锐:SDK 在帮倒忙,所有”快速搭一个 agent”的 SDK 都鼓励你犯 Factor 3、Factor 8 的错。

如果你只从这篇带走 3 条:

  1. Factor 3:Own your context window —— 这是 90% 生产 agent 失败的根因
  2. Factor 8:Own your control flow —— 不要把核心逻辑藏在框架黑盒里
  3. Factor 10:Small, focused agents —— 别建巨型 agent,建一堆小的拼起来

这 12 条与 Anthropic 那篇形成完美互补 —— Anthropic 给你词汇表,Dex 给你纪律。

🔗 延伸阅读

🔗 调研来源(可校验)