跳到主要内容

Agent工程化

本目录面向已经准备把 Agent 从原型推进到生产环境的工程团队。重点不是解释 Agent 为什么有用，而是把“可部署、可回放、可观测、可控成本、可恢复失败、可审计安全”落到工程结构和运行机制上。

核对日期：2026-05-09。

1. 阅读顺序​

顺序文件解决的问题
1Agent项目目录结构一个 Agent 项目应该如何分层，哪些内容必须版本化。
2Prompt工程与版本管理Prompt 如何像代码一样评审、发布、回滚和评测。
3状态管理Agent 执行中哪些状态要持久化，如何避免状态污染。
4会话管理多轮对话、长上下文、用户隔离和会话生命周期。
5队列与异步任务长任务、后台执行、削峰、任务状态和 worker 设计。
6幂等性设计重试、重复投递、回放时如何避免重复副作用。
7缓存策略Prompt、检索、工具结果和模型响应的缓存边界。
8成本控制token、模型、工具、批处理和预算护栏。
9失败重试超时、限流、退避、熔断、降级和补偿。
10回放与调试trace、span、输入快照、确定性回放和事故复盘。
11部署架构API、worker、状态库、队列、观测、安全边界。
12生产上线清单上线前逐项验收。

2. 工程化总原则​

Agent 生产系统必须把模型调用当成不稳定外部依赖，把工具调用当成可能产生真实副作用的分布式事务，把上下文当成可能包含敏感数据的运行状态。一个可上线的 Agent 系统至少需要：

  • 明确的代码、Prompt、工具 schema、评测集和配置分层。
  • 所有外部副作用都有幂等键、审计日志和必要的人类在环审批。
  • 会话、状态、trace、成本和安全事件可以关联到同一个 run_id。
  • 对模型、工具、检索、队列、缓存都有超时、重试、降级和限流策略。
  • 发布前通过离线评测、回归集、红队用例、灰度和回滚验证。

3. 推荐整体架构​

4. 与其他目录的边界​

  • Agent 核心 loop、规划器和执行器的概念，参考 ../02-Agent核心架构/ 与 ../07-规划与任务分解/。
  • 工具调用、MCP、tool schema 的协议细节，参考 ../04-工具调用体系/。
  • 记忆、RAG、知识库治理，参考 ../05-记忆系统/ 与 ../06-RAG与知识系统/。
  • 离线评测、线上观测和运维告警，参考 ../10-Agent评测体系/ 与 ../11-可观测性与运维/。
  • prompt injection、数据外泄、权限治理，参考 ../12-安全与治理/。

本目录只写工程化落地做法，不重复展开其他主题的完整理论。

5. 生产就绪的最低标准​

维度最低标准
可靠性有超时、重试、幂等、任务恢复、降级路径。
可观测性模型调用、工具调用、队列任务、缓存命中、成本都有 trace/span/metric。
安全工具最小权限、敏感数据脱敏、prompt injection 防护、人类审批。
可维护性Prompt、工具 schema、评测集、配置均可版本化和回滚。
成本有预算、限额、模型路由、上下文裁剪、缓存和批处理策略。
上线有 staging、灰度、回滚、事故预案和上线清单。

6. 权威资料​