多智能体Agent可达性路由方案：从能力匹配到结果校验实战解析

做多智能体（Agent）项目的人，迟早会遇到同一个尴尬场景：明明大模型能力很强、工具也接了不少，Agent 却在一个看起来并不复杂的子任务上“够不到”结果。要么是工具根本没有注册到对应的 Agent 上，要么是任务被分发给了不具备相关能力的 Agent，要么是模型压根没意识到自己该调用哪个工具。我在把多智能体系统从原型推到可落地状态的过程中，把这类问题统一归结为“Agent 可达性”问题，这也是 Agent-Reach 这个项目的出发点。

Agent-Reach 不是一个“大而全”的低代码平台，而是一套面向智能体调度的轻量路由方案。用三句话就能说清：给每个 Agent 建立标准能力档案，把任务意图向量化后与能力档案做语义匹配，用可达性评分决定“谁来干、干不干得了”。它解决的是能力可达、任务可达、结果可达这三个层面的问题。如果你正在折腾多 Agent 编排、工具调用，或者被“任务没人接”折腾得头疼，这篇经验总结应该能给你一个比较完整的参考。

1. 为什么做 Agent 能力可达性这件事

1.1 核心问题：任务经常“没人接”或者“接错人”

我的出发点是一个订单分析多 Agent 项目。背景是：有数据查询 Agent、客服话术 Agent、报表生成 Agent，再加上一个总控 LLM。看起来分工明确，实际跑起来经常乱套。用户问“对比一下华东区华南区的退货率”，系统把任务分给了客服话术 Agent，它没有 SQL 权限，答非所问；分给数据 Agent 时，又因为任务描述里没有明确“退货率”能对上哪张表，它生成了一个看似合理但根本没查库的答案。

这类问题表面上是 Prompt 写得不够好，但根子是缺一个“能力匹配层”。复盘之后我总结出三个典型痛点：

1. Agent 能力边界不清晰。很多团队习惯用一句话“简介”描述一个 Agent，比如“这是一个数据分析助手”。这种描述对 Embedding 模型来说太模糊，相似度评分没有区分度。
2. 任务分发靠硬编码。入口写死 if-else 或关键词匹配，“退货”就调客服 Agent，“报表”就调报表 Agent。用户换一种说法就露馅。
3. 没有结果校验闭环。任务派发出去了，但 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、原始文本、目标实体、限制条件（超时时间、预算等）。
• 路由层：核心层，包含任务意图识别、能力向量化、相似度打分、路由决策四步。
• 执行层：调用具体 Agent，Agent 内部再调用工具链，把执行结果封装成统一 Result。
• 观测层：记录每个任务的流入时间、路由结果、执行耗时、成功率，用于复盘和阈值调优。

四层之间通信全部走标准 JSON 结构。任意 Agent 只要实现统一接口，就能插拔接入，不用关心路由层怎么算分。我最初也考虑过把路由逻辑直接塞进总控 LLM 的 System Prompt 里，后来放弃了，因为可观测性太差：任务为什么分给特定 Agent、为什么拒绝执行，模型不会给出一份结构化的解释。而分层之后，每一跳的决策依据都能落成日志，出了问题直接翻记录，省去很多互相扯皮的时间。

2.2 能力档案：先给每个 Agent 上户口

每个 Agent 上线前必须完成一份能力档案。字段不多，但每个都有讲究：

其中最重要的是 capabilities 里的能力描述。不要写“擅长数据处理”这种空话，而要写“能把自然语言问句转换成 SQL 并执行，返回符合查询条件的记录列表，支持 JOIN、分组、排序”。为什么？因为后面做语义匹配时，主模型判断“这个任务是不是这个 Agent 的菜”，主要依据就是这段能力描述。描述越贴近任务的动词和宾语，匹配率越高。

实际维护中，能力描述应该由“人 + Agent 本身”共同迭代。初始版本让产品工程师写，跑两周后看路由日志，把经常被误路由的任务样本整理成表格，喂回给开发同学，反过来再细化能力描述。这个过程不是一次性的，而是一个持续的数据飞轮：路由日志越积累，能力描述就越精准。

2.3 四步路由法：意图识别、向量检索、评分、决策

路由层内部我拆成四步，叫“四步路由法”：

1. 意图识别：用 LLM 把用户文本拆成“目标动词 + 目标对象 + 约束条件”。比如“对比一下华东区华南区的退货率”，得到动词“对比”，对象“退货率”，维度“华东区/华南区”。这一步的输出是 JSON，不要直接拿原文去跟能力文档匹配。
2. 向量检索：把上一步的结构化结果压回自然语言描述（用模板生成一段“标准任务表述”），Embedding 后用余弦相似度召回到 TopN。
3. 可达性评分：对 TopN 候选，结合相似度、历史成功率、当前负载算加权得分。
4. 路由决策：只有得分超过阈值才派发；低于阈值就进入“澄清或升级”流程，让总控 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_factory=list) constraints: Dict[str, str] = field(default_factory=dict) 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(f"agent {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.3；Agent 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.82
• B = 0.6×0.8 + 0.25×0.9 + 0.15×0.1 = 0.48 + 0.225 + 0.015 = 0.72

A 胜出。如果只看相似度，B 的 0.8 也不低，很可能被人为选中，结果 B 已经满负载，任务排队半天。这个公式的意思其实是：不是找一个“最懂”的 Agent，而是找一个“既有把握又快”的 Agent。

阈值我一般设在 0.65。低于这个值，宁可让总控 LLM 多追问一轮，也不要瞎派。实践证明，瞎派一次引发的返工成本，远高于多问一个问题。

3.3 任务分发：单路由与多跳路由

单任务场景相对简单：直接按最高分派发，执行完后校验结果。真正复杂的是多跳场景，比如“统计上季度退货率最高的三个品类，并给每个品类生成一份替换建议”。这个任务至少需要数据查询 Agent、品类分析 Agent、文案生成 Agent 三个角色接力。

Agent-Reach 对这类任务的做法是先把任务画成一张简单 DAG。节点是原子子任务，边是依赖关系。路由层逐个节点做匹配，一个节点只能派给一个 Agent，但不同节点可以派给同一个 Agent，只要它在时间上串行执行即可。

这里要特别小心循环。我踩过一个坑：一个流程里让 A 节点派给 Agent X，B 节点又派给 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, default=0.7) load = stats.get_load(agent_id, default=0.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(key=lambda x: x[3], reverse=True) return scores[:3] def decide(task_text, top_scores, threshold=0.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，因为它没有穿衣建议工具，结果校验会把这部分标成失败。这其实验证了前面说的：能力描述和工具清单必须严格对齐。

调试技巧方面，有几个点值得单独拎出来：

1. 先打印余弦相似度直方图。如果大部分候选的得分集中在 0.5 附近，说明 Embedding 模型区分度不够，或者能力描述写得太像了。我之前三个 Agent 的能力描述都写“处理用户请求”，结果相似度全在 0.6 上下，怎么调阈值都没用。把描述改细之后，分布才拉开。
2. 用“负样本”迭代能力描述。每一条能力描述，除了正向例子，我还配了三条“绝不负责”的例子，比如“不负责数据库写入、不负责图片生成”。匹配阶段不一定直接用，但调试时能提供很好的参照。
3. 加一个“兜底 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-Reach 总共迭代了三个版本。第一个版本只做关键词硬匹配，效果很糟；第二个版本加了向量召回，路由准了但结果校验缺失；第三个版本补上权重公式、结果校验和观测面板，才算真正跑通。我个人最大的体会是：Agent 编排里最难的不是让模型干活，而是让系统知道“谁该干活、干到什么程度算干完了”。如果你也在做类似的多智能体系统，建议不要急着堆 Agent 数量，先拿一个很小但真实的业务场景，把“注册-匹配-路由-校验”这个闭环跑通。等闭环验证了，再往里面加 Agent，会轻松很多。