# 12 Factor Agents：构建生产级 AI Agent 的十二原则

> 原文链接：https://www.humanlayer.dev/blog/12-factor-agents
> 作者/来源：Dex Horthy / HumanLayer
> 阅读日期：2026-04-02

## 一句话总结
借鉴经典的 12-Factor App 方法论，提出构建生产级 AI agent 的十二条原则，核心主张是：有效的 agent 应该是"大部分确定性代码 + 战略性 LLM 决策"的组合，而非纯粹的"prompt + tools + loop"。

## 核心论点

文章挑战了当前 agent framework 的主流范式，认为市面上大多数自称"AI Agent"的产品其实并不真正具备 agentic 能力。作者 Dex Horthy 主张，与其构建单体式的全能 agent 系统，不如将 LLM 的智能决策能力嵌入到更大的确定性软件架构中。这意味着开发者应该拥有对 prompt、context window 和 control flow 的完全控制权，而不是将这些关键环节交给 framework 的抽象层。

文章以一个实际的部署机器人为例（管理前后端发布的 agent），展示了 human-in-the-loop 的决策流程：agent 提出部署步骤，人类审批或反馈，agent 据此调整。这体现了"micro-agent 嵌入确定性 DAG"的架构思路，而非试图构建一个无所不能的单一系统。

整体来看，这十二条原则的核心哲学是：**将成熟的软件工程实践与 LLM 的推理能力结合**，而非把所有责任都推给模型。这种务实的工程思维，使得 agent 系统真正可以投入生产环境。

## 关键概念

- **Natural Language to Tool Calls（Factor 1）**：将自然语言转化为结构化 JSON 输出，触发确定性代码执行。LLM 负责决策，人类编写的代码负责执行。
- **Own Your Prompts（Factor 2）**：将 prompt 视为一等公民代码，而非依赖 framework 抽象。这提供了完全的控制力、可测试性和针对特定用例的优化灵活性。
- **Context Engineering（Factor 3）**：一切皆为 context engineering。不使用标准消息格式，而是构建自定义的 context 结构，优化 token 效率和 LLM 性能。文章展示了基于 XML 的 context 格式作为替代方案。
- **Tools Are Just Structured Outputs（Factor 4）**：Tool 本质上只是 LLM 的结构化输出，触发确定性代码。这种分离允许灵活处理 tool call。
- **Unified State（Factor 5）**：将执行状态（当前步骤、重试次数）与业务状态统一为单一事件流，简化序列化、调试和恢复。
- **Launch/Pause/Resume（Factor 6）**：通过简单 API 实现 agent 的启动、暂停和恢复，支持与外部系统集成和长时间运行的操作。
- **Contact Humans with Tool Calls（Factor 7）**：用结构化 tool call 请求人类输入，将人类联系视为一等操作。支持"outer loop agent"模式。
- **Own Your Control Flow（Factor 8）**：构建自定义控制结构，决定何时循环、暂停或升级。允许在 tool 选择和执行之间插入中断——对审批工作流至关重要。
- **Compact Errors into Context（Factor 9）**：将错误信息纳入 context window，实现自我修复。LLM 可以读取错误并调整后续调用。
- **Small, Focused Agents（Factor 10）**：构建处理 3-20 步工作流的 agent，而非单体系统。随着 context 增长，LLM 更容易迷失或失去焦点。
- **Trigger from Anywhere（Factor 11）**：使 agent 可通过多种渠道（Slack、邮件、短信）触发和响应，创造"数字同事"体验。
- **Stateless Reducer（Factor 12）**：将 agent 设计为函数式 reducer——纯函数将状态加事件转化为新状态，确保可预测性和可测试性。

## 实践建议
1. 不要急于使用 agent framework，先理解底层原理，自己掌控 prompt 和 control flow
2. 将 agent 设计为小而专注的模块，嵌入更大的确定性工作流（DAG）中
3. 将 context window 视为稀缺资源，精心设计上下文结构而非简单堆叠消息
4. 为 agent 系统设计 human-in-the-loop 机制，将人类审批作为 tool call 的一种
5. 用 stateless reducer 模式设计 agent，确保可恢复、可测试、可调试

## 独到观点
这篇文章最独特的贡献在于将经典软件工程方法论（12-Factor App）迁移到 AI agent 领域，提供了一套系统化的设计原则，而非零散的最佳实践。特别是"Agent as Stateless Reducer"的概念，将函数式编程的纯函数思想引入 agent 设计，这在 agent 设计文献中相对少见。另外，"Contact Humans with Tool Calls"将人类交互标准化为 tool call 的思路，为 human-in-the-loop 提供了优雅的工程实现方案。

## 与其他文章的关联
- 与 [LangChain: Agent Frameworks, Runtimes, and Harnesses](34-langchain-frameworks-runtimes-harnesses.md) 高度互补，后者从架构分层角度区分了 framework/runtime/harness 的概念
- "Context Engineering"思想与 [LangChain: Improving Deep Agents with Harness Engineering](32-langchain-improving-with-harness.md) 中的 harness engineering 理念一致
- "Small, Focused Agents"原则与 [Anthropic: Multi-Agent Research System](35-anthropic-multi-agent-research.md) 的多 agent 协作模式相呼应
- 对 agent 评估的重视与 [Anthropic: Demystifying Evals](29-anthropic-demystifying-evals.md) 和 [OpenAI: Eval Skills](27-openai-eval-skills.md) 等评估方法论文章形成互补