我最早听到“Agent-Reach”这个词是在一次内部例会。当时我们组的智能体系统连续三周出现“工具调用了但没生效”的工单大家各抒几见最后负责人抛了一句话“别把问题当模型问题先算算你的Agent到底能触达到哪一步。”我后来把这句话当成了项目起点。所谓触达不只是“能调用一个工具接口”这么简单。它至少包含三层工具能不能被发现、上下文能不能支撑到调用那一轮、调用之后的返回信息能不能被正确接住。我当时的系统三层都在出问题工具注册表里有两百多个接口实际每次任务却只扫描到十几个任务做到第8轮上下文窗口就快满了后面的工具调用还在往里面塞资料有几个外部服务返回的成功状态码是200但数据字段被截断智能体照样把残缺信息当作最终结果交给用户。这些问题单独看都能解释成偶发故障但放到同一张时间线里就看到一个共性Agent能到达的能力范围和任务实际需要的范围之间存在一条很宽的空隙。摸清并填平这条空隙就是Agent-Reach这个项目要做的事。它不是什么酷炫的新模型也不是一个通用平台而是一套被我拼出来的内部工具能力注册表、触达轨迹记录、上下文压缩、失败回退编排外加一堆围绕它们写的巡检脚本。这套东西解决的是三类人的问题正在为多智能体任务连续性头疼的工程师想把工具调用失败率压下一个数量级的平台组以及怀疑自己选型有问题、但还没定位到具体环节的架构师。1. 先定义问题“触达”到底指什么智能体为什么够不到目标1.1 三个反复被提到的“够不到”现场先举三个很有代表性的场景。第一个场景是“工具路由遗漏”。系统里注册了221个工具但任务来到时Agent只见过顶层菜单里那十几个。原因是我们只做了工具名前缀匹配没有按任务意图维护索引。结果是业务同学用自然语言提问时智能体选了一个表面上相关、但数据完全不支持需求的工具。第二个场景是“上下文遮蔽”。任务进行到第8轮需要调用“客户应付账款汇总”工具但前置对话已经把上下文窗口挤得只剩1500个token。模型拿到工具返回的是一大张表格塞回去时先被截断了后半部分最终它只盯着前半部分写出结论。这个错误很隐蔽因为系统日志显示“调用成功”没人看到截断发生在上下文压缩环节。第三个场景是“半截返回信息被当作最终答案”。外部接口返回200但明细字段被上游限流策略裁剪成“暂无”。Agent不区分异常值和特殊业务状态码直接告诉用户该客户无应收款项。后来我们查接口文档才发现“暂无”和“金额为零”在业务上是完全两回事。这三个场景的共同点是它们都不在模型推理层面而在Agent和外界的连接层。推理再强拿不到对的数据结果也是错的。1.2 把“触达”拆成三类可度量的范围我后来和团队复盘时把触达拆成三类范围分别对应不同性质的故障触达维度定义典型失败信号可以观察的指标工具触达目标工具能否被正确发现并调用路由遗漏、参数错配、权限报错工具发现率、调用成功率、参数校验失败率数据触达任务所需上下文能否完整保留并送达截断、召回碎片、字段缺失上下文保留率、字段完整率、召回命中率流程触达多步任务中每一步产物能否正确传到下一步任务中断、重复调用、死循环任务完成率、平均步数、步骤间失败率拿一个退款流程举例工具触达指Agent能不能找到“退款创建”接口数据触达指它能不能拿到订单号、金额、用户身份并且这些字段没被打折流程触达指创建退款之后下一步的“通知用户渠道”能不能拿到上一步的操作结果。前者不行就换路径中者不行就得修上下文后者不行就是状态同步的问题。1.3 为什么不能只把锅甩给模型能力很多团队遇到这类问题第一反应是换更大的模型或者加更多few-shot示例。我的实际体会是模型的能力边界确实存在但大多数事故发生在“模型能看到什么”这一层。你给模型一张残缺的地图它再聪明也只能规划一条残缺的路线。这也是“Agent-Reach”这个名字的由来。我不关心模型本身有多大我只关心在具体任务里它到底能触达哪些工具、哪些数据、哪些流程节点。把这些东西变成显式的、可配置、可观测的规则比单纯升级模型参数更稳、更快。2. 能力目录把“能到达什么”变成一张可以查的路由表Agent-Reach 的地基不是一个大模型而是一张能力目录。它不像传统API网关那样只存接口路径和鉴权方式还要存工具之间的前置关系、依赖顺序、上下文成本以及它能服务哪些业务意图。2.1 注册工具时不止写接口地址还要写“触达条件”我们早期注册工具只写三样名字、接口地址、参数schema。结果就是工具之间没有先后关系Agent只能靠模型猜。加入Agent-Reach后每条工具多了一组字段用来写明“什么情况下这个工具能碰、碰之前必须完成什么”。- id: order.create display: 创建订单 input_schema: customer_id: string sku_id: string quantity: integer prerequisites: - condition: stock.query_result.available input.quantity required_tool: stock.query - condition: auth.has_role(user, buyer) affects: - cart.release - payment.request reach_score: 0.92这段配置解决了一个特别实际的问题工具的选择顺序。原来Agent经常不看库存就下单现在“创建订单”这条工具的前置条件里明确写了依赖“库存查询”路由层会先把库存查询工具放进候选列表等返回结果满足条件之后再把“创建订单”暴露给模型。也就是说这不再是提示词层面的建议而是流程层面的约束。2.2 用可达性分数排序而不是把所有工具都堆给模型很多工作流引擎的做法是把候选工具按字母序或注册时间排个序全塞进上下文。但工具数量一上百模型的选择准确率会明显下降而且token开销爆炸。我们改用了一个简单的启发式得分叫“可达性分数”reach_score 0.4 * 历史调用成功率 0.3 * 权限匹配度 0.3 * 任务意图相关度。这三个子分都是离线算好、在线查表的不需要实时跑模型。权限匹配度来自用户角色和工具roles字段的重叠程度任务意图相关度则来自我们在能力目录里给工具标注的业务意图标签。排序后只把前5个工具放进候选列表模型在这5个里面做选择准确率反而比之前几十个工具一起给要高不少。这个思路不复杂但它意味着你不能再偷懒每个新工具上线时都必须维护成功率和意图标签。否则分数会失真排序也就失去了意义。2.3 动态可见性不同角色看到的能力目录不一样能力目录同时承担了权限收敛的作用。同一个工具不同角色看到的优先级不同。比如客服人员能看见“查看客户联系人”和“查询订单状态”但看不到“发送营销短信”运营人员能看到“创建优惠券”但看不到“删除优惠券”。routes: customer_service: - crm.contact.read - order.status.read operations: - coupon.create - crm.contact.read finance_ops: - order.create - invoice.send曾经踩过一个坑我们让Agent在内部问答里能查应收款明细结果普通客服通过追问也能触发这个工具一口气把全量客户余额信息拉了出来。后来把这层角色和工具的映射搬进路由表每次任务开始前先解析用户身份再决定哪些工具可以出现在候选列表里。这比在提示词里写“不要访问无关数据”可靠得多。3. 触达轨迹记录每次访问让失败可以被复现能力目录解决的是“应该能到哪”但系统里还有很多“实际到不了”的意外情况。为了把这些意外变成可分析的数据Agent-Reach有一套统一的触达轨迹记录每次工具调用都会生成一条结构化的入账。3.1 一次任务的一串脚印触达事件的结构我定义了一个很简单的JSON结构核心字段就十几个尽量不引入额外复杂度。{ trace_id: tr_8f2a11b3, task_id: task_refund_2093, agent_id: assistant-negotiation, step: 4, intent: resolve_refund, tool_selected: refund.create, tool_returned: { status: ok, body: refund_id: RF-4432 }, context: { remaining_tokens: 3120, compressed: false }, reach_grade: pass }叫“触达轨迹”而不是“调用日志”是因为我们关注的不只是“调用了没”还包括调用前后上下文状态。字段里的remaining_tokens会告诉我们这次调用发生的时候模型上下文还剩下多少余量compressed字段则记录是不是刚刚做过压缩。这两个字段帮我们定位了很多“看似调用成功实则结果不可用”的问题。3.2 失败归因怎么判断是工具坏了、权限不够还是上下文断了触达轨迹收集了一段时间后我们发现失败类型其实可以归成几类每一类的处理方式完全不同。做个表放在一起最直观失败信号大概率根因建议处理路径返回权限错误用户角色和工具roles不匹配走权限申请或切换可替代工具调用超时/网络错误外部系统不稳定指数退避重试超过2次人工介入返回字段为空/缺字段上游限流或接口裁剪检查字段完整率补充查询逻辑上下文剩余token不足前序步骤塞了太多内容触发上下文压缩或改走子任务工具不在候选列表路由意图标签缺失回到能力目录补标签而不是硬塞给模型有了这张对应表每天巡检就变成了一道判断题而不是翻日志大海捞针。3.3 我在记录过程中踩的坑别把敏感字段写进轨迹触达轨迹上线第一天我们就出过一次问题。当时为了排查一个订单查询问题把用户邮箱和手机号直接打进了事件字段。虽然只在内部日志里但内部日志同样要守最小化原则。后来我在写入函数里加了一条白名单规则凡是匹配身份证、手机号、邮箱、地址等模式的字段一律替换成掩码形式。{ input: { customer_id: cus_****, phone: 138****1234, note: *** } }这个改动对排查效率影响不大因为trace_id还能去原始工单系统里找回完整数据但安全合规的压力小了很多。如果你想在自己的项目里复用这套东西敏感字段掩码这一步千万不要省略内部日志不是一个可以随便存全量个人信息的地方。4. 把触达范围撑大的三条腿上下文压缩、就近路由、失败回退能力目录和触达轨迹是基础设施真正让任务完成率变高的是三个运行时机制上下文压缩、就近路由、失败回退。这三个机制对应三类常见问题token不够用、路由选不准、下游调用不稳。4.1 上下文压缩把不需要的细节折叠但保留“可回查”线索任务循环一长上下文一定会膨胀。我们的策略不是无脑截断而是分块压缩。对于已经完成步骤的完整工具返回值保留摘要并把原始事件的关键位置写到摘要下面。这样模型在需要细节时可以通过摘要里的trace_id反查完整数据。举一个实际例子前序工具返回 stock.query: {sku: P-102, stock: 3220, warehouse: [SH-1, BJ-2], eta: 2025-04-10} 压缩后入上下文 库存查询已完成可用库存尚充足具体仓储明细见 tr_82fe91。 如果后续步骤需要确认某个仓库是否有货再调用 stock.query 带上次的trace_id。这个“可回查”的压缩方式比单纯把数据删掉要稳得多。它既省了token又没有真正丢失信息因为你给模型留了一个主动拉取详情的钩子。实际运行中我们经常在最终汇总阶段看到模型回头追问某个仓库的具体地址而这种追问完全不会占用前序步骤的上下文额度。4.2 就近路由先过滤再排序最后让模型做选择很多Agent框架喜欢把所有工具都塞给模型让模型自己决定。可工具一多模型就像你在一个货架很混乱的超市找酱油效率并不高。Agent-Reach 的做法是先把候选列表过滤到一个很小的集合再让模型做最终选择。def pick_tool(intent, candidate_tools, user_context): # 1. 权限过滤 accessible [t for t in candidate_tools if t.has_access(user_context)] if not accessible: return None # 2. 按可达性分数排序 accessible.sort(keylambda t: t.reach_score, reverseTrue) # 3. 只留top5给模型决策 shortlist accessible[:5] selected model.choose_tool(shortlist, intent) return selected这个逻辑很简单但效果很明显工具误选率下降最明显的是第10轮以后的任务。因为越到后面上下文越杂给模型的候选越少反而越不容易被无关工具干扰。4.3 失败回退不是所有失败都需要让用户重新输入早期看到工具失败就直接把错误抛给用户这是最差的体验。Agent-Reach 把失败分成可重试和不可重试两类。可重试的按照策略自动处理不可重试的才转到人工。我们预设了一个回退优先级按顺序尝试权限失败先检查是否有替代工具没有则引导用户走身份授权入口。超时或5xx错误指数退避重试一次间隔从2秒开始最多三次。参数不满足前置条件回到最近一个可满足条件的前置工具重新执行一次。上下文不足触发上下文压缩再重新发起调用。这个回退不是无限循环。每次回退都会写入触达轨迹的同一根trace_id如果连续两次回退仍失败就生成一条告警并移交人工。让智能体自己挣扎一会儿不等于让它无限挣扎。4.4 这套机制上线后我们迭代前后的对比为了直观我贴一张当时记录的数据指标改造前改造后一个季度多步任务完成率68%91%工具误选率22%6%上下文截断导致的结果错误每周约15起每周约2起用户主动反馈“答案不对”每周12次每周4次数据可能有一点幸存者偏差因为优化过程中同时也在换更稳的模型版本但我比较确定的是路由和回退机制贡献了其中大半的提升。因为它们解决的并不是偶发的推理幻觉而是结构性的够不到问题。5. 三个让我重新调整设计的实战案例理论说得再好终归要落到业务里。这里分享三个真实案例每个都逼着我改了Agent-Reach的某个设计。5.1 案例一客户信息查询功能始终读不到扩展字段我们的CRM里有200多个自定义字段但智能体查询客户信息时只读到客户名称、电话、地址这些基础字段销售团队自定义的“跟进阶段”“意向等级”始终为空。排查触达轨迹后发现agent确实调用了crm.contact.read但返回体里根本没带扩展字段。原因不在Agent而在能力目录注册时这个工具只给了固定的字段schema没把动态自定义字段的说明写进去。后来我们在工具定义里增加了field_metadata每次调用前按需加载字段描述并把用户高频使用的自定义字段名做了同义词映射比如“意向等级”同时匹配intent_level、lead_level、buying_phase。改完之后查询返回字段完整率从47%提升到了96%。这个案例给我的教训是工具触达不只是找到接口还要让工具描述跟业务语言对得上。5.2 案例二知识库问答把引用的关键前提弄丢了知识库问答是最隐蔽的一类故障。用户问“应收账款的账期是多少”Agent从向量库里召回三段内容其中一段说“本政策仅适用于预付客户”但另两段没有这个限定条件。结果Agent把适用范围扩大成了所有客户。它不是不会读而是召回的语境里关键的限定句被放在了一段它没引用的文档里。解决方式是给知识库召回阶段增加“前提保留”策略如果一条知识被标记为“限定性条款”向量召回时必须把它的上级标题和适用范围一起带进上下文。这相当于在做数据触达时把上下文当成一张关系网而不是三块独立碎片。后来我们还做了一个更细的规则限定性条款所在的文本块在压缩时不允许被摘要掉必须原样保留。5.3 案例三先查库存还是先建预订单顺序选反了电商场景里Agent需要根据客户要求创建预订单。第一次上线时它经常跳过库存校验直接建单最后发现仓库无货整条流程回退客户体验很差。根因很简单工具定义里没有前置关系。后来我在能力目录里给“创建预订单”加了前置条件要求必须存在库存查询结果且可用量大于需求量。路由层会先把库存查询工具放进候选列表等条件满足后再让“创建预订单”出现。这个改动只花了一个下午但把该场景的任务失败率从15%降到了2%。这个案例解释了为什么能力目录必须是运行时的路由约束而不只是开发期的注释文档。5.4 这些案例背后的共同点三个案例分别对应了工具触达、数据触达、流程触达。它们看起来是三类不同问题但修复手段都在同一个地方Agent-Reach的能力目录和触达轨迹。把“工具能不能被找到”“上下文能不能保留到位”“流程能不能按顺序走”这三种能力集中管理而不是散落在每个Agent的提示词里才是这套方案的真正价值。每次出问题我们几乎都能在一张路由表或者一类触达事件里定位到原因改完配置以后所有Agent都会自动生效而不需要一个一个去改提示词。6. 生产环境里真正难缠的边界问题权限、限流、上下文预算上线三个月后功能基本稳定真正让人头疼的东西变成了一些边界和成本问题。这一节写三个最值得注意的。6.1 触达范围不等于授权范围外部系统权限必须按用户角色传递Agent-Reach 很容易让人产生一个误解既然智能体什么都能调那它就代表最高权限。这是非常危险的。如果路由表只按系统账号鉴权而不把发起任务的用户身份传下去可能出现用户A通过智能体查到了用户B的订单数据。我们的做法是在每次任务开始前生成一个权限上下文绑定发起人的角色和资源范围。所有外部工具调用都必须携带这个上下文服务端再校验一次工具级权限。总结成一句话触达能力可以很宽但用户的触达边界必须很窄。6.2 外部系统的限流阈值必须写进能力目录很多外部系统都有调用频率限制但Agent发起调用是不认人的。同一批客服同时在线每人发一次查询外部接口很容易瞬间被打爆。后来我们在能力目录里给每个外部工具增加了一个元数据字段rate_limit同时接入到一个简单的令牌桶服务。当某个工具的实时调用量达到阈值的80%时路由表会自动调低该工具的reach_score把请求优先分给其它可承载的通道。这个设计不算多高级但它真正把“外部系统稳定性”变成了智能体决策的一个因子而不是等着下游报警。以前我们总以为智能体只会被模型坑后来发现它也会被上游接口的脆弱性坑。把限流阈值纳入路由决策以后这种坑至少从偶发变成了可控。6.3 上下文预算管理宁可少给也要保证最后几步能走压缩做久了我们意识到它不能解决所有问题因为总有些上下文是压不掉的核心信息。所以Agent-Reach 里的任务在启动时会做一个非常简单的预算分配。比如给整个任务分配的上下文上限是12000个token前8轮最多用6000保留4000给工具返回和最终生成剩下2000作应急。这样设计的原因是我们发现很多任务失败发生在第9轮到第12轮原因不是前几步信息不够而是最后几步没有上下文空间了导致模型拿不到最终要汇总的数据。与其让前几步都详尽发挥到极限不如把预算拆好保证流程收尾时有足够的余量。这有点像跑长跑最累的不是起步而是终点前那一段。每次压缩模块被触发时我们也会在触达轨迹里打一个compressed标记用来统计哪些任务类型最容易出现预算紧张后续再针对性做精简。6.4 升级Agent-Reach之后运维侧的日常巡检最后说下日常运维。我建议每天晚上跑一次触达轨迹扫描任务把当天满足以下条件的轨迹挑出来reach_grade不是pass或者带有truncated标记任务步数超过15步但完成状态是失败同一种工具在同一时间段内连续出现3次失败。把这些轨迹导出成一份简短的报告第二天早上花十五分钟扫一遍。这一步看起来不起眼但它是整个Agent-Reach体系里边际收益最高的一环。因为系统不会自己变好只有你天天盯着触达轨迹才能在前一天的问题还没扩散成用户投诉之前堵住它。多智能体项目的复杂度恰恰就藏在这些看似琐碎的边界细节里。