过去一年我一直在折腾AI Agent相关的评测与落地最大的感受是模型能力已经上来了但智能体到底能跑多远、能覆盖多少真实任务、在什么边界上会崩很多人心里没数。Agent-Reach这个名字起得很准——它要测量的正是智能体的可达范围。你可以把它理解成一套面向AI Agent的“能力疆域测绘系统”针对目标环境的任务集全集统计你的智能体在多大比例上能被可靠地触达并完成。这套东西解决的不是“单个任务准不准”而是“整体覆盖广不广、边界在哪里、投入产出划算不划算”的问题。适合正在做Agent落地选型、做RAG或工具调用优化、或者准备把智能体接入业务系统的人参考。下面是我从0到1搭建和使用Agent-Reach的完整记录包括设计思路、指标拆解、实操步骤和踩坑实录。1. Agent-Reach 的设计思路为什么“能触达”比“做得准”更值得先测1.1 覆盖范围才是智能体落地的第一指标常规的评测项目比如问答准确率、代码通过率、数学题得分本质上测的都是“在一个给定问题上模型表现得怎么样”。这类指标当然重要但它回答不了另一个问题你的Agent在真实环境里有多少任务能真正开始、能走完全程、能拿到可用结果举个实际例子。我之前接过一个企业知识库问答智能体的需求当时团队把精力全砸在提升单轮问答的准确率上RAG的召回优化了一轮又一轮评测集里的问答分数从78%一路干到92%。可真正放到员工日常使用环境里一跑发现问题根本不是“答案准不准”而是大量问题压根没被Agent识别成可执行任务——有人问“帮我看看上周某项目的预算使用情况”Agent不知道该调哪个工具有人问“这个月有哪些待审批流程”系统直接超时还有人用口语化的表述问“那个谁上次说的表格呢”指代完全解析不出来。单点准确率再高覆盖不到任务入口一切都等于零。这就是Agent-Reach存在的理由。它把评测的重心从“答得对不对”转移到“任务碰不碰得到”用覆盖率这个横切指标扫一遍任务全集告诉你哪些能稳定完成、哪些半路会断、哪些压根没启动。这个视角的转变对落地部署的指导意义远大于传统指标。1.2 与常规评测体系的差异在哪市面上有些评测标准已经做得很好比如衡量工具调用准确率的、衡量多步骤规划合理性的、衡量最终结果匹配度的。这些评测给了我不少参照但它们通常是“任务导向”的设计好一批带标准答案的任务让Agent执行然后打分。Agent-Reach的差异在于它是“集合导向”的。它不关心某个任务的标准答案是什么核心关注点是给定一个任务全集Agent能覆盖其中多少覆盖不到的失败原因分布如何。就像给地图做测绘重点不在于某一条路修得有多好而在于整个路网能到达多少区域。用集合视角看Agent你能发现很多单点测试发现不了的东西特定类型的任务存在系统性空白比如所有涉及“跨表查询”的都被漏掉任务覆盖率存在明显的“长尾断层”头部高频任务跑得很顺尾部随机任务全军覆没某些工具因为鉴权、参数格式、上下文过长问题导致依赖该工具的所有任务集体失败。1.3 谁最需要这套评测什么场景下价值最大从我个人的经验看以下三类场景特别适合引入Agent-Reach第一类是Agent选型阶段。要对比两个候选Agent产品时与其各测几十个精心设计的prompt不如统一跑一个覆盖业务真实场景的任务集看谁的覆盖率更高、失败分布更集中。第二类是工具链调优阶段。当Agent接入的工具越来越多互相之间出现参数冲突、权限覆盖、返回结构不兼容时用reach评测能快速定位是哪个工具拖累了覆盖率。第三类是持续集成阶段。每次更新模型、调整系统提示词、升级工具版本之后跑一遍Agent-Reach用覆盖率曲线确认这次改动到底变好还是变坏。另外我要说清楚Agent-Reach不是用来替代传统评测的它是传统评测的前置补充。先用它把覆盖面做大再用专项评测把重点任务做精一前一后配合起来才是完整的评测闭环。2. 核心细节拆解任务集、覆盖率与稳定性怎么设计才科学2.1 任务集的拆解从业务场景到可执行用例Agent-Reach的第一步是把业务需求拆成一个一个可执行的评测任务。这个步骤做得粗不粗直接决定覆盖率数字有没有参考价值。我建议按“业务域—用户意图—任务类型—具体用例”四级来做拆解。举个我从零搭建的例子。当时要评测一套企业内部的运营数据助手我按下面几个维度建任务集业务域市场、销售、供应链、客服、财务用户意图查数据、对比数据、做计算、写总结、生成图表、设置预警任务类型单轮查询、多轮追问、跨数据源关联、模糊指代解析、大范围聚合统计建完以后再根据真实使用场景填充具体用例。一个用例必须包含“用户原话”“期望调用的工具”“期望输出的形态”“简单的验收条件”四要素。比如用例编号: OPS-1024 业务域: 销售 用户意图: 查询数据 任务类型: 跨数据源关联 用户原话: 帮我看看上季度华东区销售额完成率是多少跟去年同期比涨了还是跌了 期望调用工具: [get_sales_data, get_region_dimension, get_last_year_sales, calculate_ratio] 期望输出形态: 文字结论 数字 验收条件: 包含华东区、包含完成率、包含同比涨跌方向这个四要素模板看着简单但实操中非常管用。它逼着你去把业务场景翻译成可评测的结构化描述既方便人工审核用例质量也能让你在后续自动判定结果时做到有据可依。2.2 覆盖率公式与权重设计的门道任务集建好之后核心指标就是覆盖率。最基础的公式是reach 成功完成的任务数 / 全量任务数这个公式本身没难度难点在两层一是“成功完成”怎么判定二是“全量任务”要不要加权。成功判定的标准我强烈建议分成两级。第一级是任务终点判定只看最终输出是否满足验收条件第二级是过程健康判定额外看调用工具是否合理、步骤是否有冗余、是否有无效重试。过程健康判定不直接计入覆盖率但会记录在侧栏指标里用来在覆盖率下降时定位是“结果错了”还是“过程乱了”。加权问题更要重视。企业里任务的分布从来不是均匀的有些高频查询一天上百次有些长尾问题一个月才出现一次。如果不加权你会倾向于把长尾问题做得很细结果覆盖率数字好看但实际业务里最高频的那批任务反而不稳定。我的方案是给每个用例配一个“业务权重”用近三个月的调用频次估算覆盖率计算按加权口径来。同时保留未加权口径供参考两份数字摆在一起就能直观看到优化重心应该放在哪。2.3 稳定性评测覆盖率不是跑一遍能信的还有一个容易被忽视的问题LLM的推理是有随机性的。同一个Agent同一个任务跑五次可能三次成功两次失败。如果你只跑一遍就给出覆盖率这个数字的置信度非常低。我在Agent-Reach里引入了一个简单的“n次重复评测”机制默认每个用例跑三遍标记为高风险的用例跑五遍。最终覆盖率按“至少一次成功”和“多数次成功”两个口径分别统计。前者反映Agent能不能做到后者反映Agent稳不稳定。两个口径差得很大的任务就是典型的“手感不稳定”任务在生产环境里这些都算隐患因为一旦用户碰到失败的那次体验就是实打实的差。重复评测会带来一个直接的副作用任务量大之后跑得很慢、很贵。我的经验是测试环境把并发控在16~32个Runner左右避免触发服务端限流影响结果真实性。并发上去了以后再注意给每个Runner做独立的会话隔离防止上下文串台。3. 实操流程从环境准备到报告解读跑通一次Agent-Reach全流程3.1 环境准备评测基座怎么做才干净评测环境的第一原则是“干净可控”。如果你在线上环境直接跑Agent-Reach很可能因为线上数据动态变化导致评测结果不稳定每次覆盖率差异都解释不清楚。我建议搭建一套独立的评测基座包含以下部分一套Mock业务系统提供固定数据快照不随真实业务变化一套Agent运行时版本号钉死依赖锁完整一套评测调度器负责按任务集配置派发用例、收集结果一套结果存储MySQL或SQLite都行至少能把每次评测归属到版本号我一开始偷懒直接连了测试环境的真实数据和半固定的工具服务。结果第一轮跑完覆盖率比预想低了十几个点排查了一下午才发现是某个服务当天返回了异常数据格式导致所有依赖该服务的用例集体失败。这个教训告诉我评测基座千万不能省数据不冻结覆盖率永远是“薛定谔的数字”。数据快照怎么做最简单的方式是业务库导出一份静态数据再启动一个只读API服务来提供查询。工具层识别到调用后走这个只读服务返回格式和线上保持完全一致但结果可预期。3.2 任务集的YAML配置把评测结构工程化任务集建议用YAML或JSON管理不要散落在Excel里。这样能直接进Git仓库每次调整都有版本记录。下面是一个我实际用过的片段字段含义在注释里task_suite: name: ops-assistant-suite-v3 base_url: http://localhost:8920 agent_prompt_version: v1.4.2 tasks: - id: OPS-1024 domain: sales intent: query task_type: cross_source prompt: 帮我看看上季度华东区销售额完成率是多少跟去年同期比涨了还是跌了 weight: 8 success_criteria: must_include_slots: [华东区, 完成率] expected_tool_sequence: - get_sales_data - get_region_dimension - get_last_year_sales - calculate_ratio repeat: 3这个配置文件的最大好处是同一个项目团队每个人拉下来跑出来的任务集完全一致不会出现你测你的、我测我的这种无效对比。3.3 调度Runner从任务派发到结果回传调度Runner是Agent-Reach的核心执行组件。我的实现思路是用一个Python脚本读取上面的YAML然后按配置去调度对应Agent的API。下面是一个简化版本但核心流程都在import asyncio import yaml import aiohttp import pandas as pd from dataclasses import dataclass dataclass class EvalResult: task_id: str task_type: str prompt: str success: bool success_slot: bool tool_sequence_ok: bool latency_ms: int error_type: str async def run_single_task(session: aiohttp.ClientSession, agent_url: str, task: dict) - EvalResult: resp await session.post( agent_url /v1/chat/completions, json{messages: [{role: user, content: task[prompt]}], temperature: 0}, ) data await resp.json() answer_text data[choices][0][message][content] tool_calls data.get(tool_calls, []) # 这里做成功的判定必须满足槽位要求且工具调用序列包含期望工具 slots_ok all(slot in answer_text for slot in task[success_criteria][must_include_slots]) tools_ok all( tool in [t[name] for t in tool_calls] for tool in task[success_criteria][expected_tool_sequence] ) success slots_ok and tools_ok error_type if not slots_ok: error_type slot_miss elif not tools_ok: error_type tool_miss return EvalResult( task_idtask[id], task_typetask[task_type], prompttask[prompt], successsuccess, success_slotslots_ok, tool_sequence_oktools_ok, latency_msdata.get(latency_ms, 0), error_typeerror_type, ) async def run_suite(agent_url: str, task_config_path: str) - list[EvalResult]: async with aiohttp.ClientSession() as session: with open(task_config_path, r, encodingutf-8) as f: suite yaml.safe_load(f) tasks suite[task_suite][tasks] results [] # 按 task 里的 repeat 次数重复执行 for t in tasks: for i in range(t.get(repeat, 1)): res await run_single_task(session, agent_url, t) res.task_id f{t[id]}#{i1} results.append(res) return results def compute_reach(results: list[EvalResult]) - dict: df pd.DataFrame([r.__dict__ for r in results]) total_tasks df[task_id].nunique() success_at_least_once ( df.groupby(task_id)[success].any().sum() ) success_majority ( df.groupby(task_id)[success].mean().ge(0.5).sum() ) avg_latency df[latency_ms].mean() error_counts df.loc[~df[success], error_type].value_counts().to_dict() return { total_tasks: total_tasks, reach_at_least_once: success_at_least_once / total_tasks, reach_majority: success_majority / total_tasks, avg_latency_ms: avg_latency, error_distribution: error_counts, } if __name__ __main__: agent_url http://localhost:8920 res asyncio.run(run_suite(agent_url, task_suite_v3.yaml)) print(compute_reach(res))这段代码的真正价值不在于漂亮而在于把“评测”这件事变成可以重复执行的审计过程。只要每次套件版本固定任何一次改动的覆盖率差异都可以被量化。3.4 报告解读别只盯着一个大数字跑完Runner之后不要只看总的覆盖率数字。一张有价值的Agent-Reach报告至少要有以下几块按业务域的覆盖率、按任务类型的覆盖率、按错误类型的任务量分布、以及成功率残差最大的Top 20个用例。我把一套实际跑出来的报告结构放在下面供参考业务域用例数覆盖率至少一次成功覆盖率多数次成功主要失败原因销售3688.9%83.3%多步对比场景工具序列超时市场2878.6%71.4%模糊指代无法解析为预算实体供应链2564.0%56.0%跨表聚合缺少时间维度参数财务3080.0%76.7%鉴权失败导致报表工具不可用客服2195.2%85.7%长上下文导致回答不够收敛光看“总覆盖率78%”你只能知道大概情况但一旦看到供应链业务域只有64%再结合“跨表聚合缺少时间维度参数”这类具体错误原因你就能立刻定位到工具层的问题而不是盲目调Prompt。另一个值得关注的是“降低权重后的覆盖率差”。如果加权覆盖率比未加权低说明高频任务有问题反过来则是长尾任务拖后腿。这两种情况对应的优化策略完全不同前者要优先保障核心链路稳定后者要拓宽工具调用的泛化能力。4. 常见问题与排查技巧实录4.1 任务集“污染”导致覆盖率虚高这是最容易踩的坑。所谓任务集污染是指评测用例逐步渗透到训练或提示词里或者业务数据快照被评测本身改写导致Agent“背答案”。我见过有人同一批用例跑了大半年每次覆盖率都高得惊人后来换了新用例版本覆盖率一夜之间断崖式下跌。防污染的关键做法有三点定期更新任务集建议每两周加入20%-30%的新增用例对做过评测的用例做去重防止同一个主体换个措辞混进来评测结束后的数据快照做校验和确认没有因评测调用而改变。4.2 超时与并发控制测出来的不是真实能力并发调得太高Agent服务端会限流或排队测出来的延迟和成功率都失真。我一开始图快把并发拉到128结果那轮评测里几乎每个任务的延迟都在30秒以上失败率直接飙升到40%。后来把并发降到24同样的任务集延迟降到4秒失败率也恢复到正常水平。这里我的经验是评测前先用一个小样本测试一下Agent在高并发下的稳定性临界点。一般从16起步逐步翻倍找到“延迟开始明显恶化”的并发阈值评测并发定在阈值的50%以下比较安全。4.3 上下文串台会话隔离必须做扎实用异步Runner批量跑任务时如果不给每个Runner独立的会话上下文多个任务之间可能共享记忆。后果是前面的任务内容影响到后面的任务输出比如第一个任务生成了某个地区的销售表第二个任务提问时Agent直接复用之前的表格结构输出看起来挺对但跟真实任务场景完全不符。排查方法很简单凡是需要在“无历史空上下文”下运行的任务每次调用都带上会话ID并清理掉服务器端的记忆缓存。如果业务场景本身要求多轮对话再把这类任务单独标记不要跟单轮任务混在同一个并发池里。4.4 结果不一致三次评测两次过一次不过这类问题特别常见根子在于LLM解码的随机性以及Agent内嵌的反思机制可能触发状态切换。遇到这种情况不要贸然判定任务失败我把排查流程总结成一张速查表现象可能原因排查方向偶尔超时后失败服务端排队或网络波动调低并发重跑失败样本同样的Prompt输出差异大模型采样参数未锁定检查temperature是否设置过高工具调用结果解析偶发失败返回结构不稳定检查工具返回的JSON schema变换同一个任务稳定失败能力缺口或工具缺陷看失败原因分布按类型修底层改了Prompt后多个老任务失败提示词副作用跑囘溯Diff对比失败用例的共性排查逻辑的核心是“区分随机性失败和系统性失败”。随机性失败的任务加重复次数后一般能通过系统性失败的任务不管你跑多少次都会挂在同一类原因上这类才是真正需要投入资源解决的问题。5. 用Agent-Reach的结果反向推进技术决策跑通Agent-Reach之后最实际的价值在于它能指导技术决策而不只是一张评测报表。我分享几个实操中总结的经验。一是在模型选型阶段把多个候选模型接入同一套Task Suite各跑一遍Agent-Reach。你会发现覆盖率排名和传统评测精度排名经常不一样。某个模型单点问答能力很强但涉及多工具协作时覆盖率明显下降另有一个模型虽然单点效果平庸但整体覆盖稳定、失败分布均匀落地后反而更省心。二是工具层优化优先按错误类型来排序。从Agent-Reach的错误分布里找出拦截覆盖率最高的单个工具修复它一个往往能同时解锁好几个任务的覆盖率。我有一轮评测发现所有的“时间解析”都失败查下去是工具接口把“去年”这个相对时间默认拒掉了改了一个参数默认值整个业务域的覆盖率直接涨了11个百分点。三是用Agent-Reach做回归门禁。每次改动Agent的Prompt、工具定义或底层模型之后自动跑一遍精简版Task Suite覆盖率低于基线就阻止上线。这个机制看起来笨但实测下来是防止“修一个任务崩一片任务”最有效的手段。另外一个很有价值的衍生用法是“长尾探索”。用未加权覆盖率对比加权覆盖率如果未加权覆盖率的读数明显偏低说明长尾任务没被覆盖到。这批长尾任务虽然单个频次低但在创新场景里往往代表着新的用户需求。适当用Agent-Reach随机采样长尾领域能让你比竞品更早发现值得投入的新方向。从我的实践体会来说Agent-Reach 不是那种跑完一遍就能丢掉的工具它更像一套持续运行的“探针系统”。每个版本的Agent经过一次评测你都会更清楚它能力的轮廓和边界在哪哪些改动值得上线哪些改动要回退。尤其在智能化产品从原型走向规模化的阶段这种把能力当作可测绘对象来做度量的视角能帮你省掉大量无方向的调优时间。如果你也在做Agent的选型、落地或持续迭代我建议尽早把Agent-Reach这类评测思路引入到你的工作流里先搞清楚“能触达多少”再追求“做得有多好”这个顺序千万不能反。