AI Agent 工程化与生产实践

• 基准的适用范围与局限
• 基准到生产的外推差异
• 生产基线的建立方法

这些基准（SWE-bench、WebArena、OSWorld）在固定数据集上衡量 Agent 的端到端任务完成率，是追踪模型能力的有效标尺，但数字不能直接当作生产成功率。原因：基准任务是静态、封闭、有确定答案的，而生产环境是动态、开放、噪声大、权限/工具异构的；基准的"环境"与生产系统（数据库、工具、权限、网络）差异巨大；基准流行度高、被优化甚至过拟合，数字会随代际快速上涨，不代表企业对真实业务同样有效；Demo 常选取最有利案例、人工辅助、不计失败，故表现远高于真实。因此应把基准作为"相对能力趋势"参照，建立企业自有评测集（真实业务轨迹 + 灰度抽样），用真实线上成功率、失败率与回滚率作为生产基线，并持续跟踪。

基准与生产之间隔着"环境差异、任务分布差异、过拟合膨胀"三重鸿沟。正确做法是"基准看趋势、自有集看真实"，把基准分数用于跟踪模型代际与选型，把线上真实指标用于生产基线，两者互补而非互相替代。

• 三大支柱的含义
• 观测工具的选型
• Dashboard 设计

三大支柱是：Token 成本（每次/每任务/每模型的 token 与金额，含思考 token）、任务完成率（成功/失败/部分完成的比例与耗时）、错误类型分布（循环、幻觉、工具失败、超时、参数错填等分类与占比）。用 Langfuse/LangSmith/Helicone 这类 LLM 观测平台，可自动抓取 trace（含 prompt、工具调用、token 用量、耗时、错误），并在此基础上构建 Dashboard：按租户/团队/功能维度聚合三大指标；用趋势图看完成率与成本随版本/模型/灰度变化；用错误分布图定位高频失败类型；设告警在成本或错误率超阈值时触发。关键是先定义"成功/失败/部分完成"的判定口径，再埋点采集，让三大支柱在同一 trace 上可追溯、可下钻。

可观测性不能只记"调用了模型"，而要记录完整轨迹与业务结果。三大支柱分别回答"花了多少、做成多少、为什么失败"，是 Agent 治理的基础。平台选型上，Langfuse/LangSmith 偏追踪与评测，Helicone 偏成本与中间层代理，可按需要组合。

• 识别四种常见失败模式
• 检测机制
• 熔断与回退策略

常见失败模式：循环（Agent 反复执行同一动作无进展）、幻觉（编造不存在的工具/数据/结果）、参数错填（调用工具时参数格式错误或取值错误）、工具超时（外部工具无响应或慢）。兜底链设计：检测层——步数上限、动作重复检测（hash 或相似度）、参数 schema 校验、工具调用超时与重试计数；熔断层——触发后停止继续投喂 token，返回当前中间结果或进入降级路径；回退层——回退到更简单模型、改用人工、或重试带修正（如把 schema 错误反馈给模型重新生成）。设计要点是"检测要快、熔断要果断、回退要可用"，并把每种失败类型用结构化字段记录，供统计与优化。

兜底链的本质是"让 Agent 在系统规则面前可被约束"。Agent 能力越强，越需要强制的规则兜底来防止失控。检测-熔断-回退三层分别负责"发现、止损、恢复"，缺一不可，且要按失败类型差异化处理（如超时重试、参数错填提示重写）。

• Multi-Agent 成本放大的原因
• 成本分摊模型
• 配额与治理机制

Multi-Agent 成本放大源于：多个 Agent 各自携带完整上下文、监督者与 Worker 间多次往返传递、每次调用都计费、以及重复的思考与工具调用。治理手段：按"任务/租户/团队"维度归集 token 与费用，建立成本分摊模型（如按调用次数、按 token、按业务价值权重）；为每个 Agent、每个任务、每个租户设置配额（token 上限、金额上限、最大调用次数）；用缓存与上下文压缩减少重复传递；对高成本路径做告警与熔断；把成本与任务完成率挂钩，评估"多花 3-10x 换来的质量提升是否值得"。治理关键是建立一个可分摊、可审计、可控的成本中心，让成本可归于业务单元并接受问责。

Multi-Agent 的收益（并行、分工、可编排）伴随成本放大。治理的核心不是"禁止多 Agent"，而是"让成本可归因、有上限、可评估 ROI"。通过配额、分摊与质量/成本比评估，决定哪些任务值得用 Multi-Agent。

• 必须人审的场景
• 置信度阈值设计
• 人审与 UX 的平衡

必须人审的步骤包括：影响财务/法律/医疗等高风险决策（转账、合同、诊断）、对外发布的正式内容（公关、监管披露）、涉及用户隐私与敏感数据的操作、以及模型不确定且后果不可逆的动作。置信度阈值设计上：对"必须人审"的场景设高置信度门槛（甚至 100% 总是人审），对可自动场景设低门槛；用"置信度 - 后果严重度"矩阵决定要不要人审。UX 平衡上，人审会产生等待与摩擦，应通过分批审核、异步队列、明确"待人工确认"状态、以及只对低置信度高后果项介入来减少打扰，同时把置信度透明化，让用户理解为什么要审。

HITL 的本质是"把不确定性交给人对冲"。哪些步骤必须人审，取决于"错误代价"而非"错误概率"；置信度阈值要随后果严重度动态调整。UX 上要把人审做成"顺滑的异常通道"而非"每步都打扰"。

• 状态分类
• 必须持久化的状态
• 可重建状态与重建策略

必须持久化的包括：对话上下文（用户与 Agent 的完整交互，用于续聊与追溯）、工具结果（外部调用返回的数据，供后续步骤复用，避免重复调用）、审批状态（HITL 是否已批准、待审队列）、以及 Agent 的执行计划与完成标志。可按需重建的包括：可通过重算/重新调用得到的中间结果（如可重算的摘要、可重新查询的实时数据）、日志级缓存、以及临时推理细节。重建策略是"轻量重建 + 关键断点持久化"：把关键断点（侧边效应、不可逆动作、审批结果）落盘，把可重算的中间状态留作缓存，降低持久化成本又保证一致性与可恢复。

状态持久化的核心是"区分副作用与中间结果"。有副作用、不可逆、跨会话的状态必须持久化；纯计算可重算的中间结果可重建。这既保证故障恢复与追溯，又避免过度持久化带来的存储与一致性问题。

• 上下文隔离
• 工具会话隔离
• 配额与并发限制

隔离目标：上下文隔离——每个会话拥有独立的上下文缓冲与 state，互不污染，避免会话 A 的提示词/工具结果泄漏到会话 B；工具会话隔离——每个会话/任务使用独立的工具凭证与会话（如独立的数据库连接、独立的 API token），避免不同任务的工具操作互相串扰；配额隔离——每个会话/任务/租户拥有独立的 token 配额、并发上限、调用次数上限与超时预算，防止单个任务耗尽共享的 GPU/API/成本池。实现上常用"会话级容器 + 配额管理器 + 资源门控"，为每个任务分配独立命名空间与限额，超限即熔断并告警，同时把共享资源（如总 QPS、总预算）做全局兜底。

并发隔离是 Multi-Agent 生产化的前提。上下文隔离保正确性，工具会话隔离保安全，配额隔离保公平与可用性。三者结合，才能让"一个任务出问题"不拖垮整个服务。

• 测试分层结构
• 各层的作用与工具
• CI 集成

Agent 测试分为三层：单元/工具层——用 mock 模拟工具返回，验证 Agent 对工具输入输出的解析、参数校验与错误处理，快速且稳定；轨迹层——把真实/历史轨迹快照记录下来，回放时固定工具结果为确定性数据，验证 Agent 在给定输入下是否产生期望的动作序列，适合回归测试；E2E 层——用 AgentBench 类评估集或自建业务集跑端到端完整任务，验证成功率与质量，最接近真实但慢且不稳定。CI 实践：MR 阶段跑单元/轨迹层（快、稳定、门禁），夜间或发布前跑 E2E 层（慢、覆盖全），并纳入发布门禁；用轨迹快照做回归，防止提示词/模型升级破坏既有行为。

三层测试对应"快-稳-真"的取舍。mock 层保证快速反馈，轨迹层保证行为可回归，E2E 层保证真实效果。把它们分层放进 CI 的不同阶段，能在"覆盖到位"与"反馈及时"之间取得平衡。

• 三种记忆的语义
• 记忆的读写与检索
• 协同机制

三种记忆分工：Working Memory 是当前会话的短期上下文，保存本轮的对话、状态与工具结果，随会话结束而清空；Episodic Memory 是用户的历史交互记录，用于记住用户偏好、历史操作与上下文，支持长期个性化；Semantic Memory 是结构化的事实/知识库，供 Agent 检索引用（如产品信息、用户档案）。协同机制：当前决策主要用 Working Memory，需要个性化时从 Episodic Memory 检索相关历史，需要事实时从 Semantic Memory 检索，把检索结果注入当前上下文，形成"当前上下文 + 历史记忆 + 知识库"的合成输入。工程上要设计统一的记忆接口，控制检索量、设置记忆写入时机与清理策略，并做权限与隐私控制。

层次化记忆的本质是"按需取用、存得当、放得对"。把易变的会话状态、可积累的历史、稳定的知识分开管理，能让 Agent 在短期准确性与长期连续性之间取得平衡，同时控制上下文长度与隐私风险。

• 长任务的上下文膨胀问题
• 压缩与关键事实提取
• 工具结果缓存

长任务会使上下文不断膨胀直至超限，导致成本上升与召回下降。工程实现包括：自动压缩——当上下文超过阈值时，把早期较不重要的消息总结成摘要，替换原文（摘要化/滚动窗口）；关键事实提取——从对话中持续抽取关键事实（用户需求、决策、约束）存入结构化记忆，检索时只注入相关部分，而非全量上下文；工具结果缓存——对相同参数的重复工具调用结果缓存，避免重复调用与重复注入；分层上下文管理，把"常驻摘要 + 按需检索的事实 + 当前活动块"组合。实现上需在每次写入/读取时做预算控制，保证窗口内始终是"最新 + 最关键"内容。

长任务的核心矛盾是"上下文越长越贵、越容易被稀释"。通过压缩、事实提取与工具缓存，把窗口从"全量累积"变成"关键信息分层管理"，才能支持超过 30 分钟的持续任务，同时控制成本与质量。

• 最小权限原则
• 外部内容的注入风险
• 指令隔离机制

工具权限按最小权限授予：只给 Agent 完成任务所必需的工具与数据范围，用细粒度权限（如只读、指定字段、指定库表、指定动作）而非宽泛授权；对高风险工具（转账、删除、发布）设二次确认或人工审批；为不同任务/会话用独立凭证，避免权限扩散。外部内容注入隔离：把系统指令、用户输入、外部内容（网页/文档/工具结果）用清晰的标记与区块分隔，如用 XML 标签/special token 包裹，并明确"外部内容不可执行指令、不可覆盖系统规则"；对工具返回做边界处理，不信任其内容中的指令；用输入校验与输出过滤双重防护，防止间接注入。核心是"系统指令是最高优先级，外部内容永远是数据"。

最小权限与指令隔离是 Agent 安全的两块基石。前者限制"能做什么"，后者限制"被什么影响"。通过凭证隔离、细粒度授权与内容边界标记，把 Agent 的破坏面与被诱导面都压到最小。

• 预算控制手段
• 最大步数限制
• 上下文压缩与结果裁剪

预算控制手段：最大步数——为每个 Agent 任务设置最大工具调用/推理轮数，防止无限循环；上下文压缩——对累积的对话做摘要化或滚动窗口，控制每次请求的输入长度；工具结果裁剪——对大块工具返回（如长文档、大表格）只保留关键字段、摘要或分页截断，避免把全量结果塞进上下文；在每个步骤对 token 使用做计数与告警，超预算即熔断或降级。工程上把"任务级 token 预算"设为硬约束，结合"步骤级压缩"与"结果级裁剪"，既保证任务能完成，又避免预算失控。

多轮 Agent 的 token 消耗是"每轮放大"的，预算必须全链路控制。最大步数防失控，压缩防膨胀，裁剪防溢出，三者配合让单任务成本可预期、可上限。

• 三维度指标
• 自有评测集构建
• 发布门禁

三个维度：任务完成率——任务成功/部分成功/失败的比例与质量；效率——完成任务所需的步数、时间、工具调用次数；成本——token 消耗、计算费用、人工介入次数。三者独立评估，避免"高完成率但高成本"或"低成本但低质量"被掩盖，可组合成综合评分。企业自有评测集构建：从真实生产轨迹中采样代表性任务，人工标注期望结果与判定标准（含边界与失败案例），覆盖不同模型/场景/难度，定期扩充；纳入发布门禁：在 CI/CD 中跑评测集，对三个维度分别设定门槛（如完成率不低于 X、平均成本不高于 Y），任一不达标即阻断发布，并给出对比报告支持决策。

仅看完成率会误导 Agent 的选型与优化。三个维度分别回答"成不成、快不快、贵不贵"，企业自有集解决"基准与生产脱节"，门禁解决"评测不落地"。这样才能让 Agent 的改进可量化、可问责。

• 轨迹记录的内容
• 复现与定位能力
• 结构化事件设计

应记录结构化事件序列：每次思考（对应的输入/输出/耗时）、每次工具调用（工具名、参数、返回结果、耗时、成功/失败）、重试（重试次数、原因、退避）、以及终止原因（正常完成、超时、循环、步骤上限、错误）。此外记录每次请求的完整上下文快照、token 用量、模型版本与配置。有了这些事件，故障时可按"事件回放"完整复现 Agent 的执行轨迹，定位循环（看到反复相同动作）、误调用（看到参数错误或不该调用的工具）、以及失败点（看到终止原因与当时上下文）。工程上应把轨迹导出为可检索的日志与可回放的快照，并做关联 ID 串联。

轨迹是 Agent 的"黑匣子"。记录"想什么、调什么、结果如何、为何终止"四类事件，配合上下文快照与版本信息，才能让故障可复现、可定位、可对照修正。这是可观测性与调试的基础。

• 状态快照与恢复
• 幂等性保障
• 副作用去重

恢复：在关键步骤（每次工具调用前后、每次状态变更）持久化状态快照，崩溃后从最近快照恢复，重放未完成的步骤。防重复执行副作用：为每次副作用调用生成唯一幂等键（idempotency key），工具侧记录已执行键，重复请求命中时直接返回已有结果而不重复执行；对不可幂等的操作（转账、发送、删除）用"先查询再执行"或"两阶段提交"（先登记意图，确认后再执行）；加上"已执行/进行中/已取消"状态机，避免并发或恢复导致的重放。核心是"副作用必须幂等化 + 执行前登记"，让快照恢复不会重复扣费或重复操作。

崩溃恢复与幂等是 Agent 状态机的一体两面。快照保证"能恢复"，幂等保证"恢复不闯祸"。对不可逆副作用，幂等键 + 状态机 + 先登记后执行是标准做法，可防止重复执行与重复扣费。

• 三种恢复方式
• 重放边界
• 恢复策略

恢复方式：检查点——在关键步骤保存状态，从中断点直接继续；重放——从某个检查点重新执行后续步骤，弥补中断期间可能丢失的中间结果；人工接管——Agent 无法自行恢复时，把任务转交人工处理。重放边界应确定为"从最近一个无副作用、状态完整的检查点开始"，且重放区域内的所有副作用操作必须幂等，避免重复执行；有几个关键判定：重放的开端要在"已确认一致的状态"之后，重放的终点是"中断点"，对重放区域内的不可逆操作应跳过或转人工确认。选择哪种方式取决于中断阶段与任务性质：纯计算可重放，有副作用需从幂等检查点继续或人工接管。

中断恢复的关键是"边界+幂等"。边界决定"从哪重放"，幂等决定"重放是否安全"。把检查点、重放与人工接管作为递进策略，让不同类型的任务都能可靠恢复，同时避免重复副作用。

• 组合发布的版本管理
• 版本绑定策略
• 一键回滚

Agent 行为由 Prompt、工具 Schema、模型与知识库共同决定，任何一项变化都可能改变输出。因此要建立"组合版本"：把 Prompt 版本、工具 Schema 版本、模型版本（含参数）、知识库版本（含索引版本）绑定成一个 Agent 版本号，发布时原子提交。实现上：所有组件用版本控制的制品（如配置库/镜像/对象存储），发布时写入版本清单并做灰度；回滚时把整个组合版本回滚到上一个已发布清单，保证"一键回滚"还原的是完整一致的组合而非部分组件。配合兼容性测试（该组合在评测集上的表现）与流水线门禁，确保每个版本可复现、可审计、可回退。

Agent 的"版本"是多个可变组件的组合，单独回滚某一项会导致不匹配。组合版本 + 原子发布 + 一键回滚，让 Agent 的演进可管理、故障可恢复，避免"改了知识库但模型还是旧的"这类错配。