Agent-Reach：多Agent系统触达问题的设计与实践

搞了大半年多Agent系统，我最深的感受是：模型选型、提示词工程、工具调用这些环节确实卷得厉害，但真正让系统在线上跑不起来的，往往是一个特别不起眼但又特别致命的问题——Agent之间互相"够不着"。

这个项目叫Agent-Reach，名字本身已经说明了一切：Agent加上Reach，智能体触达。它不是一个模型，也不是传统的工作流引擎，它解决的是多Agent系统里最基础也最容易被忽略的那件事：任务能不能准确、可靠地触达正确的Agent，结果能不能完整收回来。用大白话说，就是活派得下去，活儿干完了成果拿得回来，中间出了岔子还能有人兜底。

如果你正在从单Agent往多Agent迁移，或者你搭了好几个Agent但总是出现任务发出去没人接、多个Agent抢同一个任务、Agent之间互相等待导致整条链路卡死之类的问题，这篇内容应该能帮你省下不少排查时间。我会把Agent-Reach的设计思路、一个真实场景的落地过程、踩过的坑和排查方法完整拆开讲。

1. 多Agent系统里，最容易被低估的不是模型而是"触达"

1.1 为什么Agent-Reach会出现在这个时间点

过去一年，我见过太多团队把多Agent系统搭起来，然后卡在半路。单Agent的时候一切都很简单：一个Agent、一套Prompt、几个工具，坏了看日志，慢了调模型。一旦拆成多Agent，问题就全变了——Agent A需要调用Agent B的结果，Agent B又要等Agent C的数据，而Agent C压根不知道有Agent A和B的存在。整个系统就像一群人临时拼了个剧组，每个角色都有自己的剧本，但没人负责对词。

这个时间点出现Agent-Reach这类设计，本质原因是Agent的"能力密度"上来了：单Agent能做的事情越来越多、越来越复杂，于是大家开始倾向于用多个专业Agent协作的方式来解决问题。可一旦拆开，第一道坎不再是"这个Agent能不能把活干好"，而是"这个Agent能不能触达它需要的资源和其他Agent"。模型能力的提升是加法，触达问题的解决是乘法——触达做不好，模型再强也是白搭。

我更愿意把触达拆成四个层面来理解，这也是Agent-Reach整套设计的原点。

1.2 "Reach"到底在说什么：四层可达

跑过一段多Agent系统之后，我发现"可达"这件事远没有表面看起来那么简单。完整地拆开来，它至少包含四层：

• 工具触达：Agent能不能稳定调用到它需要的工具、API、数据库。这一层最常见的问题是权限配好了但网络不通、API限流没做导致一会儿能调一会儿不能调，以及工具返回值格式跟Agent预期不一致。
• 上下文触达：Agent A产出的结果能不能完整、结构化地成为Agent B的输入。很多团队的"触达失败"根本不是网络问题，而是A输出的是一大段自然语言，B没法从中提取有效字段，两边无法对齐。
• 目标触达：任务从发出到最终完成，业务目标是否真的达成。任务虽然跑了、日志也绿了，但结果根本不是发起方想要的——这是最隐蔽也最糟糕的一种"未达成"。
• 资源触达：在并发量上来之后，Agent有没有足够的计算资源和时间片去完成任务。一个Agent被任务塞满，其他任务只能堆在队列里干等，这也是一种触达失败。

Agent-Reach这套设计一开始就是围绕这四层来做的。后来实际操作中我们发现，工具触达和目标触达靠基础设施能解决大半，上下文触达和资源触达则必须在框架层面做约束。所以整个系统从最早的"消息转发器"慢慢演化成了一个带路由、带控制、带可观测性的Agent协作基座。

2. Agent-Reach的核心设计：把"派活"改成"自取"

2.1 能力声明与语义路由

很多多Agent编排工具天然带着"中心化调度"的思路：总控Agent想清楚活怎么干，然后按顺序调用其他Agent。Agent-Reach没走这条路，它采用的是"能力声明 + 语义路由"的机制。每个Agent启动的时候，要明确告诉系统自己有什么本事、接受什么输入、输出什么结构。任务进来的时候，系统把任务的需求和所有Agent的能力描述做匹配，找到最合适的接收方。

这个机制的灵感来源其实特别朴素——你到一个公司办事，如果每个部门门口都贴着"本部门负责什么、需要什么材料"，你就不用站在大厅里到处抓人问了。Agent-Reach只是把这张"部门公告牌"搬进了代码里，并且让需求描述和能力公告之间能做语义比对。

实践中我们用的是意图文本加JSON Schema的方式。每个Agent声明一个能力列表，每条能力包含一个能力ID、一段自然语言描述、输入和输出的JSON Schema。任务发出时带一个意图ID和结构化负载。优先做精确匹配：意图ID直接对应某个能力；精确匹配不到，就用Embedding把任务意图描述和所有能力描述做向量比对，低于一定阈值才判定为"无人可接"。

这套机制解决的核心问题是"任务发出去没人认领"。单Agent时代不存在这个问题，因为所有请求都是你自己的；多Agent时代任务会在系统里飘来飘去，必须有一个明确的路由规则来决定谁接。Agent-Reach在这个环节上做得比我想象中节省力气——不需要每个请求都写清楚"发给谁"，只需要写清楚"要什么"，剩下的交给路由。

2.2 任务总线：为什么不走同步RPC

早期我试过一个看起来更简单的方案：让Agent之间像微服务调用那样直接RPC，A调用B的HTTP接口，拿到结果再做下一步。实际跑了不到两周就放弃了。

同步RPC在多Agent系统里有几个绕不过去的麻烦：第一，Agent B可能还在处理上一个任务，A的调用只能干等，超时时间设多短都有问题；第二，一个Agent如果同时被多个Agent调用，调用方会直接感知到被调方的不稳定，稍有抖动整个链路全是红色告警；第三，链路深了之后，A调B、B调C、C调D，任何一层慢都会把上层全部拖住，线上定位问题需要一层层翻日志。

Agent-Reach的解法是引入任务总线：所有任务不直接发给某个Agent，而是投递到总线上，由路由层找到接收方，把任务塞进对方的队列；接收方处理完之后再把结果写回总线，发起方通过一个收据凭证去取。

这个设计的本质是把"点对点调用"换成了"发布订阅加指定路由"。用生活里的例子类比，不是A直接打电话给B让他干活，而是A把需求单投进公用的政务大厅窗口，B在窗口看到能接的单就收下并办理，办完把回执放到取件柜，A凭短信验证码来取。这样一来A和B之间完全解耦，任何一方出问题都不会直接拖垮另一方。

这里有一个人人都该明白的道理：Agent协作的稳定性，大部分不是靠提升每个Agent的质量来实现的，而是靠降低Agent之间的耦合度。任务总线就是那个耦合度控制器。

2.3 失败重试与降级策略的取舍

任务总线上线之后，第二个要解决的是失败怎么办。Agent调用跟人干活一样，不可能每次都成。Rate limit了、下游API挂了三分钟、模型服务超时报错，这些都太常见了。芝麻大点的事要是每个都直接失败返回，整个系统就没法用了；要是无脑重试，分分钟把重试风暴引出来。

Agent-Reach在失败处理上做了三件我认为很有参考价值的事情：

第一，区分"任务级失败"和"处理级失败"。任务投递成功但处理者崩溃，任务可以重新入队；任务本身语义不对、根本没法处理，就不重试直接抛回发起方。这个区分简单，但实际项目中我发现很多人把它们混在一起处理，导致一个语义错误的任务被反复重试，白耗资源。

第二，重试必须带退避和随机性。固定间隔重试是最容易引发重试风暴的写法；我们改成了指数退避加抖动，第一次重试延迟1秒，第二次4秒，第三次9秒，再配合一个全局的令牌桶防止同时重试的请求过多。

第三，降级永远优先于重试。如果一个任务的主接收Agent不可用，路由层会找次优接收方；次优也没了，就走兜底规则，比如调用模型自己生成，或者直接把任务挂起、让发起方决定下一步。重试是"再给一次机会"，降级是"换条路走"。真实系统里很多情况下换条路比重复尝试更靠谱。

3. 一个真实场景的落地过程

3.1 场景与角色拆分

讲完原理，我用一个真实跑过的场景展示落地路径。某电商公司的会员运营团队要做一个大促活动的内容自动生产与投放流水线。人工时代的流程是：运营专员盯竞品、写文案、审核合规、投放、盯数据。我们要用多Agent系统把它自动化。

角色拆出来是四个：

• 竞品情报Agent：负责抓取竞品活动页、汇总优惠力度和主打卖点。
• 内容创作Agent：根据情报生成不同渠道的推广文案。
• 合规审核Agent：检查文案里有没有违禁词、敏感夸大表述。
• 投放执行Agent：对接投放系统创建广告任务并返回投放ID。

如果不用Agent-Reach，这四个Agent之间的直接调用链会是这样：情报Agent完了通知内容Agent，内容Agent完了通知合规Agent，合规完了通知投放Agent。看着闭环挺完整，但上线之后立刻发现问题：一次大促要生成几十条文案，每条文案都要合规审核，如果合规Agent因为模型临时故障慢了几分钟，后面几十个任务全部堵住。内容Agent干等合规Agent，投放Agent干等内容Agent，整条流水线从"并行协作"退化成了"串行排队"。

用上Agent-Reach之后，整个流程改成任务驱动：运营侧一次性发出几十个内容生产任务，每个任务是一个独立的意图，系统根据能力匹配自动路由到竞品Agent采集、内容Agent生成、合规Agent审核、投放Agent执行。谁有空谁接单，某个环节慢了其他任务不受影响，最多是自己的任务完成时间长一点。

3.2 关键配置与代码实现

Agent-Reach的配置核心是一个能力声明文件。我们当时用YAML写的，内容大致是这个结构：

agents: content_writer: capabilities: - id: article.generate description: 根据主题和资料生成营销文案 input_schema: topic: string source_material: string channels: array output_schema: article: string title: string timeout_ms: 120000 max_concurrency: 20 compliance_checker: capabilities: - id: content.review description: 检查文案的合规风险 input_schema: content: string rules: array output_schema: passed: boolean reasons: array timeout_ms: 30000 max_concurrency: 10 routes: - intent: article.generate preferred_target: content_writer fallback_target: none - intent: content.review preferred_target: compliance_checker fallback_target: reviewer_lite

这里有两个细节值得说明。第一个是timeout_ms不是随便填的：内容生成要等模型输出长文，给了120秒；合规审核只做短文本判断，30秒足够。超时设置必须和任务本身的耗时量级匹配，设太短会把正常慢任务误判成失败，设太长又会拖住整个链路的失败恢复速度。第二个是fallback_target——优先接收方不可用时可以降级到谁。合规审核的降级目标是reviewer_lite，一个专门跑轻量规则检查的低成本Agent，宁可先用规则顶一下也不能让全流程都断掉。

任务投递的代码在调用方侧很简单，核心是一个异步发任务拿收据的动作：

from agent_reach import TaskBus bus = TaskBus.load("agent-reach.yaml") task = bus.create_task( intent="article.generate", payload={ "topic": "夏季防晒新品", "source_material": "竞品情报Agent汇总", "channels": ["wechat_moments", "xiaohongshu"], }, ) receipt = task.dispatch() # 立即返回，不代表完成 result = receipt.wait(timeout=180) # 阻塞等待最终结果 if result.is_success(): review_task = bus.create_task( intent="content.review", payload={"content": result.data["article"], "rules": ["广告法V1.1"]}, ) review_receipt = review_task.dispatch()

dispatch()和wait()的分离是这个设计里我认为非常关键的一步。发起方投递任务的同时拿到了一个收据，立刻可以去做别的事；等需要结果时再阻塞等待。这样一来，即使是"一个任务必须依赖另一个任务结果"的串行场景，发起方也不会在等待过程中白白占用系统资源。

3.3 触达率观测：怎么确认系统在工作

系统跑起来之后一个特别现实的问题是：你怎么知道触达是好的还是坏的？Agent-Reach里我加了一套最基础的可观测指标，所有任务都记录埋点。可以认为是"触达率观测"，具体四个指标我盯着看：

• 任务路由命中率：发出的任务里，有多少被成功匹配到了接收Agent。
• 平均入队等待时间：任务到达总线到被Agent接单花了多久。这个数字如果持续上涨，说明某个Agent的负载已经接近饱和。
• 重试率：任务经历了一次以上重试的比例。正常水平应该在5%以下。
• 结果回收率：任务处理后，发起方成功拿到结构化结果的比例。这个是最终底线，低于95%就要排查是不是协议层出了兼容问题。

落地第一个月，靠这套指标我们抓到了不少隐形问题。比如竞品情报Agent有一段时期的平均入队等待时间从2秒涨到40秒，排查后发现不是Agent变慢了，而是某个上游把抓取频率调高了两倍，任务量暴增但Agent的并发数没上调。这种问题如果只盯单个任务成功率，基本看不出来。

4. 实操中踩过的坑与排查记录

4.1 协议膨胀让所有Agent互相看不懂

Agent-Reach上线第二周，我们碰到一个特别诡异的现象：内容Agent生成的结果，合规Agent有时候能读，有时候不能读。后来排查发现，内容Agent的输出结构悄悄变了——某次迭代时在输出里多加了一个字段，但没更新能力声明里的output schema。老任务和新任务混在一起，合规Agent接收到两种不同结构的JSON，解析逻辑只能兼容其中一种。

这就是协议膨胀问题。每个Agent都在独立迭代，输出结构能加字段就加字段，能改类型就改类型。如果没有一个全局约束，用不了几个版本，Agent之间就会互相"听不懂"。我们用了一个笨但有效的办法：能力声明文件里的JSON Schema就是全局契约，任何输出变更必须先改契约、过校验才能上线；另外加了schema版本号，Acknowledged Agent在任务回执里带上自己实际使用的schema版本，发起方一比对就知道结构是不是最新的。

我的体会是：多Agent系统里的"形同鸡同鸭讲"大部分不是模型问题，而是数据结构漂移问题。Agent-Reach在这个坑上给我最大的教训是——能力声明不是写一次就完事的，必须和代码版本一起走，否则线上的Agent一定会进化成你不认识的样子。

4.2 互相等待死锁：Agent A等B、B等C、C在等A

死锁这词以前只在数据库和并发编程里让我头疼，没想到Agent系统里也能遇到。一次大促演练中，整个流水线突然全部挂起，所有任务都在排队的初始状态。排查半天，发现链路是：竞品Agent需要内容Agent给它一份往期爆款文案做风格参考，内容Agent需要合规Agent先给它审核模板，合规Agent又在等竞品Agent提供最新的违禁词清单。三个Agent互相等，谁都没法先动手。

Agent-Reach里针对这类问题做了任务依赖图检测：每次投递任务时记录任务的依赖方向和等待关系，如果发现循环等待就立刻切断，并把环路中优先级最低的任务标记为失败返回给发起方。另外在路由配置里加了一条硬规则：Agent执行任务期间不允许发起对"自己正在等待方"的依赖调用。这有点像人办事的时候禁止"我等你、你等他、他等我"式的尬局。

死锁解决之后我们做了一个更重要的调整：把任务依赖的方向尽量改成单向。具体到这个场景，合规Agent的违禁词清单不再实时依赖竞品Agent，而是每天早上由运维脚本预生成一份快照放在共享存储里。让依赖方向变简单，比在死锁发生以后再靠检测去恢复要省心得多。

4.3 上下文变胖拖垮整个链路

还有一个很常见的坑，说出来很多人都能共鸣：为了不让下游Agent"失忆"，发起方习惯把尽可能多的上下文塞进任务负载。我们有个运营同事配置的内容生产任务里塞了整场大促的全部讨论记录、历史投放数据、还有一份50页的产品手册。内容Agent每次接单都要读取这么一坨东西，Token消耗暴涨，响应延迟从平均10秒变成40多秒，严重一点的直接触发超时。

这个问题在Agent-Reach里最后是用"上下文裁剪"缓解的：任务负载里允许挂上下文引用而不是上下文本身。Agent真正需要时按引用去取，不需要时什么都不加载。另外每条能力声明里加了context_budget的限制，超过预算的上下文自动走摘要压缩。

回过来说，很多Agent触达慢的问题不是模型跑得慢，而是你给人家的材料太多了。给Agent喂东西跟给人布置工作一个道理，你把一个200页的PPT塞给同事说"你看看这个再告诉我重点"，他光是看就得看一上午。Ant的机制本质上就是把这个道理翻译成了代码规则。

4.4 重试风暴打崩下游API

第四个大坑出在重试上。某次投放API短暂抖动，投放Agent连续失败后开始重试。由于每个内容任务都走到投放这一步，几十个任务几乎同时触发了重试，投放API直接被重试请求淹没，原本正常的请求也挤不进去。

Agent-Reach最后上一套组合拳：全局令牌桶对发往同一目标的请求限流；重试间隔用指数退避加随机抖动；每个目标上游服务加了个熔断开关——连续失败达到阈值后自动熔断，新任务直接进降级队列而不是继续尝试。

这个坑给我的教训特别深：重试机制设置得好是可靠性，设置不好就是自毁设施。任何重试都必须假设"下游现在可能已经不行了"——所以重试的压力要慢慢给，更要多线并减缓重试。

4.5 常见问题速查表

把线上踩过的问题整理成了一张速查表，遇到同类问题可以按图索骥：

5. 小团队从零接入Agent-Reach的最小路径

5.1 第一步：先跑通两个Agent的"直达"

如果你的团队第一次接触这类设计，千万不要一上来就规划四个以上Agent的大协作。我吃过这个亏——第一次就把情报、内容、审核、投放四个Agent全部接入，配置文件写了三百多行，结果调试的时候什么都慢，因为变量太多。

最小路径应该从两个Agent开始：一个发起方，一个执行方。发起方发任务，执行方接任务，双方通过总线通信。先不整那些花哨的语义路由、Embedding匹配，直接用最死板的精确意图ID路由。这个阶段的目标是确认任务能发出去、有人能接、结果能收回来。我们当时就先跑了一个"信息收集Agent"和一个"格式化输出Agent"，整整一天都在调这一条链路。

5.2 第二步：加上能力声明和路由

两个Agent跑通之后，再往链路里加第三个Agent，并且把精确路由升级成语义路由。这一步的意义是让路由层真正开始发挥作用。

我们做这个升级的时候，特意把能力声明文件里的描述写详细了一点。比如不是只写"article.generate"，而是写"根据主题和资料生成营销文案，输出包含标题、正文、渠道建议"。描述越清晰，语义路由的命中率越高。这一步的目标是验证一个新Agent加入时，不需要改其他Agent的任何代码，只需要更新自己的能力声明和全局路由配置。如果做到这一点，Agent-Reach带来的解耦红利就真正体现了。

5.3 第三步：逐步控制超时、重试、可观测性

基础链路稳定后，再开始引入工程化能力：超时设置、重试策略、熔断、降级、可观测指标。我的建议是每一次只加一项，观察一段时间再说。重试和超时的参数尤其要基于真实数据来定，先看一个月的平均完成耗时，再设超时和重试次数。

最后分享一个这几轮折腾下来最值得记住的感受：多Agent系统运行的稳定性，本质上是"触达"的稳定性；而触达的稳定性，靠的不是把某个环节做得多么完美，而是让每个环节都可以失败、可以被替换、可以被观测。Agent-Reach在这个项目里给我最大的价值不是某个单点功能，而是它逼着我从"怎么让Agent更聪明"的思路里跳出来，去思考"怎么让Agent之间协作更皮实"。这个思路上的转变，直到今天做任何多Agent相关的系统我都在用。