Agent系统设计
核对日期：2026-05-13。
不稳定项：Agent SDK、工具调用协议、MCP 生态、浏览器/电脑操作能力、长期记忆方案和多 Agent 框架变化较快；生产项目必须以目标 SDK、模型能力和安全评测结果为准。
专题文件索引
本阶段已拆分为 5 个专题文件。README.md 仍保留完整阶段讲义和练习入口；专题文件用于深入学习、后续扩写和站点导航。
| 专题 | 重点 |
|---|---|
| 01-agent-loop与控制流.md | Agent 与 Workflow 边界、最小 loop、停止条件、计划漂移 |
| 02-工具调用与权限模型.md | 工具 schema、权限分级、幂等性、审批、MCP 工具治理 |
| 03-状态记忆与任务恢复.md | 结构化状态、长期记忆、事实冲突、任务恢复、上下文压缩 |
| 04-HITL与失败处理.md | 人类在环、审批卡片、失败类型、降级、撤销和事故复盘 |
| 05-Agent轨迹评测.md | 轨迹 eval、工具选择评分、失败样例库、规则评分与 judge |
生产闭环交叉引用
Agent 系统设计要和评测、安全、生产化一起读：
| 当前问题 | 继续阅读 |
|---|---|
| 如何证明 Agent 轨迹可靠 | ../10-评测体系/04-Agent轨迹评测.md |
| 工具权限、scoped credential 和审批 | ../11-安全与治理/04-工具权限审计与人类审批.md |
| Prompt injection、间接注入和工具诱导 | ../11-安全与治理/02-Prompt注入与间接注入防护.md |
| Agent trace、成本和线上观测 | ../12-LLMOps与生产化/04-可观测性与Trace.md |
| Agent 变更如何灰度、回滚和止损 | ../12-LLMOps与生产化/05-灰度发布回滚与供应商治理.md |
1. 阶段目标
本阶段目标是掌握 AI Agent 的工程设计方法。Agent 不是“更聪明的聊天机器人”，而是一个由模型、工具、状态、控制流、权限、评测和人类在环组成的执行系统。
学完本阶段，你应该能做到：
- 区分普通 LLM 调用、Workflow、Agent 和多 Agent 系统。
- 设计 Agent loop：观察、决策、工具调用、状态更新、终止和交接。
- 为工具设计 schema、权限等级、错误处理、幂等性和审计字段。
- 设计短期状态、长期记忆、任务日志和恢复机制。
- 识别计划漂移、循环、工具误用、上下文污染和权限越界。
- 设计人类在环：确认、审批、升级、复核和撤销。
- 使用 trace 记录 Agent 轨迹，并为任务成功率、工具准确率、成本和失败原因建立评测。
- 判断什么时候应该用固定 Workflow，什么时候才值得引入 Agent。
本阶段的核心产出是：
- 一个只读 Agent 设计。
- 一个受控写入 Agent 设计。
- 一份工具 schema 和权限分级表。
- 一份 Agent 轨迹评测 Rubric。
2. 学习前置条件
建议已完成：
05-Transformer与大模型原理，理解模型生成和推理边界。06-Prompt与上下文工程，能组织上下文包和结构化输出。07-RAG与知识系统，理解检索、引用和权限过滤。08-AI应用工程，理解 streaming、异步任务、成本账本和可观测性。
不要求：
- 一开始就使用复杂 Agent 框架。
- 自研工具协议或 MCP 服务器。
- 让 Agent 自动执行高风险写操作。
3. 核心知识地图
4. 详细讲义
4.1 什么是 Agent
工程上可以把 Agent 定义为：模型在一个受控循环中，根据目标、状态和环境反馈，动态选择工具、更新状态并推进任务的系统。
它至少包含：
- 目标：用户要完成什么。
- 状态：当前进展、已知事实、待办和约束。
- 模型决策：下一步做什么。
- 工具：搜索、读取、写入、执行、调用业务系统。
- 观察：工具返回和环境反馈。
- 控制流：循环、停止、重试、升级。
- 权限：哪些动作允许，哪些需要审批。
- 评测：任务是否真的成功。
如果一个系统只是固定调用 3 个步骤，它更像 Workflow；如果模型能根据观察结果动态选择下一步，它才更接近 Agent。
4.2 Agent 和 Workflow 的区别
| 维度 | Workflow | Agent |
|---|---|---|
| 控制流 | 代码预定义路径 | 模型动态决定路径 |
| 步骤数量 | 通常固定 | 可能变化 |
| 可预测性 | 高 | 较低 |
| 成本和延迟 | 更可控 | 更高且波动 |
| 适合任务 | 流程稳定、规则明确 | 开放、多步、难预先枚举 |
| 风险 | 灵活性不足 | 循环、漂移、越权、成本失控 |
经验判断：
- 能用单次 LLM 调用解决，就不要做 Agent。
- 能用固定 Workflow 解决，就不要做自主 Agent。
- 只有当任务路径难以预定义，且工具反馈能帮助模型逐步推进时，Agent 才有必要。
4.3 常见 Agentic 模式
| 模式 | 机制 | 适用 | 风险 |
|---|---|---|---|
| Prompt chaining | 多个 LLM 调用串联 | 可分解的固定任务 | 延迟增加 |
| Routing | 根据输入路由到不同处理器 | 客服、分类、模型路由 | 路由错导致后续全错 |
| Parallelization | 并行处理再汇总 | 多维审查、批量分析 | 聚合标准不清 |
| Orchestrator-workers | 中央模型拆任务给 worker | 复杂研究、代码修改 | 子任务边界混乱 |
| Evaluator-optimizer | 生成-评价-修复循环 | 写作、代码、检索 | 循环成本高 |
| ReAct | 推理、行动、观察交替 | 工具使用和搜索 | 思考漂移、工具误用 |
| Plan-and-Execute | 先计划再执行 | 多步骤任务 | 计划过早失效 |
| Supervisor | 监督者调度多个 specialist | 多能力系统 | 架构过度复杂 |
不要为了“看起来高级”上多 Agent。多 Agent 的主要价值是分离职责和并行，不是让多个模型互相聊天。
4.4 Agent Loop 的最小结构
一个只读 Agent loop 可以这样设计：
state = init(task)
for step in 1..max_steps:
decision = model.decide(state, tools)
if decision.type == "final":
return decision.answer
if !policy.allowed(decision.tool, decision.args):
return escalate("tool not allowed")
observation = tool.run(decision.args)
state = update_state(state, decision, observation)
if budget.exceeded() or state.stuck():
return escalate("needs human")
必须有：
max_steps：防止无限循环。budget：控制 token、工具成本和时间。policy.allowed：系统层权限，不交给模型。state.stuck：识别重复行动。trace：记录每一步。
4.5 工具设计：Agent-Computer Interface
工具不是随便暴露一个 API 给模型。工具定义就是 Agent 的“操作界面”。
好的工具 schema 包含：
- 清晰名称。
- 具体描述。
- 参数类型和约束。
- 示例输入。
- 返回结构。
- 错误码。
- 权限级别。
- 是否幂等。
- 是否需要审批。
- 是否会产生外部副作用。
示例：
{
"name": "create_refund_draft",
"description": "创建退款申请草稿，不会直接退款。必须由人工审批后才能提交。",
"permission": "write_draft",
"requires_approval": true,
"input_schema": {
"type": "object",
"required": ["order_id", "amount", "reason"],
"properties": {
"order_id": {"type": "string"},
"amount": {"type": "number", "minimum": 0},
"reason": {"type": "string", "maxLength": 200}
}
}
}
工具设计原则：
- 参数越明确越好。
- 写操作优先做成“草稿”或“申请单”。
- 相似工具要用清晰命名区分。
- 返回值要结构化，避免大段无关文本。
- 失败要返回可行动错误，而不是只返回异常字符串。
4.6 工具权限分级
| 等级 | 能力 | 示例 | 策略 |
|---|---|---|---|
| L0 | 无外部访问 | 纯文本总结 | 无需特殊审批 |
| L1 | 只读公开信息 | Web 搜索、公开文档读取 | 记录来源 |
| L2 | 只读内部信息 | CRM 查询、代码库读取 | 鉴权、最小权限、脱敏 |
| L3 | 创建草稿 | 创建工单草稿、退款申请草稿 | 人工确认 |
| L4 | 低风险写入 | 打标签、更新非关键字段 | 审计、可撤销 |
| L5 | 高风险写入 | 付款、退款、删除、发邮件 | 强审批、双人复核、回滚 |
| L6 | 执行代码/系统命令 | shell、浏览器、数据库写入 | 沙箱、最小权限、人工批准 |
模型可以建议工具调用，但系统必须决定是否允许。
4.7 状态管理
Agent 状态不是聊天历史。状态应该是可读、可恢复、可验证的任务对象。
推荐状态字段：
| 字段 | 说明 |
|---|---|
| task_id | 任务 ID |
| goal | 当前目标 |
| constraints | 用户和系统约束 |
| facts | 已确认事实 |
| open_questions | 未确认问题 |
| plan | 当前计划 |
| completed_steps | 已完成步骤 |
| pending_actions | 待执行动作 |
| tool_results | 关键工具返回摘要 |
| approvals | 审批状态 |
| errors | 错误和恢复记录 |
| budget | token、时间、工具调用预算 |
状态更新要遵循：
- 新事实必须有来源。
- 过期事实要标注。
- 冲突事实不能静默覆盖。
- 大段原始工具输出应摘要后入状态。
- 关键状态变更写入 trace。
4.8 记忆设计
Agent 记忆分几类：
| 类型 | 内容 | 风险 |
|---|---|---|
| 短期记忆 | 当前任务上下文 | 上下文膨胀 |
| 长期用户记忆 | 用户偏好、历史设置 | 隐私和陈旧 |
| 项目记忆 | 代码库约定、业务规则 | 过时和冲突 |
| 操作记忆 | 历史工具调用和结果 | 敏感信息泄露 |
| 失败记忆 | 失败案例和修复经验 | 误泛化 |
记忆写入必须比读取更严格：
- 明确写入条件。
- 记录来源和时间。
- 支持删除和过期。
- 不保存敏感数据。
- 用户偏好和事实分开。
- 不把模型猜测写成记忆。
4.9 规划和计划漂移
计划是 Agent 对任务的临时路线，不是合同。
计划漂移常见表现：
- 忘记原始目标。
- 做无关子任务。
- 重复搜索相同信息。
- 工具结果不支持下一步却继续推进。
- 修改计划但不解释原因。
缓解方式：
- 每步显式对齐目标。
- 状态中保留成功标准。
- 最大步数和重复检测。
- 关键节点让模型复述当前计划。
- 对高风险步骤进入人工确认。
- 用 trace 评测计划和行动是否一致。
4.10 人类在环
人类在环不是形式化弹窗，而是在系统不确定、高风险或缺权限时，把足够上下文交给人决策。
需要人类介入的情况：
- 高风险写操作。
- 证据冲突。
- 预算超限。
- 工具失败超过阈值。
- 模型低置信度。
- 涉及法律、财务、医疗、人事等敏感判断。
- 用户明确要求人工确认。
审批界面必须展示：
- Agent 想做什么。
- 为什么做。
- 使用了哪些证据。
- 影响范围。
- 可撤销方式。
- 替代选项。
- 审计记录。
只给“确认/取消”按钮是不够的。
4.11 单 Agent 与多 Agent
多 Agent 适合：
- 子任务可并行。
- 角色职责明确。
- 每个子任务有独立验收标准。
- 聚合器能处理冲突。
- trace 能回放每个 Agent 的贡献。
不适合：
- 任务本身很简单。
- 只是想让多个模型互相讨论。
- 没有预算和最大轮数。
- 没有聚合标准。
- 权限边界不清。
多 Agent 的工程难点不是“让它们说话”，而是任务分解、上下文隔离、结果合并、冲突处理和责任追踪。
4.12 MCP 和工具生态
MCP 是一种让模型应用连接外部工具、数据源和服务的协议思路。它的价值在于把工具暴露方式标准化，让客户端和工具服务器之间有更清晰的边界。
采用 MCP 或类似工具协议时要关注：
- 工具发现是否可控。
- 工具描述是否可信。
- 权限是否按用户和任务授权。
- 参数和返回是否可审计。
- 服务器是否可能泄露敏感信息。
- 工具调用是否有速率限制和预算。
不要把“能接 MCP”理解成“所有工具都能安全给 Agent 用”。协议解决连接问题，安全仍要系统设计。
4.13 Agent 失败条件
Agent 常见失败不是单点错误，而是多步复合错误。
| 失败类型 | 表现 | 预防 |
|---|---|---|
| 无限循环 | 反复调用同一工具 | 最大步数、重复检测 |
| 工具误用 | 参数错、工具选错 | 工具 schema 和 eval |
| 计划漂移 | 偏离目标 | 目标对齐检查 |
| 上下文污染 | 工具返回噪声影响决策 | 摘要和过滤 |
| 越权操作 | 调用无权限工具 | 系统权限控制 |
| 成本失控 | 多轮长上下文 | 预算和中止策略 |
| 幻觉行动 | 基于猜测执行 | 证据要求和人工确认 |
| 错误累积 | 前一步错导致后续全错 | 中间校验和回滚 |
4.14 Agent 评测
Agent 评测不能只看最终回答。必须看轨迹。
核心指标：
- 任务成功率。
- 工具选择准确率。
- 工具参数正确率。
- 平均步骤数。
- 平均成本。
- 平均延迟。
- 人类介入率。
- 失败恢复率。
- 越权拦截率。
- 最终输出质量。
轨迹 Rubric 示例：
| 维度 | 通过标准 |
|---|---|
| 目标保持 | 每步行动都能解释如何服务目标 |
| 工具选择 | 工具与子任务匹配 |
| 参数质量 | 参数完整、合法、最小必要 |
| 证据使用 | 关键结论有来源 |
| 安全边界 | 高风险动作被拦截或审批 |
| 终止判断 | 完成、失败或升级时机合理 |
5. 关键概念表
| 概念 | 含义 | 工程意义 | 常见问题 |
|---|---|---|---|
| Agent Loop | 观察、决策、行动、更新的循环 | 支撑多步任务 | 无限循环 |
| Workflow | 代码预定义流程 | 稳定可控 | 灵活性不足 |
| Tool | Agent 可调用外部能力 | 连接系统和环境 | 越权、误操作 |
| Tool Schema | 工具参数和返回定义 | 降低误用 | 描述模糊 |
| State | 任务进展对象 | 可恢复、可审计 | 当成聊天历史 |
| Memory | 跨步骤或跨任务信息 | 个性化和连续性 | 隐私、陈旧 |
| Plan Drift | 计划偏离目标 | 多步任务主要风险 | 无目标检查 |
| HITL | 人类在环 | 控制高风险动作 | 只做形式确认 |
| Trace | Agent 轨迹记录 | 调试和评测 | 只记录最终答案 |
| Guardrail | 规则、权限和预算控制 | 降低风险 | 只写在 Prompt |
6. 工程案例
6.1 只读代码库分析 Agent
目标：回答“这个功能在哪里实现，风险点是什么？”
工具：
- 文件搜索。
- 文件读取。
- 代码符号搜索。
- 测试结果读取。
边界：
- 不允许写文件。
- 不允许执行破坏性命令。
- 输出必须引用文件路径和行号。
评测：
- 是否定位正确文件。
- 是否遗漏关键调用链。
- 是否引用真实代码。
- 是否提出可验证风险。
6.2 研究资料整理 Agent
目标：围绕主题收集资料并生成简报。
工具：
- Web 搜索。
- 网页读取。
- 资料去重。
- 引用管理。
边界：
- 快速变化信息必须标注核对日期。
- 不可访问 paywall 或私有资料。
- 不能把未核实推测写成事实。
评测：
- 来源权威性。
- 引用覆盖。
- 信息时效性。
- 观点和事实分离。
6.3 工单辅助处理 Agent
目标：读取用户工单、查询订单状态、生成处理建议。
工具：
- 工单读取。
- 订单查询。
- 知识库检索。
- 创建处理草稿。
边界：
- 只创建草稿，不直接发送。
- 退款和赔付必须人工审批。
- 日志脱敏。
评测：
- 分类是否正确。
- 建议是否符合政策。
- 是否正确升级高风险工单。
6.4 受控退款申请 Agent
目标：根据用户投诉创建退款申请草稿。
工具：
- 查询订单。
- 查询退款政策。
- 创建退款草稿。
- 提交审批。
边界：
- 不允许直接退款。
- 退款金额必须由规则引擎校验。
- 用户身份和订单归属必须由系统校验。
评测：
- 是否正确识别退款资格。
- 是否创建完整草稿。
- 是否在证据不足时拒绝或升级。
6.5 数据分析 Agent
目标：根据业务问题查询数据并生成分析结论。
工具：
- 指标字典读取。
- SQL 草稿生成。
- SQL 只读执行。
- 图表草稿生成。
边界：
- SQL 只能只读。
- 大查询需要预算限制。
- 结论必须包含查询条件和时间范围。
评测：
- SQL 是否正确。
- 指标口径是否一致。
- 结论是否被数据支持。
7. 常见误区与反模式
| 反模式 | 表现 | 后果 | 修正 |
|---|---|---|---|
| 一上来多 Agent | 简单任务拆很多角色 | 成本高、难调试 | 从单调用或 workflow 开始 |
| 高权限工具裸奔 | 模型可直接退款、删除、发邮件 | 事故不可控 | 分级权限和审批 |
| 无最大步数 | Agent 一直搜索和尝试 | 成本失控 | max steps 和预算 |
| 状态靠聊天历史 | 历史越来越长 | 遗忘和污染 | 结构化状态 |
| 工具描述含糊 | 参数靠模型猜 | 调用失败 | schema、示例、错误码 |
| 不记录轨迹 | 只保存最终答案 | 无法复盘 | trace 每一步 |
| 人类审批太薄 | 只显示“是否确认” | 人无法判断 | 展示证据和影响 |
| 让模型判断权限 | Prompt 里写“不要越权” | 仍可能越权 | 系统层鉴权 |
| 记忆无限写入 | 什么都存 | 隐私和过时 | 写入策略和过期 |
| 工具返回全塞上下文 | 大段噪声进入模型 | 决策变差 | 摘要、过滤、引用 |
8. 阶段练习
8.1 工具 schema 练习
为以下工具写 schema：
- 搜索知识库。
- 读取订单。
- 创建工单草稿。
- 查询代码文件。
- 发送审批请求。
每个 schema 必须包含权限等级、是否幂等、错误码和示例输入。
8.2 只读 Agent Loop
写一个只读 Agent 伪代码，要求：
- 最大 8 步。
- 只允许搜索和读取。
- 每步记录 trace。
- 引用来源。
- 找不到证据时拒答。
8.3 写操作审批设计
为“退款申请 Agent”设计审批流程：
- 哪些信息进入审批卡片。
- 谁能审批。
- 审批后如何执行。
- 如何撤销。
- 审计日志记录什么。
8.4 失败轨迹分析
构造一个 Agent 失败轨迹，并标注：
- 哪一步偏离目标。
- 哪个工具调用错误。
- 哪个状态被污染。
- 哪个 guardrail 应该拦截。
- 如何加入 eval 防止复发。
8.5 Agent vs Workflow 判断
列出 5 个业务场景，判断用单次 LLM、Workflow、Agent 还是多 Agent，并说明成本、延迟、风险和评测方式。
9. 项目任务
9.1 项目要求
完成两个 Agent 设计或最小实现：
- 只读 Agent：能搜索、读取、汇总资料，输出带引用结论。
- 受控写入 Agent：只能创建草稿或申请单，必须人工确认后才进入真实写入流程。
必须包含：
- Agent 目标和边界。
- 工具列表和 schema。
- 权限分级。
- 状态对象设计。
- Agent loop 伪代码。
- Trace 字段设计。
- 人类在环流程。
- 10 条以上 eval 样例。
- 失败模式和防护策略。
9.2 设计文档模板
# Agent 系统设计文档
## 1. 业务目标
## 2. 为什么需要 Agent
## 3. Agent / Workflow 边界
## 4. 工具清单与权限
## 5. 状态和记忆设计
## 6. Agent Loop
## 7. 人类在环
## 8. Trace 与日志
## 9. 评测集和评分标准
## 10. 失败模式与降级
## 11. 安全和合规边界
9.3 评分标准
| 维度 | 分值 | 标准 |
|---|---|---|
| 场景判断 | 15 | 能解释为什么需要 Agent，而不是普通 Workflow |
| 工具设计 | 20 | schema 清晰，权限、错误、幂等完整 |
| 状态设计 | 15 | 状态可恢复、可审计、不过度依赖聊天历史 |
| 控制流 | 20 | 有最大步数、预算、停止和升级条件 |
| 人类在环 | 15 | 高风险动作展示证据、影响和可撤销策略 |
| 评测与安全 | 15 | 有轨迹 eval、失败模式和 guardrail |
10. 验收题
- Agent 和 Workflow 的核心区别是什么？
- 为什么很多场景不应该一开始就做 Agent？
- 一个 Agent loop 至少包含哪些步骤？
- 工具 schema 为什么比普通 API 文档更重要？
- 工具权限应该如何分级？
- Agent 状态和聊天历史有什么区别？
- 什么是计划漂移，如何发现？
- 人类在环审批卡片应该展示哪些信息？
- 多 Agent 什么时候值得引入，什么时候是反模式？
- Agent 评测为什么必须看轨迹而不是只看最终答案？
11. 延伸阅读
官方与权威资料
- Anthropic Building effective agents: https://www.anthropic.com/engineering/building-effective-agents
- OpenAI Agents SDK: https://developers.openai.com/api/docs/guides/agents
- Model Context Protocol: https://modelcontextprotocol.io/docs/getting-started/intro
- LangGraph overview: https://docs.langchain.com/oss/python/langgraph/overview
建议阅读方式
- 先读 Anthropic 的 agentic patterns，理解什么时候不要用 Agent。
- 再读 OpenAI Agents SDK 和 LangGraph，理解工具、状态和编排落到工程里的方式。
- 最后读 MCP，把工具连接和权限边界放进系统设计，而不是只看 demo。
12. 本阶段总结
Agent 的价值不在于“更像人”，而在于能在受控边界内根据环境反馈推进多步任务。它的核心不是神秘智能，而是控制流、工具接口、状态管理、权限、人类在环和轨迹评测。
你应该形成一个判断：Agent 越自主，系统越要确定。模型可以负责判断下一步，但系统必须负责权限、预算、审计、终止、回滚和评测。
下一阶段进入评测体系。你会学习如何证明一个 LLM、RAG 或 Agent 系统真的可靠，而不是只靠几个好看的 demo。