构建可靠 Agent 应用的 12 种工程化模式

本文整理自 HumanLayer 创始人 Dex Horthy 的技术分享 12-Factor Agents，借鉴经典 12-Factor App 方法论，提炼出构建可靠 LLM 应用的 12 个工程原则。当前大多数 AI 应用停留在 Demo 阶段难以进入生产环境，根本原因在于缺乏工程化思维——本文提供的模式涵盖环境配置、工具设计、人机协作、记忆管理等关键维度，帮助开发者构建真正可靠的 Agent 系统。

内容提要：

大多数 AI 应用从原型到生产级的转变需要工程化的思维和方法
12-Factor Agents 借鉴 12-Factor App，为 LLM 应用提供可移植、可扩展、持续部署的工程化框架
核心模式涵盖环境配置、工具设计、人机协作、记忆管理、审批机制等关键维度
可靠性是 AI 应用的核心挑战，需要通过系统化的工程实践来解决

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 系统。

更多案例和实践经验

如果你想继续把 12-Factor Agents 落到真实工程里，可以再看三个互补案例。第一个聚焦执行约束，第二个聚焦组织级基础设施，第三个则展示了一家公司如何把 Agent 能力真正接入研发平台、知识系统和质量控制链路。

Your AI Isn’t “Stupid” — It Just Needs a Better Harness

这篇文章提供了一个很典型的场景：让智能体写一份市场分析报告，前几步进展顺利，但做到中途开始胡编，因为搜索结果超出了上下文窗口被静默截断；再往后，模型又吐出一段残缺的 JSON，整条链路直接报废，只能从头再跑。

它想说明的问题非常直接：很多时候，不是模型能力不足，而是系统缺少足够强的执行约束。文章提出了四条很实用的 Harness Engineering 原则，和上文的很多工程化模式可以直接对应起来：

能用代码约束的事，不要指望模型自觉完成。比如 JSON 格式，不要在提示词里反复要求输出合法 JSON，而是直接做 Schema 校验，非法输出就拒绝并重试。
关键状态必须外置，不能只放在上下文里。模型执行到哪一步、哪些任务已完成、哪些还没做，都应该写入外部状态文件或状态存储。这样即使链路中断，也可以从中间状态恢复，而不是整条流程全部重来。
模型输出不能自己给自己打分，必须有独立验收机制。不要让模型同时负责执行和验收。更可靠的做法是使用独立的 Evaluator，或者直接让系统执行结果验证，比如运行编译器、调用测试、打开页面检查 UI，而不是依赖模型主观判断是否已经完成。
失败要限制在局部，避免单点错误拖垮整条链路。工具调用失败，就只重试这一步；结构化输出失败，就只修复这一段；不要让一个局部错误把整个 Agent 任务都拖垮。

如果说 12-Factor Agents 更像一套生产原则，那么这篇文章提醒的是另一件事：Agent 不稳定，往往不是因为推理能力不够，而是因为执行框架不够稳定。

Why Your “AI-First” Strategy Is Probably Wrong

这篇文章讨论的是另一个更激进的问题：如果 AI 写代码、审代码、跑测试、部署上线都越来越快，那是不是可以把整条研发流水线都交给 AI，把人只保留在极少数决策节点上？

这个设想并不空泛。PM 不再是需求瓶颈，QA 不再是测试瓶颈，团队规模也不再是速度瓶颈。AI 写代码、AI 审查代码、AI 跑测试、AI 部署发布、AI 监控线上状态，出问题自动回滚，系统再定时扫描日志、发现问题、创建任务、跟踪修复。整条链路如果真的跑通，软件迭代速度会显著提升。

但文章真正有价值的地方，在于它没有停留在愿景层，而是反过来问了一个更务实的问题：在你喊出 AI First 之前，下面这些基础条件是否已经具备？

自动化测试是否足够完善。如果 AI 改完代码后，你仍然需要人工回归大部分核心功能，那速度优势根本释放不出来。
CI/CD 流程是否真正打通。从提交代码到测试、审查、发布、回滚，如果中间还有大量人工操作，AI 只是在更快地产生待处理变更。
A/B 测试和线上监控是否成熟。功能上线后，如果没有可观测性、没有指标、没有快速回滚机制，你就无法判断 AI 产出的功能到底该保留还是该撤掉。
任务管理是否足够清晰。 AI 擅长处理边界明确、粒度合适的任务，但对大而模糊的问题依然不稳定。多个 Agent 并行工作时，任务拆分、优先级和生命周期管理都会变得更加重要。
系统架构是否足够清楚。如果代码库本身边界混乱、依赖纠缠、上下文臃肿，那么无论是人还是 AI，修改的风险和回归成本都会显著上升。

换句话说，AI First 不是一句组织口号，而是一个系统工程结果。没有测试、部署、监控、任务管理和清晰架构打底，AI 只会把混乱放大得更快。

文章最后对适用场景的判断也很重要。它更适合后端逻辑为主、界面复杂度不高、效果可以快速量化的产品，比如 API 服务、数据处理平台、内部工具，以及早期快速试错的产品阶段。而对 UI 密集型产品、核心体验高度敏感的产品，以及安全要求极高的系统，这套玩法就要谨慎得多。

The AI engineering stack we built internally — on the platform we ship

Cloudflare 这篇文章的价值，在于它不是讨论单点技巧，而是展示了一个较完整的内部 Agent 工程栈。根据文中 2026 年 4 月 20 日披露的数据，过去 30 天里 Cloudflare 有 3,683 名内部用户在使用 AI 编程工具，占研发组织的 93%；系统处理了 4,795 万次 AI 请求，2413.7 亿 token 经过 AI Gateway，另有 518.3 亿 token 由 Workers AI 处理。这个量级说明，Agent 已经不是试验项目，而是进入了日常研发流程。

文章最值得参考的地方，是它把整套系统拆成了三个层次：

平台层。统一身份认证、模型路由、成本追踪、零数据保留、MCP Server Portal、沙箱执行和长生命周期 Agent 会话都放在统一控制面里。一个代理 Worker 作为单一入口，负责转发请求、注入权限和做匿名化追踪。这和本文的配置管理、模型解耦、安全沙箱、可观测性优先高度一致。对应到具体产品，分工也很清楚：Cloudflare Access 用于零信任身份认证和统一授权；AI Gateway 负责模型路由、密钥托管、成本追踪、BYOK 和零数据保留策略；Workers AI 用于承接开源模型推理，适合对成本、延迟和数据驻留更敏感的内部场景；Workers 用来搭建 MCP Server Portal、代理入口和审查集成逻辑；Dynamic Workers 负责运行 Agent 生成的代码，提供隔离执行环境；Agents SDK 配合 Durable Objects 管理有状态、长生命周期的 Agent 会话；Sandbox SDK 用于需要完整开发环境的任务，例如克隆仓库、安装依赖、构建和测试；Workflows 负责多步骤、可恢复的长链路任务编排。
知识层。 Cloudflare 用 Backstage 维护服务目录和依赖关系，再为代码仓库生成简短的 AGENTS.md，把测试命令、目录结构、团队约束、禁改边界和依赖关系明确写出来。这样 Agent 不需要反复猜测仓库结构，知识也不再只存在于少数工程师经验里。这正对应了显式状态管理和工具接口设计的要求。这里各个组件的作用也很明确：Backstage 负责维护服务、数据库、团队、API 和依赖图谱，解决 Agent 缺少系统级上下文的问题；AGENTS.md 负责把仓库级规则压缩成可直接进入上下文窗口的高信号说明，适合代码生成、代码修改、测试执行和 MR 审查前的快速对齐。
约束层。他们把 AI Code Reviewer 直接接进 GitLab CI，让每个 MR 都自动经过多 Agent 审查流程，覆盖代码质量、安全、文档、性能和规范一致性。Reviewer 会结合仓库内的 AGENTS.md 和中央 Engineering Codex 规则库输出结构化评论，并按风险级别决定审查深度。这里体现的是人机协作、版本化规则、持续优化和可观测性闭环。在这一层，Workers 承担 Reviewer 的编排和接入逻辑，AI Gateway 负责模型调用治理，AGENTS.md 提供仓库本地约束，Engineering Codex 提供跨团队统一规范，GitLab CI 则把这些检查强制接入每个合并请求，适合做自动化代码评审、规范检查和风险分级。

这篇文章给出的经验很明确：Agent 真正进入生产，不是先追求一个更强的模型，而是先建立统一入口、统一上下文、统一约束和统一反馈机制。只有这样，工具调用、知识获取、代码生成和质量控制才能形成稳定闭环。

把这三篇文章和本文放在一起看，会更容易理解一件事：真正可靠的 Agent 系统，不是单靠模型能力就能成立，而是模型能力、工程约束、组织流程和反馈闭环共同作用的结果。