Agent-Reach 这个名字是我们团队内部讨论了好久才定下来的。字面意思很简单智能体的触达边界。但真正把它当项目做起来我才发现这个词背后藏的问题远比想象中复杂。搭一个对话机器人、做一个端到端的人事问答助手大家都能做可一旦问起“你的 Agent 在什么条件下一定能触达目标在什么条件下会彻底失灵”——很少有人能给出一个确切的答案。这个项目的发起点是去年底我们一次内部复盘。当时团队上线了一个面向售后场景的 AI 助手demo 阶段效果非常惊艳但接入真实业务系统后经常出现“查询无结果”“权限不足”“信息不完整”这类问题。每个问题都能复现也能单独修复但每次修复都像打地鼠——按下葫芦浮起瓢。我慢慢意识到我们缺的并不是某个具体功能而是一套能衡量 Agent 能力边界的方法。所以Agent-Reach 本质上解决的是智能体在真实业务环境中的触达能力评估问题。这里说的“触达”不单是能调用某个 API而是从上下文、工具、业务系统、感知、记忆五个层面量化地搞清楚你的 Agent 到底能“够到”哪儿、够不到哪儿。如果你正在做 AI Agent 应用或者团队正打算把大模型接进真实生产系统这篇文章会把 Agent-Reach 怎么拆、怎么测、实际踩过什么坑一次讲清楚。1. Agent-Reach 是什么一个关于“够得着”的问题1.1 先拆开看触达到底指什么很多人一听“Agent-Reach”第一反应是“Agent 能访问多少东西”。这么理解没错但太粗糙了。我在实际拆解时把“触达”分成了四个层面每一层都对应一类经常被忽略的问题。第一层是信息触达。Agent 需要的信息是不是真的到了模型眼前用户发来一句话里面提到两周前的订单号知识库里有一份 PDF里面写着退款政策。信息存在、但 Agent 没读到这就是信息触达没做好。第二层是工具触达。Agent 能不能在需要的时候准确选到那个工具很多系统给 Agent 挂了 50 个 API结果模型在工具选择上直接迷失。第三层是系统触达。工具选对了权限够不够接口允不允许这次操作这一层最容易出安全事故。第四层是场景触达。Agent 在这一套场景里能跑通换个业务流程、换套话术环境还能不能触达这是评估泛化能力的关键。用一个生活化的例子来类比让一个实习生去处理客户退款他需要拿到聊天记录信息触达、会使用退款系统工具触达、系统账号有退款权限系统触达、并且清楚在不同客诉场景下该怎么操作场景触达。任何一环断了事情就办不成。模型能力再强也只能干着急。1.2 为什么 Agent 评估比模型评估难一个量级做过大模型评测的朋友都知道评测一个纯语言模型相对简单给输入、看输出对比参考答案就行。但评测一个 Agent 完全是另一回事。Agent 的行为是多轮、动态、有副作用的——它要读上下文、选工具、调接口、看返回结果再决定下一步中间任何一环出错最终结果都可能对不上。我见过太多团队用“这轮回答得好不好”来评价一个 Agent这其实是在用静态指标衡量动态系统。Agent-Reach 项目最核心的转变是把问题从“回答质量好不好”换成“目标到底有没有被触达”。看似只是换个问法背后是一整套评估口径的调整不只看最终话术更要看工具调用链、上下文利用率和权限边界。这套口径建立起来之后团队才第一次能说清楚“瓶颈到底在模型、在数据、还是在系统集成上”。2. Agent-Reach 的五维触达模型2.1 上下文触达模型能“看”多远不等于能“用”多远上下文触达是我最早踩坑的地方。最初我们想得很简单模型支持 128K 上下文那把对话历史、知识库内容、工具返回结果全塞进去不就行了实测下来完全不是这么回事。问题出在两个层面。第一信息被淹没。当上下文里塞了太多无关内容模型对关键信息的注意力会被稀释。尤其是业务日志、检索片段、多轮对话混在一起时模型经常会漏掉关键字段。第二信息被截断。一些长文档被截断时恰好把最关键的结论部分切掉了模型看到一半就拿去推理结果自然偏了。后来我们的做法是给上下文做结构化管理。对话历史做滑动窗口只保留最近 N 轮工具返回结果必须经过压缩、摘要、字段抽取而不是把原始 JSON 整个丢进去关键信息订单号、用户 ID、当前状态提取后放在一个“固定锚点区”放在提示词最前面。实测下来单纯做这一项任务完成率就提升了差不多 20 个百分点。2.2 工具触达工具不是越多越好而是越“可被选对”越好工具触达是 Agent 最核心的能力之一也是最容易设计失败的部分。我给你看一组我们早期的真实数据当时给内部客服 Agent 挂了 40 多个工具名字五花八门有check_order_status有get_order_info_by_id有query_order_detail——功能高度重叠。结果模型经常选错或者反复在两个相似工具之间犹豫白白浪费好几轮。后来我把工具列表砍到 15 个做了三件事一是统一命名规范每个工具名必须体现操作对象和动作二是写清使用条件在描述里明确写“当用户询问订单物流时使用”“当用户要求修改收货地址时使用”三是为每个工具加负面提示直接告诉模型“不要在其他场景下使用此工具”。效果立竿见影工具选择准确率从 68% 提到了 91%。还有一点容易被忽略工具参数的可信度。Agent 调工具时参数经常来自用户输入而用户的表述往往是模糊的——“我那个订单”到底是哪个订单所以工具层必须设计解析和确认机制拿不准的参数宁可反问一次也不要硬着头皮传一个错误值进去。2.3 系统触达权限边界不清Agent 要么够不着他要么捅娄子系统触达这个维度我建议所有做 Agent 的人都把它列在最高优先级。它要解决的只有一个问题Agent 调接口的时候权限是否既足够又受控。这里存在两个极端。一个极端是权限给得太窄Agent 想查客户信息但接口只允许查询已登录用户自己的数据想读取工单详情但角色只配了只读权限连状态变更都做不了。Agent 全程在“撞墙”体验极差。另一个极端是权限给得太宽为了省事直接给 Agent 配了一个管理员角色的 API Key它能查所有用户数据、能删记录、能改配置。demo 是流畅了但这是拿安全事故换的。我们最终落地了一套“三层授权”机制第一层接口级别控制明确哪些接口对 Agent 开放第二层数据级别控制按业务角色限制可访问的数据范围比如普通客服看不到财务字段第三层操作级别控制把接口方法分成只读、可写、高敏三类Agent 的默认策略是只读优先需要写操作时必须经过二次确认。这套机制让系统触达既有了宽度又有了护栏。2.4 感知触达信息在图片、语音、表格里Agent 就真的能看到吗“感知触达”这个词听起来有点学术其实说的是一个非常实际的问题业务信息不全是干净文本。我们的售后场景里有大量用户发来的截图上面是报错信息或者订单页面有产品说明书 PDF还是扫描版的有好几百行的 Excel 表格里面是库存数据。如果 Agent 只能处理纯文本那这些信息对它来说就是“不可见的”。感知触达不到后面所有推理都无从谈起。我们的做法是给 Agent 加了一条“感知流水线”截图类输入先进 OCR 和图像理解模块提取出结构化文本PDF 走文档解析服务按章节切分并抽取关键字段表格类数据先做格式识别再转成 Markdown 表格或 JSON 给到模型。这个过程必须在进入上下文之前完成而且要保留原始来源标记方便 Agent 在不确定时回溯原图。这里有个判断标准很重要感知能力不能被模型“猜测”替代。如果 Agent 不确定一张图里到底写的什么它应该坦诚地说“我没看清”而不是编一个答案。感知触达的边界就是 Agent 对外部世界的“视力”边界。2.5 记忆触达跨会话的记忆是资产也可能是风险记忆触达是五维模型里最容易被人忽视、但影响最大的维度之一。没有记忆的 Agent 像一个“金鱼”每次对话都从零开始有了记忆它才谈得上“越用越懂你”。我们早期做过一次很失败的长记忆设计把每个用户的历史对话全部塞进向量库然后在每次会话开始时做检索注入。结果问题一堆用户上周咨询的是 A 产品这周问 B 产品Agent 却老记着 A 产品的信息造成干扰。后来我们做了两层调整一是给记忆内容加生命周期——短期事实比如“用户上次说的是订单号 xxx”保留 24 小时长期偏好比如“用户偏好邮件沟通”保留 30 天临时性内容到期自动清理二是记忆按需召回不是每次把所有记忆都塞给模型而是根据当前会话主题去检索最相关的条目。做记忆设计时还要想清楚一个边界问题哪些信息适合被记住、哪些不适合。比如用户的支付密码、身份证号这类敏感信息不光技术上不该记从用户信任角度也绝对不能记。记忆触达不是无上限地延伸而是该记得的记得住、不该记的不碰。3. 实操搭一套最小的 Agent-Reach 评测台3.1 评测场景怎么设计才不“骗自己”很多团队的评测集是拿历史好对话拼出来的天然偏向“顺风局”。Agent-Reach 项目里我们花大力气设计了三类场景的配比常规路径 70%、边界路径 20%、失败路径 10%。常规路径就是正常业务流比如“用户查询订单状态”“用户申请退换货”边界路径包括模糊表达、信息不全、需要多轮澄清的情况比如“打电话和发邮件那个订单是不是同一个”失败路径则是用户提出超出范围的需求比如“帮我修改订单金额”这类非授权操作。设计失败路径的目的是看 Agent 会不会正确“拒绝触达”而不是硬着头皮执行错误操作。每个场景都要写清楚四个要素用户输入、期望调用的工具链、允许的数据范围、最终应返回的结果状态。这个设计过程比较费人力但它决定了评估结论是不是靠谱。3.2 核心指标与评分口径我们最后固定下来五类核心指标触达率Reach Rate场景中必需的 N 个外部资源工具、数据、权限里Agent 实际成功触达了多少个。这是 Agent-Reach 的核心指标。任务完成率Completion Rate场景目标是否在允许轮次内完成。注意必须定义“允许轮次”超过轮次就按失败算。越权触达次数Overshoot CountAgent 是否访问了超出权限范围的数据或接口。这个指标为负向指标出现一次就要扣分。澄清效率Clarification Efficiency遇到信息不全时Agent 平均用多少轮问清问题。问得太多说明工具描述或提示词有问题。幻觉触达比例Hallucinated Reach RatioAgent“假装”调用了工具或宣称完成但实际没有发生的比例。这个指标最隐蔽也最需要监控。每个指标我们都会结合业务目标设阈值线比如触达率低于 80% 不允许上线幻觉触达比例超过 2% 必须立即回滚。指标不是摆设是发布卡点——这一点在后续迭代中帮我们挡住了好几次潜在事故。3.3 评测落地从场景注入到结果回收评测台本身用 Python 写并不复杂关键在于要做一套标准化的“执行-校验”循环。我们当时的实现思路大致如下# -*- coding: utf-8 -*- Agent-Reach 评测执行器简化示意 import json, yaml from typing import Dict, List class ReachEvaluator: def __init__(self, agent, tool_registry: Dict, policy: Dict): self.agent agent # 被测 Agent self.tool_registry tool_registry # 工具注册表含权限标记 self.policy policy # 权限策略接口/数据/操作三层 def run_case(self, case: Dict) - Dict: # case: {id: T-001, input: ..., expected_tools: [...], # data_scope: [order], max_rounds: 10} state { tool_calls: [], permission_errors: [], success: False, rounds: 0, } user_input case[input] while state[rounds] case[max_rounds]: action self.agent.step(user_input) state[rounds] 1 if action[type] tool_call: ok, result self._checked_call(action[tool], action[params]) if not ok: state[permission_errors].append(action[tool]) state[tool_calls].append(action[tool]) user_input self.agent.feed_result(result) elif action[type] final_answer: state[success] self._verify_result(action[answer], case) break return self._score(state, case) def _checked_call(self, tool_name: str, params: Dict): # 按三层权限策略做前置校验 if self.policy[interface].get(tool_name, False) is False: return False, 接口未开放 if not self.policy[data_scope].issuperset(params.get(data_keys, [])): return False, 数据范围越权 return tool_name in self.tool_registry, self.tool_registry[tool_name](params)这段代码只是骨架但两个设计点很关键。一是_checked_call在真实工具调用之前做了权限前置校验越权操作会在执行层被拦截而不是等 Agent 调完才发现——评测期间发现越权比上线后追责成本低得多。二是_score函数把触达率、越权次数、完成状态一起汇总生成一份结构化的评估报告。我们每周跑一次回归把结果自动同步到内部看板所有版本的 Agent 谁强谁弱一目了然。建议你搭评测台时也加上时间戳和数据留痕每个用例跑完把完整对话轨迹、工具调用链、权限校验结果存下来。这些数据是后面排查问题的金矿。4. 实测中踩过的坑Agent 为什么总是“够不着”4.1 上下文截断的“隐形杀手”有一次我们升级了版本把知识库检索片段从 3 段加到 8 段结果触达率反而掉了。一查日志发现问题出在上下文拼接顺序上新增的检索片段被放在工具返回结果之后模型生成时上下文超出窗口历史对话被截断了。用户的核心诉求在截断区里Agent 自然就开始“失忆”。这个教训让我意识到上下文窗口的数字只是上限不是安全线。我们在评测脚本里专门加了一项检查——每次会话结束后回放上下文中是否还包含当前任务的“目标锚点”订单号、用户 ID、关键诉求。如果锚点字段在任意一轮丢失直接判为上下文触达失败。后来再升级提示词或检索策略都会先跑一遍锚点完整性的回归测试。4.2 工具权限设错要么够不着要么越权我们遇到过两个极端的线上事故。一次是只读权限配得太死Agent 无法更新工单状态用户让“帮我催一下”时Agent 只能用话术回复“好的已为您催促”实际上后台单子压根没动。另一次是数据权限配得太大一个测试 API Key 意外带了生产库的读取权限Agent 直接被诱导查询了其他客户的订单记录。后者我们当时就紧急下线了。现在我们的策略是权限配置也走评审和演练。每个 Agent 版本上线前评测台会专门跑一批“越权诱导演示用例”由测试脚本故意诱导 Agent 访问高敏数据、执行写操作只要触发率不为零就不允许发布。权限这玩意儿宁可多测十遍不能赌一遍。4.3 幻觉式触达Agent“假装”自己完成了最隐蔽的坑是 Agent 没有真正触达任何工具却给出了一个看似合理的答案。典型场景是用户问“能不能改一下我的收货地址”Agent 直接回答“已经帮您修改成功”但日志里根本没有对应的update_address调用记录。这类幻觉式触达在纯对话场景里很难被察觉因为话术非常自然。我们的解决手段是双管齐下一是在提示词里强制要求——任何涉及外部操作的结果必须附带对应的工具调用 ID 或变更单号否则视为未完成二是后端联动校验——Agent 声称“已更新”时评测台会自动调用查询接口去核对实际状态发现状态没变就判定为幻觉触达失败。这个校验逻辑后来也被产品团队直接借去做了线上兜底。4.4 常见问题速查表我把实测中最容易碰到的几个问题汇总成了一张速查表方便大家照着排查症状可能原因排查方法建议修复方向Agent 频繁说“查不到”工具描述不清或接口数据范围受限看日志中实际调用的参数和返回码重写工具描述扩大数据权限多次调用相似工具工具数量过多、命名语义重叠统计工具选择混淆矩阵合并冗余工具增加“何时不用”说明关键信息丢失导致答非所问上下文被截断或锚点字段被挤出回放上下文检查锚点是否存在结构化上下文固定锚点区用户要求被“假装完成”提示词缺少强制证据要求比对最终答复与工具调用记录增加工具调用 ID 引用约束越权访问数据权限策略过于粗粒度审查 API Key 角色和数据范围落地三层授权机制记忆内容干扰当前会话长记忆无条件注入检查检索注入的记录时间线增加生命周期和按需召回这张表我们内部一直用着每次遇到新坑就补充一行慢慢变成了一份团队的“踩坑百科”。5. 让 Agent 触达更远的几条工程经验5.1 把“触达范围”变成显式的工程资产Agent-Reach 项目做下来我最深的一个体会是触达范围不能只存在开发者的脑子里它必须是一份显式维护的工程资产。我们团队现在维护三个清单全部纳入代码仓库随版本发布自动更新。第一份是工具注册清单每个工具写明功能、适用场景、参数要求、权限级别。第二份是数据资产清单列出 Agent 可访问的数据域、字段级权限、脱敏规则。第三份是场景回归清单就是评测台里那批用例按业务模块分类维护。新增任何工具、放开任何权限都必须同时更新清单并跑一遍回归用例。这听起来像是多了一堆流程但它让“Agent 到底能干什么”这件事从模糊变清晰也让新人接手时不用再靠口口相传。5.2 工具层协议化而不是硬编码我们早期给 Agent 接工具每个系统一套风格有的是 REST 接口有的是内部 RPC有的要拼复杂鉴权头。模型调用时经常因为参数格式不统一而失败。后来我们统一走协议化封装每个工具对外暴露一致的调用方式统一的参数校验、统一的鉴权注入、统一的结果返回结构。这一步做对了工具触达率的提升是一眼可见的。原因不难理解当工具的调用规范不一致时模型需要花更多“脑力”去理解差异反而没精力关注业务目标。把工具层标准化相当于给 Agent 铺了一条笔直的路它只需要专注决定“走哪条路”而不是还要纠结“这条路怎么走”。如果你用的是开源生态可以关注当前主流的模型上下文协议MCP这类标准化方案它能大幅降低工具接入的重复成本。5.3 在真实业务里验证而不是只在沙箱里折腾评测台里的仿真用例再丰富也模拟不出线上真实环境的全部复杂性。我们踩过的很多坑都是沙箱里跑得好好的、一到线上就露馅。后来我们建立了一套“影子模式”的验证机制Agent 的新版本在线上跑真实流量但它的所有操作默认只读或仅在隔离环境执行同时由评测执行器持续记录它的“如果当时放行会怎样”的行为轨迹。影子模式跑上一两周积累足够的真实样本后再拿这些带标注的轨迹回放进评测台做回归。这个方法的好处是你不需要拿真实数据冒险就能提前发现 Agent 在真实分布上的触达短板。评估的终点不是评测台而是线上真实流量的持续验证。做完 Agent-Reach 这个项目之后我最大的一个感受是大模型的推理能力其实一直在超出我们的预期真正限制 Agent 发挥价值的往往不是模型本身而是它外面的那一圈“边界”——权限、工具、数据、记忆、感知——没有被清晰地设计和度量。如果你也在做类似的事情我的建议是先别急着加功能老老实实把触达边界测一遍。你大概率会在动手之前就看到那个一直隐藏着的瓶颈。