你猜一个Agent最容易翻车的地方在哪？不是模型推理能力不够，也不是prompt写得不好，而是它根本够不到该用的东西。我过去三个月一直在调一个企业内部AI助手，工具函数从20个膨胀到120个之后，模型开始频繁选错工具、填错参数，甚至把函数名也改得面目全非。为了让这个烂摊子变回工程问题，我写了一套叫Agent-Reach的评测与诊断框架，专门量化Agent在真实工具环境下的触达能力。这套框架的完整复盘如下，包括指标定义、架构思路、真实失败案例，以及怎么把整套逻辑接进日常迭代流程。
1. Agent-Reach的由来：先有“够不到”的痛，才有这把尺子
1.1 从20个工具到120个工具，问题突然爆发
项目刚起步时，我的第一版Agent只挂了20个内部工具，仓库查询、订单创建、客户资料、优惠券核销，基本都是些语义边界很清晰的函数。那时候模型表现相当稳定，该调get_order_detail就调get_order_detail，很少跑偏。我当时还天真地以为，只要把工具描述写得规范一点，工具调用问题就可以一劳永逸。
等到业务方开始接入更多后台系统，工具数量冲到三位数以后，情况急转直下。最典型的是两个功能几乎重叠的工具：update_stock和adjust_inventory。前者是更新某个商品SKU的实时库存值，后者是手动调整因盘点差异产生的库存修正值，底层接口完全不同，但在模型看来它们都叫“改库存”。结果就是，一批补货任务反复调错工具，数据对不上，业务反馈“这个Agent有毒”。
我最初还怀疑是模型版本不够强，去试了更新的模型、改了几版Prompt，效果都只是暂时好转。后来把几十条失败日志摊开对比，才意识到问题的本质不是“模型不会”，而是“模型够不到”——工具列表太长太像，描述信息太多太杂，模型在做工具选择时根本没有办法在有限上下文里做出稳定判断。也就是从那一刻起，我开始认真考虑做一个独立于业务代码的“触达能力”度量体系。
1.2 为什么叫Reach：触达不只是“调用成功”
Agent-Reach这个名字，核心是一个很直白的反问：一个智能体在给定的工具、知识和上下文条件下，到底能触达多少有效资源？这里说的“触达”不是网络代理那一类概念，而是AI Agent在决策过程中对资源的发现、理解和使用能力。
我把触达拆成三个层面。第一是发现，模型能不能从一堆候选工具里感知到那个正确的工具存在；第二是理解，模型看到工具描述和参数说明之后，能不能正确理解它的职责边界；第三是保持，多轮对话和多次工具调用之间，关键信息能不能一直留在有效上下文里。任何一个层面出问题，最终表现都是Agent“够不到”该用的东西，但根因可能完全不同。
为什么单独把这三个层面抽出来做一套工具？因为常规的端到端评测只能告诉我们“任务成功还是失败”，无法告诉我们失败发生在哪一层。Agent-Reach则像一把尺子，把“触达”这件事量化出来，让每一个失败都能被归因到具体环节。这个定位从一开始就决定了它的架构不会太重，但要足够精准，足够能定位问题。
2. 三条核心指标：把“触达能力”变成可量化的数字
2.1 工具可达率：Agent到底能发现多少工具？
触达能力的第一个量化切口，是工具可达率。我不想直接叫“工具调用准确率”，因为一个任务里Agent可能调很多次工具，其中有些调用是探索性的，算进去反而稀释了信号。Agent-Reach的做法是只统计“核心工具决策”：每个评测任务预先定义一条黄金路径，比如“用户要查库存并下单补货”，核心决策就是调用query_stock，订单创建可能才是第二步。我们只看这些关键决策点上的工具选择对不对。
工具可达率的公式很简单：
Tool_Reachability = (correct_tool_decisions / required_tool_decisions) × 100%
比如一个包含50个核心工具决策的评测集里，模型有42次选对了正确工具，工具可达率就是84%。这个数字一旦低于80%，基本不用查日志就能判断：工具列表的“可发现性”存在系统性问题。
这里有一个容易被忽略的细节：工具可达率一定要和“候选工具数量”一起看。同样的85%，在20个工具的环境里可能是Prompt词序问题，在120个工具的环境里则可能是工具命名体系有结构性缺陷。Agent-Reach在输出报表时会同时列出当前工具总量、相似工具对数量，用这个背景信息辅助判断指标高低。
2.2 参数命中率：就算看到了工具，参数给对了吗？
工具选对了，不代表万事大吉。第二个常见触达缺口发生在参数层：模型发现了update_stock，也决定调用它，但把customer_id填成了user_id，把日期格式从2024-03-01写成了2024/03/01。这种失败在端到端评测里会被归类为“任务失败”，但浪费的其实是一个触达机会。
参数命中率的计算思路是把每个核心工具调用的参数逐一拆开。必填字段只要出现类型错误、缺失或明显错值，整个参数调用就算失败；关键可选字段则按比例计分。我会给必填字段更高权重，常见做法是：
Param_Hit_Rate = (required_ok / required_total) × 0.7 + (optional_hit / optional_used) × 0.3
举个例子，一个工具需要product_id、quantity和warehouse_id三个必填字段，其中两个传对了，第三个月失去了，必填命中是2/3。如果还有一个可选字段remark没有填，我们不计负分，但会记录“可选字段未使用率”。这能帮我们发现模型是不是只满足最低要求，而忽略了本该填的上下文信息。
参数命中率的特殊价值在于，它能把问题定位到“Schema设计”而不是“模型能力”。很多参数错误并不是模型智障，而是开发者在工具描述里没有给足约束和示例。Agent-Reach每次发现参数命中率骤降，我都会优先怀疑最近有没有人改过工具Schema，而不是急着换模型。
2.3 上下文利用率：信息放进去了，Agent真的读到了吗？
第三个指标是上下文利用率，也是Agent-Reach里最“反直觉”的一个。很多时候我们把检索结果、工具返回、历史对话一股脑塞进上下文，以为模型会雨露均沾，实际上它可能只盯着最中间的某一段信息，其他内容全部视而不见。
Agent-Reach会把注入的上下文切成有标记的“块”，比如“用户指令”“库存API返回”“RAG文档第1段”“订单历史摘要”。评测结束后，后台会检查模型在最终输出或工具参数里到底使用了哪些块里的关键信息。如果一个任务注入了5个上下文块，模型实际只用了第2块，那么上下文利用率就是20%。
这个指标对RAG类Agent尤其致命。我见过一个任务，RAG检索返回了10段文档，模型最终只用了其中第7段的一个数字，其他9段全都成了噪音。上下文利用率直接反映了“信息过载”问题：塞得越多，模型越容易迷路。Agent-Reach并不会直接告诉你“应该删掉哪段”，但它会把“用到/没用到”的块标识得清清楚楚，让优化动作有的放矢。
| 指标 | 定义 | 计算方式 | 典型问题 |
|---|---|---|---|
| 工具可达率 | 核心决策中正确选择工具的比例 | 正确工具决策数 / 需要工具决策总数 | 工具太多太像，模型发现不了目标工具 |
| 参数命中率 | 工具调用参数正确填充的比例 | 必填字段命中率0.7 + 可选关键字段命中率0.3 | Schema缺少约束，模型随意填参数 |
| 上下文利用率 | 注入上下文中被实际使用的比例 | 已使用上下文块数 / 注入上下文块总数 | RAG结果过载，核心信息被淹没 |
3. Agent-Reach的运行链路与埋点设计
3.1 一次评测的完整流程
Agent-Reach做评测的思路很朴素：把真实交互过程搬到可复现的沙箱里，用固定任务集去反复打，最后对比输出和预期。完整流程大概分七步：
- 准备评测任务集，每个任务都带有用户请求、初始上下文、黄金工具路径。
- 冻结当前工具注册表，包括所有工具的名称、描述、参数Schema。
- 为每个任务注入初始上下文，比如RAG片段、用户历史信息、系统指令。
- 让Agent在受控环境中执行任务，全程记录每一次模型原始输出和工具调用。
- 后台把模型行为与黄金路径比对，自动标注“对/错/偏差”。
- 汇总指标并生成报告，输出异常任务明细。
- 评测结果归档，作为后续回归对比的基线。
这套流程里最容易被偷懒跳过的是第二步。工具Schema哪怕只改一个词，Agent的行为就可能发生剧烈变化。如果不冻结，今天跑出来的分数和昨天跑出来的分数根本没有可比性。Agent-Reach每次跑评测前都会先读取工具注册表，并保存一份JSON快照，确保任何指标波动都能追溯到具体的Schema变更。
3.2 工具注册表与Schema快照
工具注册表是Agent-Reach的地基。它不只是简单列出一堆函数名，而是把“模型实际看到的工具描述”完整托管起来。下面是一个典型的工具Schema：
{ "name": "update_stock", "description": "更新指定仓库中某商品的库存数量。当用户提到补货、库存调整、手动修正时使用。", "parameters": { "type": "object", "properties": { "product_id": { "type": "string", "description": "商品ID，格式如PDT-1001" }, "quantity": { "type": "integer", "description": "变更后的库存数量，必须大于等于0" }, "warehouse_id": { "type": "string", "description": "仓库编号，格式如WH-SH-01" } }, "required": ["product_id", "quantity", "warehouse_id"] } }这里有一个我很在意的点：description的正数第二句常常被写成“当用户提到补货、库存调整、手动修正时使用”，这种“触发条件”写法比单纯的功能描述有效得多。模型在做工具匹配时，本质上是把用户意图和工具描述做语义对齐，越像“用户这句话会触发我”的描述，越容易被选中。
Agent-Reach每次评测都会给这套注册表生成一个哈希值，并存进报告元数据。如果之后工具描述被调整，Git提交记录和评测报告就能互相印证，我甚至可以精确知道“改了某一个字段后，工具可达率上升了还是下降了”。
3.3 埋点字段：把决策过程完整留下来
评测框架如果不记录过程，只输出一个总分，那跟黑盒没区别。Agent-Reach在每个工具调用节点都会写一条结构化日志，字段设计尽可能贴近原始观测：
{ "task_id": "task_001", "step": 2, "model_raw": "我需要先查询当前库存数量，因此调用 update_stock", "selected_tool": "update_stock", "expected_tool": "update_stock", "arguments": { "product_id": "PDT-1001", "quantity": 5, "warehouse_id": "WH-SH-01" }, "expected_arguments": { "product_id": "PDT-1001", "quantity": 5, "warehouse_id": "WH-SH-01" }, "error": null, "context_blocks": ["user_instruction", "stock_api_result", "rag_doc_2"], "used_blocks": ["user_instruction", "stock_api_result"] }model_raw这一字段尤其重要。很多Agent框架会直接解析模型输出成工具调用，如果解析失败就报错，原始的“模型想说什么”反而被丢掉。但Agent-Reach要求必须留下模型的原始文本，因为模型有时候并没有真正决定调工具，只是“自言自语”提了一嘴，解析层却误判成了工具调用。没有原始输出，这种误判根本无从排查。
配合日志里的expected_tool和expected_arguments，任何一次失败都能直接对比“模型做了什么”和“应该做什么”。整个排查过程从猜谜变成了看报告。
4. 五类典型触达失败复盘：真实case里的根因
4.1 案例A：工具描述“长而全”反而让模型找不到入口
我们的第一个典型失败来自一个叫get_multi_channel_inventory_report的工具。这个工具的description写了三行，详细描述了它能生成哪些渠道的库存汇总、支持哪些筛选条件、返回哪些维度。看起来信息很全，但实际效果极差。
Agent-Reach跑完评测后，我发现凡是涉及“查看库存汇总”的任务，模型总会去调get_inventory而不是这个多通道报表工具。单看工具可达率，从84%掉到了61%。排查过程很直接：我把评测保存在快照里的工具列表导出，模拟模型当时看到的上下文，发现长描述在真实环境下被截断了。模型只能看到前半句“获取多通道库存报……”，它无法判断这是不是用户要的汇总报表，于是退而去调用名字更短、看起来更通用的get_inventory。
修复方案是把description压成一句话：“汇总各渠道当前库存总数，返回报表ID。当用户要求查看全国/多渠道库存汇总时使用。”细节全部下沉到参数的description里。改完之后，同一个评测集里的工具可达率回升到了93%。这个教训后来写进了团队规范：工具描述第一行必须写清“做什么+什么时候用”，超过40个token就要警惕。
4.2 案例B：参数类型不匹配，JSON Schema写对了也会翻车
第二个案例更隐蔽。我们的订单查询工具有一个start_date参数，Schema里标注了"type": "string"，description写的是“开始日期”。结果模型经常传成"2024/03/01"这种中间用斜杠的格式，而后端接口只认"2024-03-01"。
端到端测试里这类错误会被归为“模型不会用工具”，但Agent-Reach的参数命中率数据显示，必填字段命中率只有60%左右。仔细看日志才发现，模型并不是不知道要填日期，而是没有从Schema里得到足够强的格式约束。它把“开始日期”理解成日常口语里的日期表达，而不是一个严格ISO格式字段。
修复动作很粗暴但有效：在参数description里加上“格式：YYYY-MM-DD，示例：2024-03-01”，同时在后端兼容解析层做了一层兜底，能识别斜杠和中文日期。但我不会把兼容层当作正式方案，因为它在短期解决了送达问题，却让模型失去了学习正确Schema的机会。Agent-Reach的定位就是把这些错误暴露出来，逼着开发者在源头修掉。
4.3 案例C：多轮调用时状态“断片”
第三种失败发生在多步任务里。Agent先调用create_order拿到了order_id，第二步应该用这个order_id去查物流轨迹。结果在评测集里，第二步调query_tracking时，order_id参数频繁变成null，或者干脆传成了订单金额。
第一反应是模型上下文记忆不行，但Agent-Reach的上下文利用率日志揭示了一个更具体的问题：在上一步工具返回结果里，order_id确实存在，但它埋在了一长串订单确认信息中间。模型在生成下一步参数时，尝试从上下文里重新定位order_id，却选中了另一个看起来很像ID的数字。
解决方案不是让模型“记得更牢”，而是把关键状态从冗长的工具返回里抽出来，显式注入到下一步的System Prompt里。我在工具返回后增加了一个“状态槽”，专门保存订单ID、用户ID这类核心实体，并让Agent-Reach把“状态槽内容是否被使用”单独记录。改造后参数命中率回到了96%。很多时候Agent触达不了，不是它不想，而是上下文里没有一个干净可靠的信息入口。
4.4 案例D：外部API限流，Agent触达成功但执行失败
这个案例比较特殊，它甚至不是Agent的问题。某个外部供应链接口短期流量激增，频繁返回429限流错误。Agent-Reach的指标非常好看：工具可达率100%，参数命中率100%，但任务成功率只有35%。
我一度觉得Agent-Reach没用了，因为它衡量的是“触达”，而这个环节明明触达了，却还是失败。直到我看了日志，才发现问题恰好出在触达的定义上。Agent确实“够到了”工具，但工具背后的外部服务没有真正“被够到”。这是一个执行层问题，不是决策层问题。
Agent-Reach随后增加了一个指标分层：把“决策成功”和“执行成功”分开统计。决策成功是模型选对了工具、填对了参数；执行成功是工具真正正常返回结果。429风暴里决策成功100%，执行成功率惨不忍睹，问题边界一下子就清晰了。后来我们给外部接口加了重试、缓存和降级策略，执行成功率才慢慢回升。这个案例也让我明白，一个评测框架必须清楚自己测量的是哪一层，否则很容易把“工具本身坏了”的锅扣在Agent头上。
4.5 案例E：上下文被检索结果挤爆，核心指令丢失
最后这个案例来自RAG场景。为了提升回答质量，我们把向量检索返回的10段文档全部塞进了上下文，结果Agent开始抽风：该调工具的时候不调，反而开始“根据我对文档的理解”直接编答案。
Agent-Reach的上下文利用率指标给出了非常冰冷的反馈：注入的上下文块有12个，模型实际只用了2个，其中还不包括工具说明块。更糟糕的是，由于检索结果太长，工具调用规范被挤到了上下文的边缘位置，模型已经“看不见”它了。
修复不是继续压Prompt，而是做了一个很痛的决定：限制检索结果的注入数量，从10段砍到最多5段，并增加一个重排步骤，把可能含有关键答案的段优先放到中部位置。同时把“如果用户有明确操作意图，必须调用工具”这句话重新抬高到上下文靠前区域。改完之后，上下文利用率从16%升到了58%，工具可达率也同步回升。过量的上下文看起来是“更多触达”，实际上反而压缩了真正的触达空间。
| 失败模式 | 主要症状 | 排查方式 | 首选修复 |
|---|---|---|---|
| 描述过长截断 | 工具可达率骤降 | 对比模型真实接收的工具描述快照 | 描述首行写结论和触发条件 |
| 参数格式不匹配 | 参数命中率偏低 | 查看日志中的原始arguments | 在参数描述中给示例与格式约束 |
| 多轮状态丢失 | 后续工具参数为null | 检查上下文利用率和状态槽 | 显式注入关键状态变量 |
| 外部限流 | 决策成功但执行失败 | 拆分决策成功与执行成功指标 | 重试、缓存、降级策略 |
| 信息过载 | 上下文利用率极低 | 统计上下文块使用情况 | 压缩检索结果并重排上下文结构 |
5. 把Agent-Reach嵌进开发流程：回归测试与持续优化
5.1 构建评测集：不要只拿happy path当标准
Agent-Reach要发挥作用，评测集的质量决定了它的上限。一开始我只放了20个“正常任务”，都是用户意图明确、应该调用某个工具就能完成的场景。跑了几轮发现指标好看得离谱，但上线后照样翻车，原因很简单：真实用户不会按评测集的标准出牌。
后来我把评测集分成了三类。第一类是正向调用任务，要求必须调用某个工具，这类用于衡量基本可达能力。第二类是可选调用任务，模型可以调用工具也可以直接用已有知识回答，这类用来测“会不会过度调用工具”。第三类是禁止调用任务，比如用户只是问了一句“这个功能多少钱”，根本不需要调库存API，模型如果调了就算触达错误。
这三类任务的比例大概控制在6:2:2。还要专门加入一组“易混淆任务”，故意挑工具描述相近的场景，比如update_stock和adjust_inventory。没有这些hard case，Agent-Reach很容易变成一个报喜不报忧的摆设。评测集建好后，所有方案改动都要先在它上面跑分，再谈上线。
5.2 在CI里跑Reach回归：分数波动就是告警
Agent-Reach真正开始发挥工程价值，是在接入CI/CD之后。现在团队里任何人改动工具Schema、调整系统Prompt，或者升级模型版本，都必须跑一次Reach回归测试。我把它做成了一个独立命令：
agent-reach run --suite core-suite --config config.yaml --report report.json agent-reach diff --baseline baseline.json --current report.json --threshold 0.02第一条命令跑完测试并生成当前报告，第二条命令把当前报告跟基线对比。如果工具可达率或参数命中率下降超过2个百分点，流水线直接标红，阻止合并。这个阈值不是拍脑袋定的，我观察了两周的历史波动，正常改动带来的浮动基本在1个百分点以内，只有真正出了问题才会超过2。
这里面最容易被忽略的是“基线”的选择。我一开始用“上一次提交的分数”作为基线，结果两个低分提交之间比来比去，什么问题都发现不了。后来改为手工确认一个“稳定版本”作为长期基线，任何改动都要跟它比。虽然开始会有点麻烦，但回归测试的语义立刻清晰了：改动只会让触达能力变好或变坏，不存在“跟上次比还行”的侥幸。
5.3 从今天就能做的三个优化动作
如果暂时不想搭建完整的Agent-Reach流程，也可以先做三个低成本的优化动作，它们都是我在这三个月里被坑过后总结出来的。
第一个动作，工具描述第一行写结论。不要把功能细节、参数规则、注意事项全堆在description里。第一行必须回答两个问题：这个工具做什么，什么时候该用。如果你发现第一行里出现了逗号套逗号，那就是在挑战模型的解析能力。
第二个动作，参数Schema里给示例值。尤其是日期、ID、枚举类型这三个高频翻车点。"date": "2024-03-01"这样一个示例，能替代十行描述文字。对模型来说，示例比规则更容易理解。
第三个动作，把上下文结构固定成模板。用户指令放最前，然后是核心系统约束，工具定义紧随其后，RAG检索结果放最后。这样即使检索内容很长，也不会挤占模型对工具规范的注意力。上下文不是越多越好，而是越有结构越好。
6. 边界与取舍：Reach分数高不等于Agent好用
6.1 什么时候Reach不是核心瓶颈
Agent-Reach解决的是“够得到”的问题，但一个Agent好用不好用，还取决于很多和触达无关的因素。如果任务本身不依赖外部工具，用户问一句，模型用常识回答一句，那Reach指标几乎没有参考价值。这时候把精力花在上下文压缩、检索质量上，都比花在工具触达上更有意义。
还有一种情况，Reach分数很高并不意味着产品体验好。一个工具可达率95%的Agent，可能会因为回复太啰嗦、语气不对、逻辑跳跃，照样让用户觉得难用。Agent-Reach只负责回答“资源有没有被用上”，至于“资源被用上之后结果好不好”，那是另一套端到端质量评估体系的事。
我自己吃过这方面的亏。有一段时间团队把Reach分数当成北极星指标，为了冲高分，给每个工具都加了冗长的触发条件描述，结果Agent倒是能正确选工具了，但响应速度慢了一倍，用户投诉率上升。后来我才意识到，任何单一指标被过度优化，都会以另一种形式反弹。触达是必要条件，不是充分条件。
6.2 不要做成Agent-Reach全家桶
Agent-Reach在发展中也踩过“过度设计”的坑。最初，团队成员提议把延迟监控、成本统计、模型质量评测、安全合规检查全部塞进Agent-Reach，做成一个“Agent平台监控全家桶”。我坚决否掉了一部分，原因很简单：如果一个框架什么都能测，它就会变得什么都测不准。
价值主张必须聚焦。Agent-Reach只做三件事：测量触达、暴露触达失败、辅助定位触达根因。延迟和成本交给其他监控系统，回答质量交给LLM-as-Judge，安全合规交给独立的审核框架。多出来的指标不是不好，而是会稀释框架本身的判断力。每增加一个指标，报告的可读性和维护成本都会指数级上升。
我现在对Agent-Reach的定位是“一把手术刀”，而不是“瑞士军刀”。它要有足够的锐度去切开问题，而不是面面俱到地掩盖问题。这个边界意识，可能比框架本身的代码更重要。
6.3 我的落地体会和一个小心思
最后分享一个我做这个项目最大的体会：别急着写一万行框架，先拿着20个最真实的任务把指标跑起来再说。Agent-Reach的第一版其实就是一个Python脚本，每天手动跑一遍，把结果贴到群里。那时候它连“框架”都算不上，但它已经能帮我和团队成员快速定位问题了。很多工程问题，不是缺少复杂工具，而是缺少一个愿意被重复使用的简单度量标准。
还有个小心思，我后来在所有工具的description里加了一个“当用户提到……时使用”的触发条件前缀。看起来只是描述习惯的小改动，却让工具可达率在120个工具的环境下从71%直接跳到了84%。模型在做匹配的时候，非常吃“意图信号”这一套。你可以把工具描述当成UI设计来打磨，而不是当成接口文档来写，这个视角转换会带来很明显的效果差异。
如果你也在被同类问题困扰，建议先别急着换模型，试着把“Agent够不到”这件事测量出来。毕竟，一个连该用的东西都够不到的Agent，换再大的模型也只是换了一个更聪明的迷路者。
