你猜一个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.3Schema缺少约束模型随意填参数上下文利用率注入上下文中被实际使用的比例已使用上下文块数 / 注入上下文块总数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: stringdescription写的是“开始日期”。结果模型经常传成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 caseAgent-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换再大的模型也只是换了一个更聪明的迷路者。