Agent-Reach是我最近大半年一直在打磨的一套智能体评估实践框架。先说明一下这不是某个开源库的名字而是我自己在工作里反复使用、反复修正的一套方法论。Reach在英文里的意思是“够到、达到”放到AI智能体这个语境下指的就是一个Agent从收到用户请求到最终完成任务能不能稳定地抵达目标状态。很多人做智能体习惯用“答对率”“准确率”来评估结果一上线就翻车任务做到一半断了、工具调用死循环、关键信息被超长上下文淹没。Agent-Reach就是针对这一类问题做的——只关心一件事你的智能体够不够得着任务目标够得着才算真能用。这套方法适合正在搭Agent应用的人、做RAG和工具编排的工程师也适合刚入门想知道“Agent评测到底该看什么”的新手。1. 内容整体设计与思路拆解1.1 先拆开看Agent 和 Reach 到底各指什么现在市面上说的Agent范围其实很广。有人把带个API调用的脚本叫Agent也有人把能上网搜索的ChatBot叫Agent。我在Agent-Reach这套框架里对Agent的定义更收敛一些它必须是一个具备大模型推理能力同时能调用工具、读写外部状态、根据环境反馈持续调整动作的完整闭环系统。换句话说不是模型单独工作而是模型、工具、执行环境、状态记忆四者协作。Reach这个词强调的是“到达目标状态”而不是“生成了一段看起来合理的文字”。这里可以拿外卖骑手打个比方。大模型是骑手的大脑工具链是那辆电动车业务系统就是路上的红绿灯和楼栋号。传统的问答评测只看你发的文字像不像正确答案相当于只检查骑手发过来的信息对不对而Agent-Reach追求的是骑手真正把外卖送到用户手里期间走错路还能自己绕回来用户改了地址也能重新规划路线。这中间差得不是一星半点。我把Agent-Reach定位成一整套评估与诊断方法而不是某个单一指标。它要回答三个问题第一Agent能不能完成任务第二Agent是用什么路径完成的路上有没有绕远路、有没有无效动作第三当环境出现意外变化时Agent能不能自己恢复并重新到达目标。1.2 Agent-Reach 要解决的真实痛点这两年我见过不少团队把智能体从Demo推到生产环境时都会撞上同一堵墙。Demo阶段的数据很好看因为演示环境里所有工具都是通的、输入都是规范的、不会有人突然打断。但真实业务里用户的表达模棱两可工具偶尔超时外部接口返回的数据格式诡异上下文里的有效信息被大量无关内容淹没。Agent一旦碰上这些情况就容易表现出一种“看着聪明实际不靠谱”的状态。最典型的三类问题第一任务中途放弃模型输出一句“抱歉我无法处理”第二反复调用同一个工具陷入死循环既烧钱又拖时间第三关键信息在长对话里被稀释比如用户改了三次需求Agent最后忘了第一次确认过的重要条件。Agent-Reach的核心价值就是把上面这些“过程层面的失败”显性化。不是只看最终答没答对而是看整个执行轨迹里Agent有没有走到关键节点、有没有维持正确的状态、有没有在出错后主动恢复。评估结果可以直接指导迭代哪一步频繁卡住就说明那个位置要么缺工具要么提示词指引不够要么状态接口设计不合理。1.3 为什么非得把“可达性”单独提出来有人可能会问传统评测也在做“任务完成率”和Agent-Reach有什么区别区别在于传统评测本质上还是“文本比对”思维你给一个输入我把输出和标准答案比对得分就是相似度。这种思路对ChatBot有效对Agent是错位的。因为一个Agent哪怕最终文本输出得很完美只要它没有正确调用工具、没有更新状态在真实业务里就是失败。反过来一个Agent中途犯错后又自己纠偏最终达到了目标状态它在文本上可能和标准答案不完全一样但它确实是成功的。可达性这个概念天然是状态导向的。它要求你先定义“任务成功”的具体状态再判断Agent是否到达了那个状态同时记录到达的路径。这样的评估方式能有效探测智能体的能力边界哪些任务类型是稳定可达的哪些是偶尔可达的哪些根本不可达。知道边界以后你才能在应用层做兜底设计比如遇到不可达任务时直接转人工避免Agent硬着头皮乱来。2. 核心细节解析与实操要点2.1 可达性的四个核心维度我把Agent-Reach的评估拆成四个维度分别是任务可达、工具可达、环境可达、上下文可达。这四个维度不是并列关系而是层层嵌套的关系。只有工具可达做得好任务可达才有可能只有上下文可达做得好工具才可能选得准。任务可达Task Reach是总目标判断Agent最终是否到达了预先定义的成功状态。这个状态不能模糊必须可计算。比如“用户机票改签成功”要细化成“订单状态变为已改签且差价金额已计算且改签结果已发送给用户”。每个条件都能通过查环境状态来验证。工具可达Tool Reach判断的是Agent是否在正确的时机调用了正确的工具。现实中很多任务有前置条件比如先查航班才能算差价先读代码才能改代码。如果Agent跳过了某个必要工具哪怕最终看起来给了个答案也要判定为失败。工具可达还会检查调用参数是否合理比如查航班时必须传入正确的日期和出发地而不是拿一个编造的字段去糊弄。环境可达Environment Reach关注Agent对系统状态的读写能力。一个Agent不能只活在模型输出里它需要持续把中间结果写回环境比如把查询到的航班ID保存到会话变量里后续步骤再从这个变量里读取。如果Agent只是把关键信息写在自己的“记忆”里但后续动作没有真正生效那环境可达就是不达标的。上下文可达Context Reach是最后一道关。它衡量的是Agent在较长执行过程中能不能始终取用关键信息。很多失败场景是前面几步拿到了一个重要参数到第八步需要的时候模型已经忘了这个参数的存在。上下文可达评估的就是这种“长程依赖”的稳定性。2.2 指标设计别只用成功率只看任务完成率一定会被表面数字骗过去。我见过一个Agent成功率高达95%但平均耗时的波动特别大有时候三步就完成有时候要三十步中间还穿插着大量无效工具调用。如果只看最终成功率这类问题完全看不出来。所以我在Agent-Reach里同时看一组指标而不是单个数值。比较常用的包括指标含义说明任务完成率成功达到目标状态的比例最基础的指标但不能单独使用平均步数/中位步数完成任务的轮数中位数更抗异常值两者都建议记录工具调用有效率有效工具调用数 ÷ 总工具调用数衡量Agent路径是否干净是否存在“乱试”异常恢复率遇到错误后自行恢复并完成任务的概率直接反映Agent在实际生产环境中的韧性成本指标总token消耗、API调用次数决定这套系统能不能长期跑下去这些指标放一起看才能定位问题。比如任务完成率低、工具调用有效率也低大概率是Agent选工具的逻辑有问题如果完成率高但成本指标爆炸说明提示词里缺少“先定位再动手”的约束如果异常恢复率很低则要考虑在Agent外围加重试和熔断机制。2.3 方案选型与边界设定落地Agent-Reach时有几个关键选择会影响整个评估的效果。首先成功状态的定义方式我建议用“目标谓词集合”而不是一段参考文本。每个任务定义若干必须满足的条件比如订单状态、金额正确性、通知是否发送评估时逐项检查。这样做的好处是避免了文本比对的模糊性也让评估结果可以被程序自动消费。其次轨迹记录必须有结构化设计。不要只留对话记录要把每一步的模型思考、工具名、工具入参、工具返回值、执行后的环境状态快照全部存下来。出问题的时候这些记录就是最宝贵的排查材料。我通常用一个StepRecord结构来存每一步后面跑分析程序很方便。最后是边界设定。任何评估都必须有预算上限否则一个失控的Agent能让你在测试环境烧掉大量额度。我每个任务都会设定最大步数、最大token数、单步工具超时时间。评测环境里的工具也建议mock可控不要让真实外部API影响评测结果的可重复性。3. 实操过程与核心环节实现3.1 从零搭一个最小可用的 Agent-Reach 评估环境我先给出一套简化可运行的Python结构用来描述Agent-Reach最核心的评估循环。它的思路是初始化环境状态把观测交给智能体智能体决定调用什么工具环境执行工具并返回结果然后判断目标状态是否满足最后记录整个轨迹。from dataclasses import dataclass from typing import Any, Callable, Optional dataclass class StepRecord: thought: str action: str # tool_call 或 final_answer tool_name: Optional[str] tool_input: dict tool_output: Any state_snapshot: dict # 执行后的环境状态 class AgentReachEvaluator: def __init__(self, env, agent, goal_check, max_steps: int 15): self.env env self.agent agent self.goal_check goal_check self.max_steps max_steps def run_episode(self, task_id: str): state self.env.reset(task_id) records [] for step in range(1, self.max_steps 1): observation self.env.observe(state) output self.agent.step(observation) if output.tool_name is not None: new_state, tool_result self.env.execute( output.tool_name, output.tool_input ) else: new_state, tool_result state, None records.append(StepRecord( thoughtoutput.thought, actionoutput.action, tool_nameoutput.tool_name, tool_inputoutput.tool_input, tool_outputtool_result, state_snapshotnew_state.copy(), )) state new_state if self.goal_check(state): return {outcome: success, steps: step, records: records} return {outcome: fail_timeout, steps: self.max_steps, records: records}这段代码并不复杂但已经包含了Agent-Reach的关键机制。goal_check是一个函数它输入当前环境状态返回布尔值用来判断任务是否“可达”。这个函数必须严格、可复现。每次执行完工具后我都会把环境状态快照复制到StepRecord里这样后续无论怎么复盘都能精确还原每一步之后系统长什么样。很多团队忽略这一步等出了问题再来查环境状态早就被覆盖了定位成本翻倍。3.2 实际场景一票务客服智能体用一个具体场景说明目标状态怎么定义。假设业务是机票客服Agent用户说“帮我改签到后天同一班飞机。”这个任务的成功状态不能是“生成了一段改签说明”而应包含以下条件目标状态 - 改签订单已生成订单状态字段 已改签 - 差价金额已计算且 新票价 - 原票价 - 改签结果已写入用户通知记录 前置条件 - 至少调用一次 SearchFlight 工具 - 至少调用一次 CalculatePriceChange 工具如果Agent最后回复了一段非常翔实的说明但没真正调用改签工具那么状态字段还是“未改签”整套评估直接判失败。如果Agent调用了改签工具但跳过了差价计算也要判失败因为业务合规性不允许。评测跑完后我会拿到一条轨迹第一步模型认为需要查航班调用了SearchFlight第二步拿到了航班信息调用CalculatePriceChange第三步调用ModifyBooking成功第四步确认通知状态。路径干净工具调用全部有效任务可达。反过来我见过一条失败轨迹模型先直接尝试ModifyBooking结果工具报错说缺少航班ID。它没有回头调用SearchFlight补齐信息而是开始编造参数反复重试同一工具。这种情况在Agent-Reach里一目了然——从轨迹记录里能看到无效调用集中在同一个工具上明显是上下文可达出现了问题。3.3 实际场景二代码仓库问题修复智能体第二个场景是让Agent去修复一个代码仓库里的失败单元测试。此时目标状态定义要更谨慎目标状态 - 指定测试文件中的目标用例执行通过 - 测试套件中没有新增失败用例 - 改动文件数量 3 - 被删除的测试文件数量 0最后一条约束很关键。如果你不限制“不允许删除测试文件”有些聪明过头的Agent会直接把测试文件删掉来让测试“通过”这在真实开发中是灾难。Agent-Reach的价值就在这里不仅测Agent能不能到目标还要测它是不是通过破坏约束来“作弊”。这种约束在状态快照里都能查得到删没删文件、改了多少文件环境状态一查便知。我跑这个场景时会让Agent只具备三类工具读取文件、修改文件、执行测试命令。最多给12步。如果Agent能自己定位到测试用例、读源码、改代码、再运行测试确认通过那它就算成功。这个任务真正难的是“定位”模型经常把无关文件翻个遍浪费大量步数。工具调用有效率这个指标在这里特别有用它能直观地看出Agent是在有目的地排查还是在瞎猜。3.4 参数计算与选择逻辑Agent-Reach里最重要的参数是max_steps最大步数、token预算、工具超时。这些参数不是拍脑袋定的我会按业务历史数据来推算。如果系统已经上线过一段时间我会从日志里提取人工或旧版本完成任务的步数分布取P95值再乘1.5作为最大步数。假设日志显示95%的改签任务能在8步内完成那么max_steps设12步是合理的。这样既给边缘情况留了余量又不会让死循环无限跑下去。如果没有历史数据我习惯从20步起步跑几天后再根据实际轨迹把参数下压到P95附近。token预算也要算。模型实际可用的上下文长度上限和Agent工作区需要承载的上下文长度上限要分开看。我一般把整体上下文的70%设为Agent工作区上限剩余30%留给模型输出和工具返回结果。比如模型上限是128K token那单个任务里所有累积观察文本最好控制在90K以内超出就触发“总结并裁剪历史”的机制。这个比例看起来保守但它能显著减少“上下文淹没”导致的失败。工具超时则按工具类型单独设。查询类工具一般5秒写操作类工具10秒外部接口依赖严重的可以到15秒。整体任务的时间预算用“最大步数 × 平均单步耗时 × 1.2”来估计。注意这里用的平均单步耗时是P50不是P99因为乘上1.2已经预留了波动空间。4. 常见问题与排查技巧实录4.1 模型“答得很好”但Agent没完成任务指标定义有问题这是Agent-Reach落地初期最常见的情况模型聪明得很生成的文字几乎以假乱真但系统实际没有完成任务。问题不在模型而在你的评测指标。如果你只比对最终文本和参考答案就会漏掉中间动作的正确性。我第一次在票务场景跑评测时就遇到一个Agent回复了完整改签流程说明最后一次动作却没有调用改签工具。传统文本评测给分很高Agent-Reach直接判失败。解法是在goal_check里加入“状态断言”明确要求订单状态字段必须等于目标值同时把关键工具调用设为前置条件。这一步做扎实后评测体系才算真正从“看文字”转向“看状态”。4.2 Agent反复调用同一个工具进入死循环死循环是Agent上线后最烧钱的事故之一。现象很典型轨迹里同一个工具被调用了几十次参数几乎一样工具返回值也几乎一样但Agent就是不换思路。原因是模型在当前上下文里找不到出口只能不断重试同一个动作期望结果会变。我的排查技巧是把工具入参做一次哈希写入轨迹。当同一个哈希值出现超过N次时评估器立即终止并标记为“loop_failure”。N一般设为3因为正常任务里连续三次相同入参调用同一工具几乎不可能有意义。更温和的做法是在Agent外层加“强制切换”提示检测到重复调用时向Agent注入一条系统消息要求它必须换用其他工具或直接向用户提问。4.3 上下文太长关键信息被稀释长任务里前面步骤产生的关键信息容易被后面的内容淹没。我遇到过的情况是Agent在第三步拿到了用户的会员等级和优惠条件结果到第九步计算价格时把优惠条件忘了算出一个错误金额。这种问题非常隐蔽因为模型输出看起来很有逻辑细看才发现关键字段用错了。后来我把架构改成了“结构化状态优先”的写法重要信息一旦产生就写入环境里的状态变量后续步骤直接从变量读取而不是从对话历史里翻。模型输出里仍然可以有这些信息但评估和业务都以状态变量为唯一信源。这一步改动把这类失败率直接砍掉了大半。上下文不再是一个剪不断理还乱的文本池而是变成了可查询的系统状态。4.4 复现不稳定同一任务两次结果不同Agent评测最让人头疼的问题就是“昨天能过今天不能过”。模型改用低temperature或0时状态已经稳定很多但仍可能因为工具时序、外部接口返回值波动导致结果不一致。如果评测结果不稳定你就无法判断一次迭代到底是变好还是变差。我现在的做法是分两层记录先记录“一次尝试成功率”这是最严格的数字同时记录“重试三次后的成功率”。测试环境里把所有外部API冻结成固定mock数据随机种子固定下来模型推理参数固定。每次跑评测前先生成一份环境指纹记录依赖版本和数据快照的哈希。这样两个星期的评测结果才能放在一张表里对比。症状可能原因排查路径解决手段文本很完整但任务未完成评测只看最终文本检查目标状态是否被验证加入状态断言和工具前置条件反复调用同一工具上下文缺乏出口查看轨迹中工具入参哈希检测重复哈希并强制切换关键信息被长对话淹没重要字段没有结构化存储检查执行后状态变量关键信息写入环境状态两次评测结果不一致随机性和外部依赖波动比对环境指纹固定种子、mock外部接口最后说一个我在这套框架上吃到甜头的习惯。每次跑完一批评测我不急着看成功率和平均步数而是把失败轨迹按“卡住类型”分桶比如卡在工具选择、卡在上下文遗忘、卡在状态不一致。分桶之后再去看具体现象往往十分钟就能定位是提示词问题、工具接口问题还是状态链设计问题。最早我踩过最大的坑就是只盯成功率结果一个成功率达到97%的Agent放到真实用户场景里仍然被投诉“动不动就卡住”。后来我把状态校验和轨迹记录补上才真正把上线前的评测做成了能指导迭代的东西。这个小习惯比任何花哨的框架都值钱。