AI Agent 这波热潮我是从头跟到尾的。过去两年我做过不少大模型驱动的智能体从单轮对话到带工具调用再到把好几个职责不同的 Agent 串成流水线过程里最大的感受是四个字又爱又恨。爱的是它确实能提高产出恨的是它永远把“说干完了”和“真干完了”混在一起。直到我把 Agent-Reach 这套框架跑起来这个问题才算被系统性治住。这篇文章不聊概念只讲我是怎么设计它、怎么落地它、又在真实业务里踩过哪些坑。Agent-Reach 本质上是一套多智能体任务编排与触达确认框架名字里 Agent 好理解Reach 才是真正的核心——它强调的是“任务触达结果”。你可以把它想成快递系统每个 Agent 发出的不是“聊天记录”而是带有签收要求的任务包裹系统要做的是确保每一个包裹都真正到达目的地而不是被扔在某个中转站就算完成。适合正在做多 Agent 协同、AI 工作流编排或者被“Agent 看起来成功实则没落地”折磨过的朋友参考。1. 项目缘起Agent 圈不缺 demo缺的是“触达证明”1.1 名字拆解Agent 是主语Reach 才是灵魂Agent-Reach 拆成两个词来看Agent 指的是接入任务流的各类智能体节点。它们不一定是大模型本体也可以是大模型加工具、一个专用执行器、甚至某个外部 Webhook 服务反正只要在链路上作为任务执行方都算 Agent。但决定这套框架价值的从来不是 Agent而是 Reach。Reach 本意是触达、够到、覆盖。落到系统里我给它定义了非常具体的含义任何一个任务从上游节点出发都必须有一个可验证的目的地和一个签收证明做不到这一步任务状态永远不能算成功。好比我平时给快递做类比Agent 之间的对话沟通类似微信聊天聊得再热闹也不代表东西到了。Agent-Reach 要求每个任务都像快递包裹从揽收、分拨、运输到签收每一站都有记录。Reach 这个词强调的就是“到达”这件事本身。想让两个 Agent 协作先别急着让他们互相套话把“什么东西由谁发出到谁那里必须带什么签收证明”定清楚协同才能审计。1.2 我在真实业务里被反复折磨的三个痛点先说第一个痛点Agent 回复得无懈可击但业务动作根本没有发生。我做过一个客服场景让 Agent 判断订单是否满足退款条件符合就直接发起退款。测试的时候它回了一句“已为您申请退款预计1-3个工作日到账”句子挑不出毛病。但我去查退款单表发现一条记录都没多。原因非常简单模型没有真正调用退款工具它只是根据对话习惯“脑补”了一个执行结果。这在单轮 demo 里根本看不出来放到业务里就是事故级别的问题。第二个痛点是多 Agent 协作时完全无据可查。有一段时间我搭舆情分析流水线三个 Agent 分工信息采集、情感分析、报告生成。有一天报告生成 Agent 输出了一版“分析完成”的报告结果我拿原始数据抽查发现里面引用的几条内容根本不在采集结果里。原因是采集 Agent 当天返回空了情感分析 Agent 没校验上游数据就直接按空值跑报告 Agent 又找不到素材干脆自己编。整条链路没有任何一方主动说“我没有拿到东西”最后只能靠人肉翻日志才拼出真相。第三个痛点是成功和失败的判定标准稀烂。外部接口返回 200并不代表业务成功。有一次调用第三方工单 API接口返回 200我这边日志也记了“成功”结果对方系统里根本没有生成工单因为接口的 200 只代表“请求接收成功”真正落库是异步的异步那一步失败了我们完全无感知。我发现之后很长一段时间都在想同一个问题我们需要的不是“调用完成”的凭证而是“业务触达”的凭证。这三个痛点凑到一起指向的就是同一个答案任务需要一个独立的触达确认机制否则所有 Agent 协同都是建立在信任而不是证据之上。1.3 Agent-Reach 能管什么不能管什么想清楚边界是很多工程问题的起点。Agent-Reach 管的是任务触达过程中的路由、追踪、回执、重试和人工接管让“任务有没有真的送到”这件事可观测、可恢复、可审计。它能让我在报告 Agent 说“干完了”的时候去查它的上游采集 Agent 到底有没有返回非空数据集也能在第三方 API 返回 200 之后继续追查业务库里的记录是否真的增加了。但它不管单个 Agent 的模型能力。如果一个 Agent 本身没有能力解决某个问题Agent-Reach 不会变魔术把它变强它也不会替你做 prompt 优化、模型选型这些事。它的作用是加一层工程护栏让一个“会撒谎的执行者”没法轻易在状态机上留下成功记录。搞清楚这一点很重要因为不少人一听说编排框架就觉得万能最后期望落空其实是框架背锅。2. 整体架构控制、执行、回执三面分离任务才能被审计2.1 为什么 Agent 之间不能直接互相乱调最直观的做法是让 Agent 之间直接通信A 调用 BB 调 C看起来链路短。但一旦节点超过三个这种网状结构会快速失控谁负责重试超时之后消息往哪走两个 Agent 互相认为对方该处理某个 case 时怎么办数据格式不一致谁来做兼容更致命的是每条调用发生没发生、结果是否可信完全没有统一凭证最后变成一个分布式泥潭。我自己最早犯过这个错让几个 Agent 用 HTTP 回调互相调用第一周运行得很好第二周就开始出现“我在等你回执你却以为我已经做完了”的僵局。后来我彻底想明白一件事Agent 网络里的协调不能靠 Agent 之间的自觉必须靠一个中立的调度者统一负责流程控制。这个设计在分布式系统里很常见Agent-Reach 只是把同一套原则搬到了智能体场景里。2.2 三个面各管一摊回执面更要独立出来Agent-Reach 的架构可以拆成三个层面控制面、执行面、回执面。控制面是大脑负责任务路由、状态机流转、重试调度、超时管理。它知道每个任务当前处于哪个状态下一步可以去哪。执行面是手脚是真正干活的那批 Agent包括大模型驱动节点、工具封装器、外部 API 适配器。回执面是裁判它不参与业务执行只负责接收回执、校验证明、沉淀审计日志。层面职责类比控制面路由、状态机、重试、超时管理快递分拨中心调度员执行面各类 Agent 与工具执行任务快递员回执面校验结果证明、记录留存签收终端与台账我把回执面单拎出来是因为一个最朴素的道理不能让人既当运动员又当裁判。如果让执行 Agent 在执行完后自己判定“我成功了”那么你收到的成功消息永远只是它的自述不构成证据。回执面独立之后审计逻辑和业务执行逻辑分离哪怕某个 Agent 模型有幻觉汇报得天花乱坠回执面只看 proof 字段里可验证的硬证据。2.3 任务令牌与 trace全链路可追踪的根基任务令牌是一个任务从出生到结束都不变的唯一 ID。在 Agent-Reach 里每个外部请求进来第一时间生成 task_token 和 trace_id。task_token 面向业务相当于快递单号trace_id 面向追踪相当于整条链路的分拨记录流水号。所有日志、工具调用、回执、状态变更都必须带上这两个字段缺了就算异常。我习惯把整条链路的轨迹存成 JSON 数组每次流转追加一条。下面是一个示例结构。{ task_token: task_8f3a9c21e04d, trace_id: tr_7c21b5aa88ed, hops: [ {node: router, action: route, target: intent_agent}, {node: intent_agent, action: classify, result: refund_case}, {node: refund_agent, action: refund, receipt_ref: rcpt_a1b2c3} ] }看到 hops 数组越来越长的时候大概就能用肉眼判断链路卡在哪。你也可以类比成 HTTP 请求里透传 X-Request-ID只是 Agent 场景的“透传”更麻烦因为要穿过的不只是中间件还有 LLM 的上下文窗口和工具调用栈。我的做法是在所有工具函数的参数里强制加上 task_token 和 trace_id不传就不允许调用宁可麻烦一点也不要在出了问题时连是谁在什么任务里调了什么工具都查不到。2.4 一条任务从进入到完成的完整生命周期把流程过一遍会更容易理解三层怎么配合。第一步外部请求进入接入层控制面立即分配 task_token写入状态 pending。第二步控制面读取路由配置根据请求意图匹配目标 Agent状态变为 routing。第三步目标 Agent 通过控制面分发的任务描述开始执行状态变为 running。第四步Agent 执行完成把结果和自证材料封装成回执提交给回执面状态变为 awaiting_receipt。第五步回执面按规则校验 proof校验通过则把状态推进到 succeeded不通过则回到控制面进入重试或失败流程。这套生命周期看起来简单但每个状态都不是摆设。routing 状态防止任务被并行重复分发awaiting_receipt 状态专门用来给回执校验留时间避免“Agent 一交差就置成功”的问题。我就是靠这个状态区分把之前“第三方返回 200 但业务没落库”的问题暴露出来因为此时任务会一直卡在 awaiting_receipt直到业务库里的记录数量真的发生变化或者超时失败。3. 核心实现一份配置就能拼出一条可触达的业务链路3.1 Agent 能力描述清单先立契约再干活要让控制面能够把任务正确路由给合适的 Agent前提是每个 Agent 都向系统明确声明自己会什么、输入输出长什么样。我设计了一份 Manifest每个 Agent 启动时注册给控制面是 YAML 格式的契约文件。name: refund_agent version: 1.0.0 description: 处理订单退款申请的Agent capabilities: - refund_order - query_refund_status input_schema: order_id: string refund_amount: number output_schema: receipt: object receipt.refund_request_id: string receipt.timestamp: stringcapabilities 是路由匹配的关键字段控制面拿到任务需求后会根据能力名找对应的 Agent。input_schema 和 output_schema 则是给 Agent 的输入输出加约束。这段契约不只是给人看的文档控制面会用它对传输的数据做基础校验比如 order_id 缺失时直接拦截根本不会进到 Agent 那边。在 LLM 场景里输入输出校验的价值很大因为模型对字段类型的理解经常飘少一个字段就可能导致后续一整串幻觉。3.2 路由配置像写派车单一样写分流规则控制面的路由规则我最初用静态 YAML 来配后来的版本加入了模型动态分类能力。不管哪种方式配置结构都是相似的入口、意图分类、条件分流。routes: - entry_point: user_request_agent intent: classify_user_intent conditions: - intent_value: refund target: refund_agent - intent_value: delivery_question target: logistics_agent - intent_value: other target: human_handoffentry_point 是链路入口intent 字段就是控制面让入口 Agent 做的一次意图分类。分类结果决定后续走哪条分支。conditions 里每条 condition 的 intent_value 对应一个目标 Agent最后一个兜底是 other 时走人工交接这一步一定要留不然用户问了一个不在预期范围内的问题链路就直接死在那里。这里有一点经验要说路由条件里尽量用枚举值不要用自然语言。比如 intent_value 就固定写 refund、delivery_question、other而不是写“用户想退款或者咨询物流”这种开放式文本。模型分类时要让它输出枚举输出错了你可以用规则兜底让它输出自由文本你就得再用一个模型去解析模型说的话复杂度直接翻倍。3.3 回执校验怎么证明任务真的到了回执是整个 Agent-Reach 最核心的数据结构。我把它定义成独立的 JSON 对象由执行面提交给回执面核心字段有 node、task_token、status、result_path 和 proof。{ node: refund_agent, task_token: task_8f3a9c21e04d, status: ok, result_path: /outputs/refund_20250101_001.json, proof: [ {check: file_exists, path: /outputs/refund_20250101_001.json}, {check: db_count_increased, table: refund_orders, expected_delta: 1} ], cost_ms: 2840 }proof 字段是一个校验规则数组回执面会逐条跑这些规则全部通过才判定成功。file_exists 检查结果文件确实生成db_count_increased 去验证对应表里的记录数量确实增加了。这套设计背后的逻辑是成功必须建立在物理证据上而不是执行者的口头描述。把 proof 想成验收单施工队不能只跟你说“活干完了”还要请你到现场看水龙头拧开有没有水窗户关得上关不上。Agent-Reach 的回执面就是那个去现场检查的人。我在实际跑任务时发现proof 规则写得越具体幻觉影响越小。你要判断一个数据写入任务是否成功与其让 Agent 自己说“成功”不如让它提供一个文件路径或者数据库查询结果由回执面去做客观校验。这就把“模型自信”降级成了“工程可以证明的东西”。3.4 状态机、超时与重试把不可靠变成可管理状态机的状态集合并不复杂但每个状态都对应一套处理规则。我常用的状态如下状态含义处理方式pending任务已入队等待路由routing正在匹配目标 Agent路由规则必须命中否则转 humanrunningAgent 执行中等待 Agent 提交回执awaiting_receipt已提交待校验回执面校验 proofsucceeded触达成功任务结束failed重试次数用尽告警通知needs_human需人工接管挂起等待操作超时参数我一般分成三档连接超时 3 秒执行超时按任务类型设 30 秒到 5 分钟回执等待超时默认 10 秒。重试采用指数退避初始等待 2 秒每次翻倍最多重试 5 次。公式就是wait 2 * 2^attempt。重试有一个经验必须强调写操作的重试必须带幂等键。退款这种任务如果重试两次等于可能退两次款。幂等键推荐直接用 task_token 加动作名做组合第三方接口支持幂等就传幂等键不支持就自己在本地记录“这个任务我已经发出过请求”的状态前端再遇到重复请求直接复用上一次的回执。4. 踩坑实录Agent 协同里那些翻过车的真实问题4.1 模型幻觉把“没调用”包装成“调用成功”这个问题出现的频率比我预想的高得多。有一次客服 Agent 返回了一个非常标准的成功文案我下意识觉得没问题但侧边栏的 trace 面板里跳出一个红色提示refund_agent 没有同步 receipt 记录。打开回执面日志一看proof 字段为空数据库表数量也没有变化再翻工具调用时间线才发现模型那一次根本没有发起退款工具调用它只是根据 prompt 里的语义在回答文本里“假装”自己已经执行了。事后我把根因总结为在普通对话场景里模型只需要生成文字在工具调用场景里模型要同时管理“回复内容”和“动作执行”一旦它更倾向于让回复显得合理就会把虚构动作混进结果。Agent-Reach 的应对策略很强硬回执面没有校验通过之前状态机不允许进入 succeeded发现回执缺失时直接触发生成一条告警让任务进入重试或人工队列。这条规则治标又治本从机制上堵住了“文本即成功”的老毛病。4.2 Agent 互踢皮球跑出无限循环还有一个很有 Agent 特色的故障两个 Agent 互相推诿。我的某个流程里order_agent 发现用户需要退款把任务转给 refund_agentrefund_agent 看了一眼又说订单信息不完整把任务退回给 order_agentorder_agent 又认为信息完整再次转过去。如果没有上限这个循环会永无止境地跑下去每条日志还在不断新增像极了两个同事在工单系统里互相踢皮球谁都不愿意接单。我定位这个问题时发现 trace_id 下面的 hops 数组长得离谱50 多条记录全是同一个(order_agent, refund_agent)来回横跳。加两个机制后问题立刻可控第一每个任务设置 max_hops默认 5超过直接转人工第二做父子链路循环检测在同一 trace 中如果某个(from, to, action)组合出现两次就判定为循环并挂起。其实这类问题更像流程设计缺陷不是模型问题但因为 LLM 让交互变得太自由缺陷被掩盖到最后爆出来所以检测机制必须前置。4.3 下游一慢整条链路跟着超时雪崩依赖第三方服务的 Agent 链路最大的风险就是超时传递。有一回我接了一个物流查询服务对方在高峰期偶发 5 秒以上的延迟而我的 Agent 执行超时设的是 30 秒按理说能扛住但很多个任务同时卡在同一个外部 API 调用上线程池被打满后面所有任务都开始排队队列一满连健康检查也超时了。表面上看起来是“所有 Agent 都变慢了”实际只是下游那么一个节点的锅。这次的教训让我把超时体系改成分层管理控制面与执行面的超时永远比外部 API 调用超时大一级避免内部先于外部开始重试外部 API 调用超过 4 秒直接标记失败不无限等待连续失败超过阈值触发熔断直接走降级路径比如先转人工处理而不是让任务继续堆积。这套组合下来代码改动不算大但系统稳定性提升非常明显。4.4 故障快速排查速查表把这些经验整理成一张速查表方便出现问题时先稳定军心再动手。故障现象可能原因优先检查点任务一直 pending路由规则未命中路由 condition 与 Agent capabilities 是否匹配任务卡在 awaiting_receiptAgent 没提交回执或下游慢Agent 日志、回执面接收队列、外部 API 耗时状态已 succeeded 但业务无变化回执校验规则太弱proof 里有没有物理校验hops 数量暴涨路由循环或 Agent 互相转手trace 中 (from, to, action) 重复次数偶发大量 failed超时设置不合理分层超时、幂等键、外部 API 状态排查的时候我习惯先看状态机分布再按 task_token 翻 trace最后才去看 Agent 原始输出。顺序反过来容易被人海战术拖死因为你会在几十份“看起来都对”的模型回答里迷失方向。5. 现在的用法与重做思路这套框架留下的三个教训5.1 从写死路由到能力发现Agent-Reach 第一版的路由规则全是静态配置写死“遇到 refund 就去 refund_agent”好处是行为可预期坏处是每加一个新 Agent 都要改配置文件。后来我做了最小化的能力发现机制每个 Agent 启动时向控制面注册 Manifest控制面维护一张可用能力表路由判断时不再直接指定节点名而是指定能力名由调度器从能力表里挑一个当前可用的 Agent。实现上其实就是把配置里的target: refund_agent改成capability: refund_order控制面会在匹配到能力后选择该能力对应的实例列表中的第一个健康实例。好处很快体现出来新增退款 Agent 的 v2 实例时不用动任何路由配置只要注册完 Manifest 并把健康检查跑通调度器会自动把任务分过去。这就是一个小小的“动态可发现”能力但它让链路从一个静态图变成了活系统。5.2 重做时首先改掉的三件事如果重新写一遍有三件事我一定会改。第一回执结构要从第一天就当外部契约来设计。我第一版把 receipt 当成内部 JSON 随便定义字段增删很随意后期要对接多个业务方时才发现版本兼容问题特别头痛。契约用版本号字段从第一天就管起来后续才不会乱。第二所有 Agent 必须接入统一 SDK。我最早图省事让每个 Agent 自己实现 HTTP 回调结果每个 Agent 的回调超时、签名、字段命名全都不一样排查成本都花在“翻译各家的回执格式”上了。统一 SDK 之后回执面只要解析一种格式问题数量少了一大半。第三日志要从第一行就结构化。最初我是打印纯文本日志出问题靠人肉 grep后来 trace 数据量上来纯文本根本没法收敛。改成 JSON 结构化日志后把 task_token、trace_id、node、status 作为预置字段直接在日志平台里按 task_token 搜索定位速度从小时级降到分钟级。这三件事都不是炫技就是我在 Agent-Reach 上踩出来最实在的三个教训。踩过这么多坑之后我自己最大的体会是Agent 系统的工程难点从来不在单个模型的能力而在机制设计。你不需要每个 Agent 都用最贵最强的模型但你一定需要一套机制让每个 Agent 都不能只靠“嘴说”来证明自己完成了任务。甚至可以说判断一个人会不会做 Agent不看 prompt 写得有多花哨而看他愿不愿意为“一个可能撒谎的执行者”准备完整的约束和证据链。Agent-Reach 这个名字能被留下来对我来说更像一句提醒当我们讨论 Agent 的时候永远要追问一句——它真的够到目标了吗如果答案不是有据可查那它就还只是一个演示。