先交代一句背景我过去一年半基本都在做大模型 Agent 相关的应用从 RAG 到工具调用再到多智能体协作踩过的坑比写过的代码还多。前阵子团队内部做了一个叫 Agent-Reach 的小项目本来只是为了一次线上事故做的排查工具结果越做越完整最后成了我们每次发版前必跑的体检流程。这篇文章就是想把 Agent-Reach 的核心设计、落地方式和踩坑经验完整写出来给同样在做 Agent 应用的朋友一个参考。先说清楚 Agent-Reach 是做什么的。名字拆开来就两半Agent 指智能体Reach 是触达、达到的意思。用大白话说Agent-Reach 就是一个用来回答我的 Agent 到底能触达多少东西的诊断框架。这里说的触达包括三种一是模型能不能从工具列表里正确选中该用的工具二是任务所需的关键信息有没有真正进入模型的上下文窗口三是多智能体场景下任务能不能从一个 Agent 完整流转到下一个 Agent。实际开发中这三个环节任何一个出问题表现都是同一种Agent 答非所问、反复调用同一个工具、或者干脆假装工作。这篇文章会从设计思路、指标定义、完整接入流程到问题排查一步步展开。适合几类人看正在做 Agent 应用但总发现模型行为不稳定的工程师准备给团队搭建 Agent 质量评估体系的技术负责人以及被上下文怎么都喂不够、工具怎么都调不对折磨的 AI 应用开发者。如果你是纯小白只要懂基本的 Python 和大模型 API 调用也能跟着实操部分把 Agent-Reach 跑起来。1. 为什么 Agent 开发最怕够不着先说清楚 Reach 是什么1.1 从一次线上事故说起工具链明明完整Agent 却答非所问今年年初我们上线了一个给企业销售团队用的 Agent功能不复杂销售拿着手机上的应用跟 Agent 说话询问客户资料、最近跟进记录、待办任务Agent 背后接了 CRM、知识库、日历三个系统一共开放了 12 个工具函数。上线前功能测试全部通过但灰度到真实用户后差评率飙升。最典型的反馈是用户问小李那个单子上周聊到哪了Agent 回答了一大段 CRM 里根本没有的内容甚至开始编造客户意向。我们当时第一反应是模型幻觉换成更强的模型、加了更严格的 system prompt问题反而更诡异——模型开始频繁调用一个搜索客户的工具然后说找不到数据。后来我们拉日志逐帧回放才发现问题根本不在于模型能力而在于工具可达性用户说的小李在 CRM 里存的是姓名拼音字段Agent 的对话历史里只有自然语言形式没有映射到实际查询参数同时知识库工具的描述写得像毕业论文摘要模型根本不知道该在什么场景下调用它。工具链条全是完整的但 Agent够不着——这就是 Reach 问题。那次事故之后我意识到一件事传统的准确率、召回率评估对 Agent 这种环境交互型系统根本不适用。你需要衡量的不是答得对不对而是在整个调用链条里Agent 有没有能力触达到正确的上下文、正确的工具、正确的结果。Agent-Reach 就是围绕这个思路搭起来的。1.2 Agent-Reach 要解决的三类触达问题设计 Agent-Reach 之前我们把 Agent 运行时的失败模式做了归类最终收敛成三类触达问题。第一类是工具触达Tool Reach。模型有一份工具清单每个工具都有函数名、参数描述、调用说明。工具触达衡量的是给定一个用户意图模型能不能从清单中选对工具、填对参数、并按正确的顺序调用。选错工具、参数缺字段、把字符串格式的日期传给时间函数全算工具触达失败。第二类是上下文触达Context Reach。现代 Agent 几乎都是检索增强 上下文填充的结构把相关资料塞进 prompt 让模型读取。上下文触达衡量的是关键信息有没有真正进入模型可读取的窗口。注意我这里说的是可读取不是被写进 prompt——很多系统把资料写进了 prompt但被截断、被排在无关内容后面、或在多轮对话中被系统消息覆盖模型实际上没看到这就是触达失败。第三类是网络触达Network Reach。多智能体架构下一个任务会被拆分成多个子任务分发给不同 Agent然后汇总。网络触达衡量的是任务在 Agent 之间的流转质量和完整性——上游 Agent 的输出有没有完整地作为下游 Agent 的上下文任务状态有没有在传递中丢失。Agent-Reach 的全部指标体系都围绕这三类触达来设计。它不是一个推理框架也不是一个运行时而是一个体检工具——像体检报告一样告诉你当前系统的触达率是多少、短板在哪个环节、具体的失败样本是什么。1.3 适用人群与使用场景结合我自己的经验Agent-Reach 最适用的两类场景一类是开发诊断。新功能开发完毕、准备上生产之前跑一遍 Agent-Reach 的完整诊断流程。它会自动模拟一批高频用户请求追踪整个调用链路上的工具命中、上下文填充和任务流转情况然后给出每个环节的可达率。如果某个环节低于设定的阈值会直接输出对应的失败用例和链路日志。另一类是回归监控。Agent 上线后prompt 调整、模型版本切换、知识库更新、工具函数参数变更任何一项变动都可能影响触达效果。单独靠人工回归测试根本测不过来Agent-Reach 可以做成 CI 的一部分每次变更后自动跑一轮用分数变化来感知行为退化。如果你是团队里一个人负责维护 Agent 的全栈工程师这套东西也完全值得落地——一个工具集大概两三天就能接进来便宜、无侵入不需要改动现有 Agent 的核心逻辑。2. Agent-Reach 的核心设计四个指标看懂智能体的触达能力2.1 工具可达率模型能不能正确选中工具工具可达率是 Agent-Reach 最基础的一级指标定义很简单在 N 次测试请求中模型成功调用了正确工具的比例。[ ToolReach \frac{CorrectToolCalls}{TotalRequests} \times 100% ]关键在于怎么判定正确。我们内部把它拆成三层判定任何一个层次不合格都算失败Tool ID 命中模型选中的工具函数是否就是预期工具。如果预期是 get_crm_contact模型选了 search_knowledge_base直接 Fail。参数完整性选中工具后必填参数是否都被正确填充。缺一个必填参数算 Fail。参数语义准确性参数虽然填了但值对不上。比如预期传入的是客户 ID CUST-1024模型传成了 CUST-1024 带空格或把日期格式从 ISO 8601 传成 2024/1/5这类都算语义错误。实际项目里三层判定用不同颜色标记在报告里绿色是完全通过黄色是参数语义偏差红色是工具选型或参数缺失。这样一看就知道是不会选还是不会填这是后续针对性优化的关键。2.2 上下文覆盖率关键信息有没有被塞进窗口第二个指标是上下文覆盖率它衡量的不是 prompt 里塞了多少内容而是任务所需的关键实体有没有出现在模型的输入上下文中。做法是这样的我们在测试数据集里给每个请求预先标注好关键实体——比如用户查询涉及客户名 小李、日期 上周、状态 跟进中。Agent-Reach 在执行完一次完整推理后抓取实际发送给模型的 prompt 文本包括 system prompt、工具描述、检索结果、对话历史然后逐个实体验证以下三件事实体是否出现在最终 prompt 里出现在哪个区域头部 / 中部 / 尾部通常中部和尾部容易被截断是否被完整引用比如客户名被截断了一半也算失败。然后是覆盖面计算[ ContextCoverage \frac{FoundEntities}{RequiredEntities} \times 100% ]这个指标最大的价值在于能迅速定位检索质量差和上下文管理差的区别。如果实体压根没被检索出来那是 RAG 链路的问题如果检出来了但被截断在上下文窗口之外那是上下文管理策略的问题——两种问题的解决方向完全不同。2.3 对话触达深度多轮任务中的链条完整度单轮工具调用的触达相对好验证真正让人头疼的是多轮对话。用户往往会这样帮我查下李总那个单子Agent 查出客户视图——顺便把他最近三封邮件摘要给我Agent 需要复用上一轮得到的客户 ID——再帮我把明天的会议改成线上Agent 需要同时用到客户 ID 和日历工具。对话触达深度衡量的是多轮任务中跨轮信息传递的完整度。每轮任务结束后Agent-Reach 会给当前上下文做一个状态快照记录当前轮次中哪些实体已经确定、哪些工具结果已经被引用、哪些中间变量还在继续被下游消费。然后进入下一轮时检查上一轮的关键状态是否有延续。如果上一轮已经拿到客户 ID这一轮模型却重新问了一遍用户是哪一个李总说明跨轮触达断裂。计算上我们用[ DepthReach \frac{Continuations}{PromotableState} \times 100% ]说起来很抽象但跑一次真实测试就明白了。我们内部见过最典型的低分场景就是第一轮模型正确调用了 get_crm_contact 拿到客户 ID第二轮因为 system prompt 被压缩直接把第一轮的输出丢出了上下文窗口模型被迫失忆从第二轮的视角看第一轮所有成果都白做了。2.4 多智能体协作触达任务流转是否顺畅多智能体架构下的触达问题比单 Agent 更隐蔽。我们遇到过这样的案例一个客服 Agent 把任务转给退款处理 Agent信息表里明明有退款单号但处理 Agent 收到的输入上下文里只有用户 ID退款单号丢了处理 Agent 只能重新让用户提供一次。Agent-Reach 在多智能体场景下做的是任务合约验证。每个 Agent 之间会定义好交接协议——下游 Agent 接收什么字段、上游必须传递什么字段。Agent-Reach 在每次交接时比对实际传递的数据结构和约定协议逐字段检查是否完整、格式是否一致、是否为占位符比如 None、unknown。网络触达指标就是这些交接协议字段的通过率[ NetworkReach \frac{PassedFields}{AttemptedFields} \times 100% ]这个指标在实际测试中经常会拉低整体分数而且往往跟代码 bug 无关而是设计层面的字段命名不一致——上游 JSON 里写 customer_id下游 Agent 的 prompt 里写 userId模型没法自动对齐两套命名体系。Agent-Reach 的作用就是把这个隐隐约约觉得不对的问题变成明确的红色数字。3. 实操用 Agent-Reach 给现有 Agent 做一次触达体检3.1 安装与初始化Agent-Reach 我们用了相当轻量化的设计没有重型依赖核心就是一个 Python 包 一组 YAML 配置文件。安装方式pip install agent-reach装完之后初始化一个诊断工作区agent-reach init --dir ./reach_workspace这会在当前目录生成三个关键文件config.yaml全局配置包括大模型 API 端点、密钥、要诊断的 Agent 类型testcases.yaml测试用例集每条测试用例对应一个用户请求和期望行为report_template.md报告模板。初始化完成后要对 config.yaml 做两处必改配置。第一处是模型接入配置model: provider: openai model_name: gpt-4o temperature: 0.2 max_tokens: 4096第二处是目标 Agent 的定义。Agent-Reach 不限制你用什么框架只要提供两个东西工具函数清单和调用入口。工具函数清单用于第一步的工具可达率判断调用入口用于实际执行测试请求。agent: invoke_endpoint: http://localhost:8000/agent/invoke tool_schema_path: ./tools/schema.json context_snapshot_prefix: CONTEXT_SNAPSHOT注意这个 context_snapshot_prefix 字段。为了实现上下文覆盖率的检查Agent-Reach 需要在运行时从日志中还原实际发送给模型的 prompt。一个通用做法是在 Agent 调用链里加入一个日志中间件把最终拼好的 prompt包括所有插入内容以某个固定标记开头打印到日志中Agent-Reach 从日志里解析出这一段文本。如果你不想改代码也可以直接把 prompt 导出逻辑做成一个 hook只要是启用了快照前缀Agent-Reach 都能识别。3.2 编写第一个可达性探测用例testcases.yaml 是 Agent-Reach 的灵魂格式设计得有点像单元测试用例的参数化版本。一条完整的测试用例包含三个部分- id: reach_001 description: 查询指定客户的最近跟进记录 input: 帮我查一下李总上周的跟进情况 expected_tools: - tool_name: get_crm_contact param_check: name: required: true alias: [小李, 李总] - tool_name: get_follow_up_records param_check: contact_id: alias_field: get_crm_contact.result.customer_id required_context_entities: - entity_name: customer_name value: 李总 search_region: ALL expected_conversation_depth: 2我来解释一下这段配置的意图。expected_tools 定义了该请求期望被调用的工具序列。param_check 里除了要求工具名命中还要求 get_follow_up_records 的 contact_id 参数必须来自 get_crm_contact 的返回结果用 alias_field 表示跨工具传递链路。这个字段是 Agent-Reach 非常关键的设计它能检测出模型是否正确地进行了链式调用——而不是从第一个工具的结果里抄了一个看似对应的 ID随后编造后续调用。required_context_entities 定义了上下文覆盖率检查所需的实体。这条用例里要求 李总 必须以完整形式出现在 prompt 中。如果你在测试中发现实体存在但只停留在对话历史的原始用户输入中而没有进入检索结果或工具返回Agent-Reach 同样会判定不通过因为模型实际依赖的上下文并没有真正把实体推到可推理的位置。expected_conversation_depth 这里填写 2表示这条需求需要两轮交互才能完成——第一轮查客户第二轮查跟进记录。如果模型第一轮就宣称完成了全部任务对应的深度评分就会折算失败。编写测试用例时有一个经验不要贪多先从你的核心业务高频请求里挑 20 到 30 条每条覆盖一个完整意图然后根据跑出来的失败样本持续补充边界用例。我见过团队一上来就写 500 条用例跑完一遍发现全是低质量的边界场景淹没了很多真实的问题。3.3 跑完诊断之后怎么读报告配置好之后执行诊断agent-reach run --config ./reach_workspace/config.yaml --cases ./reach_workspace/testcases.yaml --output ./reach_workspace/report.mdAgent-Reach 会逐个测试用例执行请求实时记录工具调用链、上下文快照、多轮状态最终生成一份 Markdown 报告。报告开头是一份总分表测试批次工具可达率上下文覆盖率对话深度网络触达综合得分批次 2024-05-1276%58%64%82%70%综合得分的计算我们用了加权平均权重可以根据业务侧重点调整。比如销售场景的工具可达率权重就调得高一些客服场景的多轮触达权重会调高一些。权重配置在 config.yaml 的 scoring 字段里scoring: tool_reach: 0.35 context_coverage: 0.25 depth_reach: 0.20 network_reach: 0.20报告的重点肯定不是这个总分而是失败样本明细。每一条失败的测试用例都会附带两个东西完整调用链日志和一个失败原因标签。比如你看到这样的输出FAIL reach_003 查询李总上周跟进情况 原因标签: tool_param_missing (参数缺失) 真实调用序列: get_crm_contact(name李总) - OK get_follow_up_records(contact_id) - FAIL (参数为空) 现场prompt片段: ... get_follow_up_records(contact_id: string, required) ...这就非常直观问题不是出在工具选型而是参数传递环节模型调用了 get_crm_contact 拿到客户信息后没有把 customer_id 正确提取出来传给下一个工具。根据这个日志你可以快速定位到是解析逻辑的问题还是 prompt 中工具描述的格式问题。报告还有一个容易被忽略的板块上下文覆盖率逐实体明细。它会列出每个实体是否出现、出现在 prompt 的哪个 token 位置、距离结束符还有多少 token。我们曾经靠这个板块发现了一个重大隐患某些长文档测试用例中客户姓名被排进上下文第 7000 token 的位置而模型当时配置的 max_tokens 是 8192从计算上看这个 token 应该仍然在窗口内但模型实际生成时优先读取了尾部指令中间位置的关键实体权重被稀释——这种问题在传统评估中根本不会被发现。4. 常见问题与排查技巧实录4.1 问题速查表把 Agent-Reach 落地到不同项目的过程中我们沉淀了一张高频问题速查表基本覆盖了 80% 的触达不到场景。症状可能原因优先排查方向工具可达率低且失败集中在工具选型工具描述过于抽象、区分度不够改写每个工具 description强调使用场景和正反例工具可达率低且失败集中在参数缺失参数描述不完整缺少格式示例在参数描述中显式标注枚举值、格式、示例值上下文覆盖率低实体被截断上下文管理策略过于简单按顺序堆叠内容引入上下文优先级排序关键实体前移上下文覆盖率低实体根本没出现RAG 检索质量差召回不足检查 embedding 分词策略和 top_k 设置对话深度低第二轮失忆多轮状态没有持久化或者被新内容挤出窗口启用 conversation memory 管理模块定期压缩早期内容网络触达低交接字段丢失上下游 Agent 的命名和格式协议不一致统一交接 schema用 Pydantic 模型强约束网络触达低字段值变成占位符上游 Agent 输出 unknown / None 等占位值增加上游输出校验禁止占位值流入下游所有指标都挺高但用户仍不满意测试用例和真实分布相差太大从真实用户日志中挖掘新的测试用例这里特别想展开说一下工具描述的写法。很多团队在注册工具函数时description 写得特别偷懒比如{ name: get_crm_contact, description: Get CRM contact }这种描述对模型来说几乎没有任何区分度。我建议的写法是场景化描述 参数格物化描述 负向提示三者结合{ name: get_crm_contact, description: 查询 CRM 系统中的客户信息。当用户提到具体客户姓名、公司名或销售线索时调用此函数。不要使用该函数查询历史跟进记录那属于 get_follow_up_records 的职责。, parameters: { name: { type: string, description: 客户姓名支持中文姓名、拼音及常见别名如李总、小李、LI YUAN。 } } }负向提示可以大幅减少模型误调工具的频率。很多模型在工具选择上特别贪心看到查询两个字就想用 search 类工具。这时候明确告诉它这不是什么往往比这是什么管用得多。4.2 三个我踩过的坑第一个坑把 Agent-Reach 当成了模型能力测试器。刚开始我们用它去对比不同大模型的 Agent 能力比如 GPT-4o 对 Claude 3.5分数差一点就开始怀疑模型。后来跑了半个月才发现分数差异根本不来自模型推理能力而来自我们对每个模型配置的 prompt 风格不一样——工具描述措辞的微小差异就会让可达率差出十几个百分点。现在我们的原则是固定一套 prompt 模板和工具描述再对比模型否则对比的其实是 prompt 风格而不是模型能力。第二个坑测试用例里混入了后见之明。早期我们写 expected_tools 时容易受自己知道正确路径影响给某个请求只标注了一条理想调用链但实际上业务允许两三条完全合理的路径。比如查客户信息既可以直接走本地缓存也可以实时调 CRM API两个工具都算正确选择。Agent-Reach 的 expected_tools 支持多路径配置用 alternatives 字段列出可接受的替代工具序列。不配置的话就像用一把呆板的尺子量柔性任务误报率高得吓人。第三个坑上下文快照的日志量比想象中大。加了 context_snapshot_prefix 日志中间件后每个请求都会多打一份完整 prompt 副本单个请求可能几 KB 到几十 KB线上高并发场景下日志成本暴涨。我们后来把快照抽成独立的异步日志流只保留测试流量和低比例线上采样流量才把成本压住。如果你只想做回归监控建议在测试环境开全量快照生产环境开 1% 采样够用。最后再分享一个经验Agent-Reach 跑出来的分数别只看绝对值重点看趋势。同一个测试批次这周 70 分下周 65 分中间可能只是改了一版本 RAG 的 top_k 配置。Agent-Reach 最有价值的地方不是告诉你现在有几十分而是让你在发版前及时发现这次改动让触达能力退化了——这一点比任何花哨的评估指标都实在。