做多智能体Agent项目的人迟早会遇到同一个尴尬场景明明大模型能力很强、工具也接了不少Agent 却在一个看起来并不复杂的子任务上“够不到”结果。要么是工具根本没有注册到对应的 Agent 上要么是任务被分发给了不具备相关能力的 Agent要么是模型压根没意识到自己该调用哪个工具。我在把多智能体系统从原型推到可落地状态的过程中把这类问题统一归结为“Agent 可达性”问题这也是 Agent-Reach 这个项目的出发点。Agent-Reach 不是一个“大而全”的低代码平台而是一套面向智能体调度的轻量路由方案。用三句话就能说清给每个 Agent 建立标准能力档案把任务意图向量化后与能力档案做语义匹配用可达性评分决定“谁来干、干不干得了”。它解决的是能力可达、任务可达、结果可达这三个层面的问题。如果你正在折腾多 Agent 编排、工具调用或者被“任务没人接”折腾得头疼这篇经验总结应该能给你一个比较完整的参考。1. 为什么做 Agent 能力可达性这件事1.1 核心问题任务经常“没人接”或者“接错人”我的出发点是一个订单分析多 Agent 项目。背景是有数据查询 Agent、客服话术 Agent、报表生成 Agent再加上一个总控 LLM。看起来分工明确实际跑起来经常乱套。用户问“对比一下华东区华南区的退货率”系统把任务分给了客服话术 Agent它没有 SQL 权限答非所问分给数据 Agent 时又因为任务描述里没有明确“退货率”能对上哪张表它生成了一个看似合理但根本没查库的答案。这类问题表面上是 Prompt 写得不够好但根子是缺一个“能力匹配层”。复盘之后我总结出三个典型痛点Agent 能力边界不清晰。很多团队习惯用一句话“简介”描述一个 Agent比如“这是一个数据分析助手”。这种描述对 Embedding 模型来说太模糊相似度评分没有区分度。任务分发靠硬编码。入口写死 if-else 或关键词匹配“退货”就调客服 Agent“报表”就调报表 Agent。用户换一种说法就露馅。没有结果校验闭环。任务派发出去了但 Agent 到底有没有真正完成任务缺一个可量化的校验手段。Agent-Reach 就是在这些痛点之上做的一层“路由与评估”组件它不替代具体 Agent只在前面把路领对在后面把结果验掉。1.2 现有框架为什么“够不到”任务主流的几套多 Agent 编排框架比如 LangGraph、AutoGen、CrewAI 这类大多提供了“任务-智能体”的绑定能力但绑定的粒度是静态的。配置里写死了“这个 Agent 负责哪些工具”运行时最多做一个基于角色的硬匹配。这种架构有个隐蔽问题当 Agent 数量变多、工具类型变杂时任务预期结果和 Agent 能力描述之间容易产生语义断层。举例一个“天气查询 Agent”里注册了城市天气 API 和穿衣建议工具用户任务“明天去杭州出差需要准备什么衣服”很多框架会分类成“穿衣建议”派给这个 Agent这个分配没错。但如果用户换一种说法——“我看了一下杭州未来三天都是雨帮我写一段降水对骑行路线的影响分析”这同时涉及天气、路线知识、文本生成三类能力硬匹配框架通常抽到关键词“天气”就分给同一个 Agent而真正能算路线、分析路况的 Agent 在旁边闲着。这种“够不到”的根因是缺少一个在运行时把任务重新切成原子子任务、并对每个子任务做能力匹配的环节。Agent-Reach 做的事就是把依赖模型强推理、强记忆的事拆成“注册-匹配-路由-校验”四个固定动作让复杂任务变成一组可追踪的小路由。2. 整体设计与架构拆解2.1 四层结构接入、路由、执行、观测Agent-Reach 整体架构分成四层接入层接收用户文本输入统一转成结构化任务对象包含任务 ID、原始文本、目标实体、限制条件超时时间、预算等。路由层核心层包含任务意图识别、能力向量化、相似度打分、路由决策四步。执行层调用具体 AgentAgent 内部再调用工具链把执行结果封装成统一 Result。观测层记录每个任务的流入时间、路由结果、执行耗时、成功率用于复盘和阈值调优。四层之间通信全部走标准 JSON 结构。任意 Agent 只要实现统一接口就能插拔接入不用关心路由层怎么算分。我最初也考虑过把路由逻辑直接塞进总控 LLM 的 System Prompt 里后来放弃了因为可观测性太差任务为什么分给特定 Agent、为什么拒绝执行模型不会给出一份结构化的解释。而分层之后每一跳的决策依据都能落成日志出了问题直接翻记录省去很多互相扯皮的时间。2.2 能力档案先给每个 Agent 上户口每个 Agent 上线前必须完成一份能力档案。字段不多但每个都有讲究字段作用示例id全局唯一标识agent_data_queryname展示名数据查询 Agentdescription一句话白描负责读取数据库、执行 SQL、返回表格化结果capabilities能力项列表每个能力项含 name、description、tool_idstools可用工具 ID 列表sql_executor, schema_inspectorconstraints执行约束只读模式、超时 60 秒、不支持写操作其中最重要的是 capabilities 里的能力描述。不要写“擅长数据处理”这种空话而要写“能把自然语言问句转换成 SQL 并执行返回符合查询条件的记录列表支持 JOIN、分组、排序”。为什么因为后面做语义匹配时主模型判断“这个任务是不是这个 Agent 的菜”主要依据就是这段能力描述。描述越贴近任务的动词和宾语匹配率越高。实际维护中能力描述应该由“人 Agent 本身”共同迭代。初始版本让产品工程师写跑两周后看路由日志把经常被误路由的任务样本整理成表格喂回给开发同学反过来再细化能力描述。这个过程不是一次性的而是一个持续的数据飞轮路由日志越积累能力描述就越精准。2.3 四步路由法意图识别、向量检索、评分、决策路由层内部我拆成四步叫“四步路由法”意图识别用 LLM 把用户文本拆成“目标动词 目标对象 约束条件”。比如“对比一下华东区华南区的退货率”得到动词“对比”对象“退货率”维度“华东区/华南区”。这一步的输出是 JSON不要直接拿原文去跟能力文档匹配。向量检索把上一步的结构化结果压回自然语言描述用模板生成一段“标准任务表述”Embedding 后用余弦相似度召回到 TopN。可达性评分对 TopN 候选结合相似度、历史成功率、当前负载算加权得分。路由决策只有得分超过阈值才派发低于阈值就进入“澄清或升级”流程让总控 LLM 重新追问或者交给人工处理。这个流程最大的好处是每个环节都有记录。一次任务最终失败时翻日志能清楚看到意图识别成 A、候选相似度 [0.82, 0.71, 0.65]、实际派发给 Agent B、B 执行过程中调工具失败。这种透明性在处理复杂跨 Agent 任务时特别有用不需要靠猜。3. 核心模块实现细节3.1 能力注册表给 Agent 上户口注册表我用的是简单的字典存储加正则校验生产环境可以平移到 Redis 或 Postgres核心逻辑不变。关键点是Agent 上线时除了写档案还要声明自己的工具清单工具清单和能力描述必须对得上否则会出现“描述里说能查 SQL但工具列表里没有 SQL 执行器”的尴尬。下面是我原型里的一段注册代码Python# agent_registry.py from typing import Dict, List from dataclasses import dataclass, field import uuid dataclass class Capability: name: str description: str tool_ids: List[str] dataclass class AgentProfile: id: str name: str description: str capabilities: List[Capability] field(default_factorylist) constraints: Dict[str, str] field(default_factorydict) def add_capability(self, name: str, description: str, tool_ids: List[str]): self.capabilities.append(Capability(name, description, tool_ids)) class AgentRegistry: def __init__(self): self._profiles: Dict[str, AgentProfile] {} def register(self, profile: AgentProfile): if profile.id in self._profiles: raise ValueError(fagent {profile.id} 已存在) self._profiles[profile.id] profile def get(self, agent_id: str) - AgentProfile | None: return self._profiles.get(agent_id) def list_all(self) - List[AgentProfile]: return list(self._profiles.values())原型阶段不必上向量数据库直接在内存里遍历所有 capability.description 做余弦相似度就行。等 Agent 数量超过几十个、每次路由都要全量扫描时再引入向量索引这一步我放在第 4 章的简易版路由里一起演示。3.2 可达性评分距离怎么算路由的核心是“距离”。Agent-Reach 里的距离不是简单文本相似度而是三者的加权语义相似度0.6任务的标准表述与能力描述的余弦相似度。历史成功偏好0.25这个 Agent 历史上承接类似任务的完成率。完成率低的扣分。负载因子0.15实时任务队列长度除以并发上限负载高的 Agent 会被降权。最终得分公式score 0.6 * sim 0.25 * success_rate 0.15 * (1 - load_ratio)。举个例子。Agent A语义相似度 0.9历史成功率 0.7负载 0.3Agent B语义相似度 0.8历史成功率 0.9负载 0.9。算出来A 0.6×0.9 0.25×0.7 0.15×0.7 0.54 0.175 0.105 0.82B 0.6×0.8 0.25×0.9 0.15×0.1 0.48 0.225 0.015 0.72A 胜出。如果只看相似度B 的 0.8 也不低很可能被人为选中结果 B 已经满负载任务排队半天。这个公式的意思其实是不是找一个“最懂”的 Agent而是找一个“既有把握又快”的 Agent。阈值我一般设在 0.65。低于这个值宁可让总控 LLM 多追问一轮也不要瞎派。实践证明瞎派一次引发的返工成本远高于多问一个问题。3.3 任务分发单路由与多跳路由单任务场景相对简单直接按最高分派发执行完后校验结果。真正复杂的是多跳场景比如“统计上季度退货率最高的三个品类并给每个品类生成一份替换建议”。这个任务至少需要数据查询 Agent、品类分析 Agent、文案生成 Agent 三个角色接力。Agent-Reach 对这类任务的做法是先把任务画成一张简单 DAG。节点是原子子任务边是依赖关系。路由层逐个节点做匹配一个节点只能派给一个 Agent但不同节点可以派给同一个 Agent只要它在时间上串行执行即可。这里要特别小心循环。我踩过一个坑一个流程里让 A 节点派给 Agent XB 节点又派给 Agent Y而 Y 的内部把整个任务重新提交回入口结果形成无限循环直到超时。后来我在任务对象里加了 visited 标记和最大跳数限制路由层遇到重复任务 ID 直接拒绝。细节我会在第 5 章排查部分展开。3.4 结果校验别让 Agent “嘴上说完成”这是我最想强调的部分。多 Agent 系统里最隐蔽的虚假繁荣是任务显示成功但其实是模型直接根据上下文编了一个答案根本没调用工具。要防这个我在 Result 结构里加了一个 evidence 字段{ task_id: task_001, agent_id: agent_data_query, status: succeeded, output: ..., tool_calls: [ { tool_id: sql_executor, input: SELECT ..., output_rows: 12, duration_ms: 340 } ], evidence: SQL 查询返回 12 行记录字段包括 category, return_rate }校验规则很简单凡是声明需要工具能力的子任务执行结果里必须包含 tool_calls且至少有一个 tool_calls 的状态是 success否则就算失败。这一条规则挡掉了至少三成“假成功”。我在生产环境里见过太多“答案看起来对但数据源根本没查”的案例。加了这条硬校验之后Agent 为了通过检查必须真正走工具链路模型自己“脑补”答案的空间被压缩了很多。3.5 观测面板与复盘让系统越来越准Route 决策日志是 Agent-Reach 的另一个资产。我每天会生成一个简单面板任务总量、首跳准确率、端到端成功率、平均路由耗时、各 Agent 负载分布。其中“首跳准确率”是最核心的指标——第一次把任务派对了整条链路大概率就顺了如果首跳经常出错后面再补偿也难看。复盘时我会把“首跳错误样本”拉出来做归类常见三种原因意图识别错了、能力描述太宽泛、工具声明不对。每类原因对应不同的修复动作。这个环节不能省因为这类系统的本质是数据飞轮路由错误越少成功数据越多历史成功偏好权重就越有参考价值。4. 实操跑通一个简单原型4.1 最小原型场景与环境准备为了把上面的设计落地我搭了一个最小可运行版本。场景是三个 Agent计算 Agent能做四则运算、税费计算工具是 calculator。天气 Agent查城市实时天气工具是 weather_api。文档 Agent做文本摘要、格式转换工具是 text_processor。用户输入一段自然语言比如“帮我计算 1220 元的含税价税率 13%”系统要把它路由到计算 Agent 而不是天气 Agent。环境只需要三样Python 3.10一个本地 Embedding 模型我用了 sentence-transformers 里的 all-MiniLM-L6-v2跑起来不需要额外调用付费接口一个 LLM 接口用于意图识别原型阶段甚至可以用正则加关键词兜底。整体代码量控制在三百行以内。4.2 核心路由代码以下是简化后的路由核心# router.py from sentence_transformers import SentenceTransformer import numpy as np model SentenceTransformer(all-MiniLM-L6-v2) def build_capability_index(registry): cap_texts [] cap_agents [] for agent in registry.list_all(): for cap in agent.capabilities: cap_texts.append(f{agent.name}: {cap.description}) cap_agents.append((agent.id, cap.name)) return model.encode(cap_texts), cap_agents def route(task_text, vectors, cap_agents, registry): task_vec model.encode([task_text])[0] scores [] for i, vec in enumerate(vectors): cos_sim float(np.dot(task_vec, vec) / (np.linalg.norm(task_vec) * np.linalg.norm(vec))) agent_id, cap_name cap_agents[i] profile registry.get(agent_id) # stats 是模拟的历史统计模块生产环境换成真实采集即可 success_rate stats.get_success_rate(agent_id, cap_name, default0.7) load stats.get_load(agent_id, default0.2) weighted 0.6 * cos_sim 0.25 * success_rate 0.15 * (1 - load) scores.append((agent_id, cap_name, cos_sim, weighted)) scores.sort(keylambda x: x[3], reverseTrue) return scores[:3] def decide(task_text, top_scores, threshold0.65): best top_scores[0] if best[3] threshold: return None, no_confident_agent return best[0], best[3]注意一个小细节capability_index 的每一行是“Agent 名 能力描述”而不是只存能力描述。为什么因为用户任务文本里经常会带 Agent 的功能叫法比如“让天气助手看看上海会不会下雨”。带上名字之后语义匹配能同时命中名称和职责召回明显更稳。低于阈值的任务我建议返回“需要澄清”而不是强派。原型里可以直接让用户重新说一遍下一版再接 LLM 追问。这个兜底逻辑虽然简单但对整体体验的提升非常明显。4.3 跑通后的效果与调试技巧我拿十组测试任务跑了一遍简单任务的正确路由率做到了 100%复杂意图比如“杭州下雨适合穿什么”这种跨天气与建议的任务首跳准确率 80% 左右剩下两成会落到天气 Agent因为它没有穿衣建议工具结果校验会把这部分标成失败。这其实验证了前面说的能力描述和工具清单必须严格对齐。调试技巧方面有几个点值得单独拎出来先打印余弦相似度直方图。如果大部分候选的得分集中在 0.5 附近说明 Embedding 模型区分度不够或者能力描述写得太像了。我之前三个 Agent 的能力描述都写“处理用户请求”结果相似度全在 0.6 上下怎么调阈值都没用。把描述改细之后分布才拉开。用“负样本”迭代能力描述。每一条能力描述除了正向例子我还配了三条“绝不负责”的例子比如“不负责数据库写入、不负责图片生成”。匹配阶段不一定直接用但调试时能提供很好的参照。加一个“兜底 Agent”。我在生产里总会留一个编排 Agent 专门接手低置信度的任务。它不依赖工具只做拆解和转述至少保证用户不死等。5. 常见问题与排查技巧实录5.1 任务经常路由到错误的 Agent排查顺序我建议这样先看意图识别结果再看候选相似度 Top3最后核对“目标 Agent 的工具清单是否真的具备完成这个任务的能力”。我遇到过一个典型案例用户说“把上周的销售 Excel 转成 PDF 发给我”意图识别成了“文件转换”路由给了格式处理 Agent但它只有文本处理工具没有 Excel 解析和 PDF 生成能力。这就是工具声明和描述没对齐。修正方式是在 AgentProfile 里增加 required_tools 校验注册阶段就用正则检查描述中提到的动词解析、生成、转换是否都有对应工具。还有一个高频原因是 Embedding 模型太小。我对比过更强的向量模型相似度分布明显更合理但成本也上来了。小项目先用本地小模型完全可以只要在迭代期多跑样本验证别一上来就追求大模型否则资源消耗会很吓人。5.2 Agent 执行超时怎么解多 Agent 系统里超时是最让人头疼的。我把超时分成两类路由层超时和执行层超时。路由层超时一般是大模型意图识别太慢。我把 LLM 单次调用限制在 2 秒以内超时降级到正则兜底。执行层超时通常是工具本身慢比如 SQL 跑了 30 秒。我给每个 Agent 配置独立的超时时间在 Result 里记录 duration_ms然后设置一个慢任务队列超过阈值的任务不进主流程走异步补偿。5.3 多跳任务死循环与重复执行前面提到的 visited 标记我再补一下原理。任务对象带一个 history 字段记录经过的所有 Agent ID。路由层在分发前检查目标 Agent 是否已在 history 里如果在说明要么这个 Agent 被重复选中要么 DAG 存在环直接中断并报“route loop”。最大跳数我默认设为 5超过就进入人工处理。另一个看着像死循环、但其实是“重复执行”的问题一个 Agent 内部重试工具调用时把同一个任务提交了两次结果下游收到两个相同请求产生两份结果。解决方式是在任务对象里加 request_id 作为幂等键执行层落库时如果发现 request_id 已存在就直接返回缓存结果。这个坑我踩过消费型工具的重复执行后果挺严重的尤其是涉及积分扣减、消息发送这类操作时。5.4 评估指标为什么失真只看端到端成功率会被“假成功”骗到只看路由准确率又会漏掉执行质量。我的建议是把三个指标一起看指标定义阈值建议首跳准确率第一跳路由命中正确 Agent 的比例 85%执行成功率Agent 报告成功且通过结果校验的比例 90%端到端准确率用户对最终结果的抽查正确比例 80%这三个指标是互相约束的。如果首跳很低但端到端还很高说明有补偿机制在干活这时候要看补偿路径有没有被滥用。如果执行成功率很高但端到端很低多半是结果校验规则太松出现了“说完成但没完成”的假成功。我每次调整能力描述或权重都会用同一批黄金测试集跑回归保证改一处不会影响其他路由。没有回归测试的路由系统改配置就像拆弹指不定哪天哪一跳就炸了。从项目原型到现在Agent-Reach 总共迭代了三个版本。第一个版本只做关键词硬匹配效果很糟第二个版本加了向量召回路由准了但结果校验缺失第三个版本补上权重公式、结果校验和观测面板才算真正跑通。我个人最大的体会是Agent 编排里最难的不是让模型干活而是让系统知道“谁该干活、干到什么程度算干完了”。如果你也在做类似的多智能体系统建议不要急着堆 Agent 数量先拿一个很小但真实的业务场景把“注册-匹配-路由-校验”这个闭环跑通。等闭环验证了再往里面加 Agent会轻松很多。