Routing

说明： 原先的 Spring Boot 示例模块 agentscope-examples/multiagent-patterns/ 已在 2.0 包重构中移除。请以本文中的代码片段作为参考实现。其他可运行示例见 agentscope-examples/documentation/。

​

概述

• 分类步骤：路由器（如 LLM 或规则分类器）决定调用哪些专家以及向每个专家发送什么子查询。
• 专家智能体：每个垂直领域有独立智能体（如 GitHub 专家、Notion 专家、Slack 专家），以 AgentScopeAgent 与 AgentScope 工具实现。
• 合成：将专家返回的原始结果合并为一个连贯答案（例如通过一次最终 LLM 调用）。

​

架构

查询 → Router（分类）→ [智能体 A] → 合成 → 组合答案
                ↘ [智能体 B] ↗
                ↘ [智能体 C] ↗

​

Simple 与 Graph 对比

​

实现（Simple 变体）

​

设计要点

• 单一调用完成路由：业务只调 RouterService.run(query)；内部用 AgentScopeRoutingAgent 一次 invoke(query) 完成分类、并行专家、框架内 merge。
• 合成可选：若路由框架已写入 RoutingMergeNode.DEFAULT_MERGED_OUTPUT_KEY，则直接用作最终答案；否则由 RouterService 用同一 Model 再跑一次 LLM，将各专家结果合成为一条回复。

​

代码结构（包 io.agentscope.examples.routing.simple）

​

Bean 与约定

1. Model：一个 Model Bean（如 DashScopeChatModel），供路由与所有专家共用。
2. 专家 AgentScopeAgent：每个领域一个，例如：
   • name / description：供路由分类时识别；
   • instruction：模板中含占位符 {agentName_input}（如 {github_input}），由路由节点在运行时填入子查询；
   • outputKey：该专家结果写入状态的键，如 github_key、notion_key、slack_key；
   • Toolkit：注册该领域的桩工具（如 GitHubStubTools 的 search_code、search_issues）。
3. AgentScopeRoutingAgent：AgentScopeRoutingAgent.builder().model(...).subAgents(List.of(githubAgent, notionAgent, slackAgent)).build()；内部实现分类 + 并行调用专家 + 将结果写入各 outputKey 及 merge 键。
4. RouterService：持有 Model 与 AgentScopeRoutingAgent；run(query) 后若需要合成，则用 Model 将各专家结果格式化为一段 prompt 再调用一次 chat，得到 finalAnswer。

​

RouterService.run 逻辑（简要）

1. routerAgent.invoke(query) → 得到 OverAllState。
2. 遍历 github_key、notion_key、slack_key：若 state 中有该 key，则从 state 取 agentName_input 与专家输出，构造 Classification 与 AgentOutput 列表。
3. 若 state 中存在 RoutingMergeNode.DEFAULT_MERGED_OUTPUT_KEY，则将其内容作为 finalAnswer；否则调用 synthesize(query, results)（同一 Model，系统提示为“合并多源结果回答原问题”），返回值作为 finalAnswer。
4. 返回 RouterResult(query, classifications, results, finalAnswer)。

​

实现（Graph 变体）

​

设计要点

• 路由作为子图嵌入：整体是 StateGraph，其中「路由」不是单个 Bean 调用，而是 AgentScopeRoutingAgent.getAndCompileGraph() 返回的已编译子图作为一节节点；子图内部仍是分类 → 并行专家 → merge。
• 显式预处理与后处理：在路由节点前后增加 PreprocessNode 与 PostprocessNode，用于校验、规范化、埋点、格式化等，状态在整图上流转，便于扩展和观测。

​

代码结构（包 io.agentscope.examples.routing.graph）

​

图与状态键

• StateGraph：new StateGraph("routing_graph", keyFactory)，边为 START → preprocess → routing → postprocess → END。
• keyFactory：为 input、query、messages、preprocess_metadata、merged_result、final_answer、postprocess_metadata 以及 github_key、notion_key、slack_key 等配置策略（多为 ReplaceStrategy，messages 为 AppendStrategy(false)）。
• preprocess 节点：node_async(new PreprocessNode())，纯函数节点，无 LLM；输出供 routing 子图消费。
• routing 节点：routerAgent.getAndCompileGraph()，即把「分类 + 并行专家 + merge」整段逻辑作为子图挂到主图的一节，子图输出写入 merged_result（及各 xxx_key）。
• postprocess 节点：node_async(new PostprocessNode())，读取 merge 结果与预处理元数据，写出 final_answer 与 postprocess_metadata。

​

PreprocessNode / PostprocessNode 与 Simple 的区别

• Simple：无独立预处理；若需要“再合成”，仅在 RouterService 内用 Model 做一次调用，无统一的状态键或 trace 元数据。
• Graph：预处理集中做校验与规范化，并写入 preprocess_metadata（如 traceId）；后处理集中做最终格式与日志，并写入 postprocess_metadata；整条链路状态一致，便于扩展（如加条件分支、额外节点）。

​

示例项目

• Simple：入口为 RouterService.run(query)；流程为分类 → 并行专家 →（框架 merge）→ 可选 RouterService 合成。设置 routing.runner.enabled=true 可在启动时运行 Simple 演示（见 RoutingRunner）。
• Graph：入口为 RoutingGraphService.run(query)；流程为预处理 → 路由子图 → 后处理。设置 routing-graph.runner.enabled=true 可在启动时运行 Graph 演示（见 RoutingGraphRunner）。

​

相关文档

• Pipeline - 顺序与并行智能体组合
• MsgHub - 多智能体消息广播
• Agent as Tool - 将智能体注册为工具