12-Factor Agents：构建生产级 LLM 软件的工程原则

LLM 应用开发正在经历从 "Demo 可用" 到 "生产可靠" 的关键转折。许多团队发现，用现有框架快速搭建的原型能在短期内达到 70%-80% 的质量水平，但当试图跨越最后 20% 的鸿沟时，却不得不面对一个残酷现实：框架的抽象层成了调优的障碍，黑盒提示词难以精细控制，最终往往走向反向工程甚至推倒重来。

12-Factor Agents 方法论正是在这一背景下应运而生。它借鉴了经典的 12-Factor Apps 理念，由 HumanLayer 团队基于与上百位 SaaS 构建者的深度交流提炼而成，旨在回答一个核心问题：如何构建真正可靠到可以交付给生产用户的 LLM 驱动软件？

核心哲学：Agent 不是 DAG，而是 "mostly software"

传统软件工程将程序建模为有向图（DAG），开发者精确编码每个节点和边。DAG 编排器如 Airflow、Prefect 的出现，为这一模型增加了可观测性、模块化和重试机制，但本质未变 —— 软件执行的每一步仍由人类开发者明确定义。

Agent 的承诺似乎打破了这一范式：不再需要编码每个步骤，只需给 Agent 一个目标和一组可能的转换，让 LLM 实时决定执行路径。这种 "提示词 + 工具包 + 循环直到完成" 的模式听起来诱人，但实践中却屡屡碰壁。

12-Factor Agents 的核心洞见在于：真正优秀的 Agent 并非高度自主的 "智能体"，而主要是确定性代码，LLM 仅在关键决策点介入。这与 Anthropic 在《Building Effective Agents》中的观点一致 —— 过度依赖 LLM 做决策往往适得其反。

关键原则详解

1. 拥有你的提示词（Own Your Prompts）

许多框架提供 "黑盒" 抽象，通过角色、目标、人格等参数生成提示词。这在快速启动阶段有效，但进入生产调优阶段时，开发者往往发现难以精确控制输入模型的每一个 token。

正确的做法是将提示词视为一等代码公民：使用模板引擎或 BAML 等工具显式定义提示词结构，支持完整的版本控制、测试和迭代。这带来五个关键收益：完全控制、可测试评估、快速迭代、透明可审计，以及灵活利用 API 的非标准用法（如角色注入技术）。

2. 统一执行状态与业务状态

许多系统试图将 "执行状态"（当前步骤、等待状态、重试计数）与 "业务状态"（已发生的操作记录）分离管理。这种分离在复杂场景下有其价值，但对于大多数 LLM 应用而言，它引入了不必要的复杂性。

更简洁的架构是：让上下文窗口成为唯一真实数据源。通过精心设计上下文构建逻辑，可以从消息历史推断出所有执行状态。这种方法带来序列化简单、调试直观、故障恢复容易（只需加载线程即可恢复）、支持任意点分叉等工程优势。

3. 通过工具调用人类

生产级 Agent 必须处理不确定性边界 —— 当置信度不足、涉及敏感操作或需要主观判断时，Agent 应当能够优雅地请求人类介入。关键在于将人类交互建模为与普通工具相同的接口：Agent 输出结构化请求，系统将其路由给合适的人类，人类响应作为新的消息追加到上下文窗口，Agent 继续执行。

这种设计保持了架构的一致性，同时建立了清晰的人机协作边界。

4. 工具即结构化输出

工具调用不应被视为特殊的 API 机制，而应理解为 LLM 输出结构化 JSON 的一种形式。这一视角转变带来重要启示：工具选择本质上是分类问题，工具参数填充是结构化生成问题。基于此，可以统一处理工具调用、响应生成和状态转换，简化 Agent 循环的实现。

5. 小而专注的 Agent

与其构建一个试图处理所有任务的通用 Agent，不如设计多个小而专注的 Agent，每个负责明确的子任务。这不仅降低了单个 Agent 的复杂性，也使得系统更容易测试、调试和迭代。即使 LLM 能力持续指数级提升，这种模块化设计原则仍然适用。

从框架到自主控制：迁移路径

12-Factor Agents 并非否定现有框架的价值 —— 它们在快速原型阶段确实有效。但团队应当意识到框架的适用边界，并规划迁移路径：

阶段一：框架验证（0-2 周）：使用 CrewAI、LangChain 等框架快速验证产品假设，达到 70% 质量水平。

阶段二：关键组件替换（2-4 周）：识别质量瓶颈环节，逐步替换框架的抽象层，开始直接管理提示词和上下文构建。

阶段三：自主控制（4-8 周）：完全掌控 Agent 循环，框架退化为可选的工具库，系统具备完整的可观测性和可调试性。

这一渐进式迁移策略避免了 "推倒重来" 的高昂成本，同时确保最终系统满足生产环境的可靠性要求。

适用边界与权衡

12-Factor Agents 并非银弹。它最适合以下场景：

• 面向客户的生产系统：质量容错空间小，需要精细控制
• 复杂多步骤工作流：需要明确的可观测性和调试能力
• 合规敏感领域：需要审计 Agent 的每一步决策

对于内部工具、原型验证或容错度高的场景，框架的快速启动优势仍然值得考虑。

总结

LLM 应用开发正在从 "魔法演示" 走向 "工程实践"。12-Factor Agents 提供了一套经过验证的原则框架，帮助团队跨越从 Demo 到生产的鸿沟。其核心启示在于：不要盲目追求 Agent 的 "自主性"，而是将 LLM 视为软件系统中的智能组件，在确定性代码与概率性推理之间找到恰当的边界。

正如该方法论所强调的："最快的路径是将 Agent 构建的模块化概念融入现有产品，而非全盘重写。" 这一务实态度，或许正是当前 LLM 应用开发最需要的清醒剂。

参考来源

• 12-Factor Agents - HumanLayer 团队开源的生产级 Agent 构建方法论
• Building Effective Agents - Anthropic 关于有效 Agent 设计的工程建议

ai-systems