构建可靠 LLM 应用的工程原则——
在 AI Agent 时代，重新定义「十二要素」。
HumanLayer 出品 · 致敬 12factor.net · AI Engineer World's Fair 演讲
← 返回汇总让 Agent 回归软件工程。
不是框架，是一套原则。任何语言、任何框架都可应用。
作者 Dex 试过所有 Agent 框架，访谈众多 YC 创始人后发现：大多数自称"AI Agent"的产品并不那么 agentic。
用什么原则，才能构建出
真正敢交付给生产用户的 LLM 软件？
答案不是更聪明的模型，而是工程方法。即便 LLM 指数级变强，这些核心工程技巧仍让 LLM 软件更可靠、可扩展、易维护。
2011 年 Heroku 发布 12-Factor App，定义了云原生应用最佳实践，深刻影响了 Docker/Kubernetes 时代。
云原生应用 → 配置分离、无状态、日志即事件流...
LLM 应用 → 上下文工程、状态统一、人是工具...
Agent 的入口是把自然语言转化为结构化工具调用。
不要让框架黑盒管理 prompt，自己写、自己调。
主动构建上下文，而非被动接收。Context Engineering。
工具调用本质是结构化输出，统一对待。
Agent 执行状态与业务状态用同一套机制管理。
用简单 API 实现可中断、可恢复的执行。
Human-in-the-loop 也是一次工具调用，而非特殊机制。
不要把流程逻辑交给 LLM 隐式决策，自己编排。
错误是上下文的一部分，要压缩后纳入而非丢弃。
单 Agent 单职责，避免塞所有逻辑。
从任何渠道触发，在用户所在之处响应。
把 Agent 做成 stateless reducer，状态外置可恢复。
| 反模式 | 问题 |
|---|---|
| Prompt + 工具袋 + 无脑循环 | 不可控、不可预测、难调试 |
| 框架黑盒管理 prompt | 无法精细调优，迁移成本高 |
| 把流程逻辑交给 LLM | 非确定性，每次跑不一样 |
| 单个巨型 Agent | 难扩展、难维护、难测试 |
| 状态内置于 Agent | 崩溃即丢失，无法水平扩展 |
上下文不是给出来的，是构建出来的。
借鉴 Redux 思想：Agent 是一个 (state, event) → state 的纯函数。状态外置存储，Agent 本身无状态。
可水平扩展、崩溃可恢复、可重放调试、易测试。
需把状态显式建模，不能依赖内存中的隐式状态。
Python/TS/Go，LangGraph/自研栈都能用。
来自 HumanLayer 构建真实客户面 Agent 的踩坑总结。
Agent 工程化尚无成熟标准，这是早期权威参考。
每条原则有具体实践，create-12-factor-agent 脚手架。
AI Agent 工程化方法论的开源定义者。若社区采纳，将成为构建生产级 Agent 的参考标准——类似 12-Factor App 之于云原生。即便具体原则演进，其"用工程方法驯服 LLM 不确定性"的核心思想长期有效。对任何严肃做 Agent 的人，这是必读。