本文整理自 HumanLayer 创始人 Dex Horthy 的技术分享 12-Factor Agents，借鉴经典 12-Factor App 方法论，提炼出构建可靠 LLM 应用的 12 个工程原则。当前大多数 AI 应用停留在 Demo 阶段难以进入生产环境，根本原因在于缺乏工程化思维——本文提供的模式涵盖环境配置、工具设计、人机协作、记忆管理等关键维度，帮助开发者构建真正可靠的 Agent 系统。
1. 配置即代码（Environment Configuration）
现代软件工程的核心原则之一是配置与代码分离。对于 Agent 应用同样如此——API 密钥、模型选择、温度参数等配置应该通过环境变量管理，而非硬编码在代码中。
这样做的好处：
- 不同环境（开发/测试/生产）可以无缝切换
- 敏感信息不会泄露到代码仓库
- 配置变更无需重新部署代码
实践建议：使用 .env 文件管理本地配置，生产环境使用密钥管理服务（如 AWS Secrets Manager、Azure Key Vault）。
2. 工具即接口（Tools as Interfaces）
Agent 的能力来自于它能够调用的工具（Tools）。将工具设计视为接口设计是构建可靠 Agent 的关键。
每个工具应该有：
- 清晰的命名：让 LLM 能直观理解工具用途
- 准确的描述：详细说明工具的功能、参数、返回值
- 恰当的抽象：既不过于底层（需要多轮调用才能完成一个任务），也不过于高层（失去灵活性）
工具设计遵循单一职责原则，每个工具只做一件事并做好。避免”万能工具”的诱惑——它们往往导致 Agent 调用意图不明确。
3. 人机协作回路（Human-in-the-loop）
生产级 Agent 必须有人类监督机制。Human-in-the-loop 不是可选功能，而是可靠性保障的核心。
典型的需要人工审批的场景：
- 涉及资金的交易操作
- 对外发送的消息/邮件
- 修改重要系统配置
- 访问敏感数据
实现方式：在关键步骤设置”检查点”，等待人工确认后再继续执行。HumanLayer 等工具可以帮助实现这一模式。
4. 显式状态管理（Explicit State Management）
Agent 应用需要显式管理对话状态、工具执行结果、中间思考过程等。
避免的状态管理方式：
- 依赖 LLM 隐式”记住”之前的对话（不可靠且成本高）
- 将所有历史记录无差别塞进上下文窗口（浪费 token 且效果差）
推荐的模式：
- 结构化存储对话历史和关键状态
- 使用状态机明确定义 Agent 的各个阶段
- 定期总结和压缩历史信息
5. 工具调用的幂等性（Idempotent Tools）
由于 LLM 可能产生幻觉或错误，同一个工具调用可能被重复执行。工具设计应该考虑幂等性——多次执行产生相同结果。
幂等性实践：
- 写入操作使用唯一 ID 去重
- 查询操作不改变系统状态
- 所有工具返回结构化结果，便于判断执行成功与否
6. 可观测性优先（Observability First）
Agent 系统的可观测性比传统软件更重要，因为 LLM 的行为更难以预测。
必备的可观测性要素：
- 详细的日志记录：记录每次 LLM 调用、工具调用、状态变更
- 追踪链路：跨多轮对话的完整调用链
- 性能指标：延迟、token 消耗、成功率
- 版本管理：记录使用的模型版本、提示词版本
7. 持续集成与持续部署（CI/CD）
Agent 应用应该像其他软件一样，有完整的 CI/CD 流程。
CI/CD 注意事项：
- 自动化的单元测试和集成测试
- 提示词版本的回滚能力
- 金丝雀发布和蓝绿部署支持
- 生产环境的实时监控和告警
8. 模型解耦（Model Decoupling）
不要将应用与特定模型强绑定。模型能力在快速演进，应用架构应该支持模型切换。
解耦策略：
- 抽象模型调用接口，支持多种模型后端
- 提示词按模型系列组织（GPT、Claude、Gemini 等）
- 评估基准测试，量化不同模型的表现差异
9. 安全与沙箱（Security & Sandboxing）
Agent 有能力执行代码、调用 API、访问数据，安全风险远高于传统应用。
安全实践：
- 工具运行在沙箱环境中
- 最小权限原则——Agent 只能访问必要的资源
- 输入验证和输出过滤
- 敏感操作的额外认证层
10. 版本化的提示词（Versioned Prompts）
提示词是 Agent 的”代码”，应该像代码一样版本化管理。
提示词工程实践：
- 使用模板引擎管理提示词
- Git 版本控制提示词文件
- A/B 测试不同的提示词变体
- 生产环境使用固定版本的提示词（避免意外变更）
11. 优雅降级（Graceful Degradation）
LLM 服务可能不可用、超时、返回错误。Agent 应用需要有优雅的降级策略。
降级策略：
- 关键功能使用备用模型或规则引擎
- 非关键功能可以暂时关闭
- 向用户清晰地说明当前状态和限制
- 失败的请求可以排队稍后重试
12. 持续优化（Continuous Optimization）
构建 Agent 不是一次性任务，需要基于生产数据持续优化。
持续优化方法：
- 收集用户反馈和失败案例
- 定期分析工具调用成功率
- 基于数据迭代提示词和工具设计
- 建立性能基线，量化改进效果
总结
12-Factor Agents 不是教条，而是一套经过验证的工程实践。从原型到生产级应用，需要的不仅是更好的模型，更可靠的系统架构和工程化思维。
核心原则回顾：
- 配置即代码——环境变量管理配置
- 工具即接口——良好的工具设计是可靠 Agent 的基础
- 人机协作——关键操作需要人工审批
- 显式状态——结构化状态管理
- 幂等性——工具调用可重复执行
- 可观测性——详细的日志和监控
- CI/CD——自动化的部署流程
- 模型解耦——不绑定特定模型
- 安全沙箱——最小权限和安全执行
- 提示词版本——像代码一样管理提示词
- 优雅降级——应对模型失效的策略
- 持续优化——基于数据持续改进
这些要素共同构成了可靠 LLM 应用的基础框架，帮助开发者构建真正可投入生产的 AI 系统。