# 工程化：可靠性、安全、资源与评估 Demo 展示的是 Agent 能做什么；系统设计关注的是 Agent 什么时候不能做。 一个能运行的 Agent Demo 和一个可上线的 Agent 系统之间，隔着一系列工程化问题：目标怎么定义清晰、失败了怎么恢复、人应该介入哪些环节、安全边界在哪里、资源消耗如何控制、推理深度怎么选择、探索任务如何不发散。这些不是模型能力能解决的，而是系统设计问题。 ## 上篇：可靠性与安全 ### 目标设定：没有验收标准就没有可靠性 Agent 必须知道自己要达成什么，也必须知道什么叫完成。目标模糊是 Agent 失败的主要原因之一，而不是模型能力不足。 一个完整的目标应该包含四个维度： ```text 任务目标：要交付什么 质量标准：正确、完整、风格、格式、性能、安全 约束条件：预算、时间、权限、不可触碰范围 停止条件：何时结束，何时升级给人 ``` **目标分解框架** 从模糊到可执行，需要一个分解过程： ```text 模糊目标：优化页面性能 → 第一步：澄清范围 只优化首页首屏加载 → 第二步：量化指标 当前 Lighthouse Performance 分数 65，目标 85 加载时间从 3.2s 降低到 2.5s 以内 → 第三步：设定边界 不改变视觉结构 不使用新框架 不引入破坏性变更 → 第四步：定义验收 跑 Lighthouse 验证 手动回归关键路径 无控制台错误 ``` **验收标准的量化方法** 验收标准应该是可测量的： - 时间指标：加载时间、响应时间、处理时长 - 质量指标：测试覆盖率、错误率、通过率 - 资源指标：Token 消耗、API 调用次数、成本上限 - 约束指标：不修改的文件、不触碰的配置、保留的功能 常见反模式： - "优化页面"式模糊目标：没有边界，无法判断完成 - "尽快完成"式时间约束：没有具体期限 - 缺少停止条件：不知道什么时候该停下来 - 缺少升级条件：不知道什么时候该求助 ### 异常处理：失败要可分类、可恢复 Agent 系统必须假设失败一定会发生。异常处理不应该只是一句"重试"，而是要按失败类型决定恢复动作。 **异常分类体系** ```text 临时错误 - 网络超时 - API 限流 - 服务暂时不可用 → 恢复策略：限次重试 + 指数退避 权限错误 - 文件访问被拒 - API 密钥无效 - 操作权限不足 → 恢复策略：请求授权或降级方案 数据缺失 - 必需字段不存在 - 文件找不到 - 依赖服务无响应 → 恢复策略：补充检索或声明边界 计划失败 - 执行路径不通 - 前置条件不满足 - 预期结果未达成 → 恢复策略：重新规划或放弃当前路径 安全风险 - 提示注入检测 - 敏感操作识别 - 越权访问尝试 → 恢复策略：停止并上报人工 验证失败 - 输出不满足规则 - 测试未通过 - 格式不符合要求 → 恢复策略：回滚或修复后重试 ``` **恢复策略矩阵** 每个异常类型应该有明确的恢复动作： ```text 异常类型 | 重试 | 退避 | 降级 | 重规划 | 人工 -----------------|------|------|------|--------|----- 网络超时 | ✓ | ✓ | | | 权限不足 | | | ✓ | | ✓ 数据缺失 | | | ✓ | ✓ | 计划失败 | | | | ✓ | ✓ 安全风险 | | | | | ✓ 验证失败 | ✓ | | | ✓ | ``` **重试策略** 不是所有错误都适合重试： - 临时错误：限次重试（3-5次），指数退避（1s, 2s, 4s, 8s） - 权限错误：不应重试，需要解决权限问题 - 数据缺失：不应简单重试，需要补充信息 - 计划失败：不应重试相同计划，需要重新规划 **什么时候放弃当前计划** 以下情况应该触发重规划： - 连续三次执行失败 - 单步执行时间超过预期阈值 - 中间结果与预期严重偏离 - 发现了之前未知的约束条件 常见反模式： - 统一"重试"：所有错误都用重试处理 - 忽略异常类型：不区分失败原因 - 不记录失败上下文：无法分析根因 - 无限重试：消耗资源而不收敛 ### Human-in-the-Loop：把人放在高杠杆节点 Human-in-the-Loop 不是让用户频繁点确认，而是在高风险、高歧义、高价值的位置引入人类判断。 **适合人工确认的节点** ```text 目标确认 - 任务范围是否正确 - 验收标准是否清晰 - 约束条件是否完整 不可逆操作 - 删除文件、数据库记录 - 部署到生产环境 - 发送邮件、通知客户 - 修改权限配置 合规相关 - 涉及个人数据处理 - 需要审计的操作 - 合同、承诺相关动作 方案取舍 - 多个可行方案存在明显权衡 - 技术选型需要业务判断 - 资源分配需要优先级决策 语义判断 - 自动验证无法覆盖的内容 - 需要业务背景的判断 - 主观质量评估 ``` **人工确认的选择框架** 可以用"风险 × 价值 × 可逆性"来决定是否需要人工确认： ```text 高风险 + 低可逆性 → 必须人工确认 高价值 + 多方案取舍 → 建议人工确认 低风险 + 高可逆性 → 可以自动执行 ``` **过度确认的代价** - 效率损失：频繁打断执行流程 - 用户疲劳：过多确认导致用户习惯性点击通过 - 价值稀释：真正重要的确认被淹没 **确认不足的代价** - 失控风险：关键操作无人审核 - 信任崩塌：一次严重错误就会毁掉用户信任 - 修复成本：事后修复比事前确认昂贵得多 **实践案例：部署 Agent 的人工确认设计** ```text 自动执行： - 读取部署配置 - 运行测试 - 构建镜像 - 推送到测试环境 需要确认： - 部署到生产环境 - 数据库迁移 - 配置变更 - 回滚操作 分级确认： 低风险变更：单次确认 高风险变更：双人确认 紧急回滚：简化确认流程 ``` ### 护栏：贯穿生命周期的安全层 护栏不是一个单独模块，而应该贯穿 Agent 生命周期的每个阶段。 **输入护栏** ```text 风险分类 - 识别请求的风险等级（正常、敏感、危险） - 高风险请求触发额外审核 权限检查 - 验证用户是否有权限执行请求的操作 - 检查是否越权访问资源 提示注入防护 - 检测对抗性输入 - 过滤试图绕过规则的指令 ``` **过程护栏** ```text 工具门控 - 危险工具需要额外授权 - 限制工具调用的频率和范围 权限范围 - 动态限制每次操作的权限 - 最小权限原则 预算限制 - Token 消耗上限 - API 调用次数限制 - 成本阈值告警 ``` **输出护栏** ```text 敏感信息检查 - 检测是否泄露隐私数据 - 过滤机密信息 事实引用 - 关键结论需要引用来源 - 区分事实和推断 合规校验 - 检查输出是否符合规范 - 验证是否有法律风险 ``` **护栏设计模式** ```text 白名单模式 - 只允许明确的操作 - 适合高风险场景 黑名单模式 - 禁止明确的危险操作 - 适合低风险场景 评分阈值 - 对操作打分，超过阈值触发审核 - 灵活性高，但需要调优 人工升级 - 检测到不确定情况时升级给人工 - 平衡自动化和安全性 ``` 常见反模式： - 只在入口加护栏：执行过程缺乏控制 - 护栏过于严格：系统变得不可用 - 护栏过于宽松：起不到保护作用 - 护栏硬编码：难以适应新场景 ### 评估与监控：上线后才是真测试 Agent 的评估不能只看单次输出好不好。需要建立完整的评估和监控体系。 **评估集构建方法** ```text 标准任务集 - 覆盖主要成功路径 - 包含常见使用场景 - 验证基本功能正确性 对抗任务集 - 越权尝试 - 提示注入 - 误导性输入 - 异常边界情况 回归任务集 - 过去失败过的真实案例 - 已知缺陷的验证 - 新版本可能破坏的功能 ``` **监控指标体系** ```text 业务指标 - 任务成功率 - 失败率 - 人工介入率 - 用户修正次数 技术指标 - 平均延迟 - P95/P99 延迟 - Token 消耗 - API 调用次数 成本指标 - 单次任务成本 - 日/月总成本 - 资源利用率 稳定性指标 - 回滚次数 - 错误率波动 - 服务可用性 ``` **A/B 测试策略** ```text 对比维度 - 新旧 Agent 版本 - 不同推理深度 - 不同工具组合 - 不同确认策略 评估指标 - 主要指标：成功率、用户满意度 - 次要指标：成本、延迟、人工介入率 - 负面指标：错误率、回滚次数 实验设计 - 分流策略：随机分流或基于特征分流 - 样本量：确保统计显著性 - 实验时长：覆盖完整使用周期 ``` **失败案例沉淀为测试** 每个生产环境的失败都应该： - 记录完整上下文 - 分析根因 - 生成测试用例 - 加入回归测试集 - 验证修复效果 常见反模式： - 只看单次输出质量：忽略了系统性问题 - 缺少对抗测试：无法发现安全漏洞 - 上线后无监控：无法发现真实问题 - 没有回归测试：重复犯同样的错误 ## 下篇：资源与推理 ### 资源感知：智能不是无限预算 Agent 的资源包括 Token、时间、API 调用次数、工具成本、上下文窗口、并发额度、人类注意力和外部系统负载。资源感知优化的核心是：不同任务不应该消耗同样预算。 **Agent 的资源清单** ```text 计算资源 - Token：输入 + 输出 - 上下文窗口：最大可携带信息量 - 模型调用次数：API 请求开销 时间资源 - 单任务超时 - 总执行时长 - 用户等待时间 财务资源 - API 成本 - 工具使用成本 - 人力成本 系统资源 - 并发额度 - 外部服务负载 - 存储空间 ``` **资源分层策略** 按任务风险和复杂度分配不同预算： ```text 简单低风险 - 快速模型（Haiku/小参数） - 少工具调用 - 短上下文 - 轻量验证 - 示例：文档问答、代码补全 中等复杂 - 标准模型（Sonnet/中参数） - 必要检索 - 标准验证 - 示例：代码生成、数据分析 高风险复杂 - 强模型（Opus/大参数） - 完整计划 - 多轮验证 - 人工关口 - 示例：生产部署、架构设计 ``` **Token 预算管理** ```text 预算设定 - 根据任务复杂度设定上限 - 预留安全边际（实际使用 < 80% 预算） 消耗追踪 - 实时监控 Token 使用 - 预警机制（达到 70% 发出警告） 超预算处理 - 触发重规划：寻找更经济的路径 - 降级策略：简化输出、减少验证 - 升级人工：请求用户决策 ``` **模型路由** 不同任务选择不同能力的模型： ```text 快速任务 - 简单问答 - 格式转换 - 文本摘要 → 路由到轻量模型 推理任务 - 代码生成 - 问题分析 - 方案设计 → 路由到标准模型 复杂任务 - 架构设计 - 多步推理 - 高价值决策 → 路由到强力模型 ``` 常见反模式： - 所有请求走最高规格：成本不可控 - 所有请求走低成本路径：高价值任务失败 - 不追踪资源消耗：无法优化 - 预算设定不合理：要么过高浪费，要么过低无法完成 ### 推理技术：按问题选择推理深度 推理技术不是越复杂越好。选择合适的推理深度，是效率和质量的平衡。 **常见推理方式** ```text 分步推理 - 适用：多步骤依赖问题 - 特点：逐步分解、链式验证 - 成本：中等 树状探索 - 适用：多方案需要比较 - 特点：并行探索、择优选择 - 成本：高 反事实比较 - 适用：需要验证假设 - 特点：假设验证、排除错误路径 - 成本：中等 生成-批判循环 - 适用：需要迭代优化 - 特点：生成方案、批判改进 - 成本：高 约束求解 - 适用：严格规则约束 - 特点：在约束空间内搜索 - 成本：低-中 案例类比 - 适用：有相似先例 - 特点：参考历史、类比推理 - 成本：低 ``` **推理方式选择决策树** ```text 问题类型判断 │ ├─ 是否有严格规则约束？ │ ├─ 是 → 约束求解 │ └─ 否 → 继续 │ ├─ 是否有相似先例？ │ ├─ 是 → 案例类比 + 快速验证 │ └─ 否 → 继续 │ ├─ 是否需要多步依赖？ │ ├─ 是 → 分步推理 │ └─ 否 → 继续 │ ├─ 是否有多个候选方案？ │ ├─ 是 → 树状探索 │ └─ 否 → 直接执行 │ └─ 是否需要迭代优化？ ├─ 是 → 生成-批判循环 └─ 否 → 一次性生成 ``` **推理深度与任务风险的匹配** ```text 低风险任务 - 轻量推理即可 - 重点是快速响应 - 示例：文档查询、格式转换 中风险任务 - 标准推理深度 - 平衡速度和质量 - 示例：代码生成、数据分析 高风险任务 - 深度推理 + 多重验证 - 重点是正确性 - 示例：架构设计、生产变更 ``` **关键原则：推理服务于证据** 很多工程任务不需要模型"想很久"，需要的是： - 先读真实文件 - 运行真实测试 - 查看真实错误 - 获取真实反馈 推理应该服务于证据，而不是替代证据。 常见反模式： - 简单问题过度推理：浪费资源 - 复杂问题推理不足：质量不够 - 纯模型推理无外部验证：容易产生幻觉 - 推理与执行分离：推理结果无法落地 ### 优先级排序：先做最能降低不确定性的事 Agent 经常面对一堆可能动作：查资料、写代码、跑测试、问用户、重构、部署、回滚。优先级排序决定了系统是否有效。 **不确定性下降排序法** 问自己：哪个动作最能减少后续错误？ ```text 排序原则 1. 阻塞项：不做这个就无法继续 2. 高风险验证：早发现早修复 3. 高价值产出：尽快交付核心价值 4. 润色优化：最后再做 ``` **实践案例：改代码前的优先级决策** ```text 场景：用户要求"优化查询性能" 错误顺序： 1. 直接改代码 2. 跑测试发现失败 3. 发现理解错了需求 4. 重写代码 正确顺序： 1. 先读现有代码（了解现状） 2. 跑性能分析（找到瓶颈） 3. 确认优化目标（对齐预期） 4. 改代码 5. 验证效果 ``` **排序框架** ```text 阻塞项 → 必须先做 - 缺少必要信息 - 依赖未就绪 - 权限未获取 高风险验证 → 尽早做 - 可能推翻当前假设的验证 - 成本高但影响大的验证 - 失败后果严重的检查 高价值产出 → 尽快做 - 核心功能实现 - 关键路径任务 - 用户最关心的部分 润色优化 → 最后做 - 代码格式调整 - 性能微调 - 文档完善 ``` 常见反模式： - 按想到的顺序做：缺乏优先级 - 先做容易的：把难的留到最后 - 同时做多件事：切换成本高 - 不做风险评估：踩到地雷才发现 ### 探索与发现：开放式任务要有边界 探索模式适用于目标不完全清晰、路径未知、需要发现新信息的任务，例如市场调研、代码库摸底、论文综述、故障定位、产品机会分析。 探索的风险是发散。一个没有边界的 Agent 可以一直搜索、一直总结、一直发现新问题。 **可控探索的六要素** ```text 时间预算 - 最多花费多少时间 - 单个步骤的超时时间 - 示例：30分钟内完成调研 来源范围 - 从哪些来源获取信息 - 限制搜索空间 - 示例：只查看官方文档和 GitHub issues 产物格式 - 输出应该是什么格式 - 需要包含哪些信息 - 示例：结构化表格 + 关键发现列表 停止条件 - 什么时候停止探索 - 什么算"足够好" - 示例：找到3个可行方案即停止 发现优先级 - 什么信息更重要 - 如何权衡深度和广度 - 示例：优先找真实案例，其次找理论分析 不确定性标注 - 哪些是确认的事实 - 哪些是推测 - 哪些还需要验证 ``` **探索结果的结构化输出** 探索不是最终交付，而是为后续决策提供地图。探索结果应该明确区分： ```text 事实 - 已确认的信息 - 有明确来源 - 可验证 推断 - 基于事实的推测 - 合理但未验证 - 需要标注不确定性 待验证 - 需要进一步确认的点 - 存在疑问的地方 - 建议的验证方法 ``` **探索与执行的边界** 探索结果应该： - 提供决策依据，不是做决策 - 给出多个选项，不偏向任何一个 - 标注不确定性，不做过度承诺 - 建议下一步，不强制执行 常见反模式： - 无边界探索：时间无限制、来源无限制 - 探索结果无结构：混杂事实和推断 - 探索与执行混淆：探索阶段就做决策 - 不确定性未标注：把推测当事实 ## 权衡篇：成本-质量-速度三角 工程实践中，成本、质量、速度三者存在根本性张力。你无法同时优化三者，必须根据场景做取舍。 **三者之间的根本性张力** ```text 提高质量通常需要： - 更多计算资源（增加成本） - 更多验证步骤（降低速度） - 更强模型（增加成本） 提高速度通常需要： - 跳过部分验证（降低质量） - 使用更快模型（可能降低质量） - 并行执行（增加成本） 降低成本通常需要： - 使用更小模型（可能降低质量） - 减少验证步骤（降低质量） - 串行执行（降低速度） ``` **不同场景下的优先级选择** ```text POC / 原型阶段 - 优先：速度 - 接受：质量可妥协 - 策略：快速迭代，小步验证 内部工具 / 辅助场景 - 优先：成本 - 接受：速度可妥协 - 策略：经济模型，必要时人工介入 核心业务 / 生产环境 - 优先：质量 - 接受：成本可增加 - 策略：强模型 + 多重验证 + 人工审核 用户面向 / 竞品场景 - 优先：质量 + 速度 - 接受：成本可增加 - 策略：强模型 + 并行化 + 缓存优化 ``` **工程实践中常见的权衡决策** ```text 模型选择 - 强模型高质量高成本，弱模型相反 - 决策依据：任务价值、错误容忍度 验证策略 - 多重验证高质量高成本，单次验证相反 - 决策依据：任务风险、失败代价 并行化程度 - 高并行高速度高成本，串行相反 - 决策依据：时间要求、资源预算 人工介入 - 多介入高质量低速度，少介入相反 - 决策依据：任务复杂度、用户容忍度 ``` **权衡的动态调整** 同一个 Agent 系统中，不同任务可以有不同的权衡策略： ```text 用户查询 → 快速响应为主 代码生成 → 质量优先 生产部署 → 质量绝对优先 内部报告 → 成本优先 ``` 关键是根据任务特征动态调整，而不是一套参数打天下。 ## 总结 Demo 展示的是 Agent 能做什么；系统设计关注的是 Agent 什么时候不能做。 可靠性不是靠提示词承诺出来的，而是靠： - 清晰的目标和验收标准 - 完善的异常分类和恢复机制 - 合理的人工介入节点 - 贯穿生命周期的安全护栏 - 完整的评估和监控体系 - 感知的资源管理和推理策略 - 有边界的探索和发现 这些工程化能力，才是让 Agent 从 Demo 变成可上线系统的关键。