1. AgentScope 多智能体协作模式到底解决什么问题如果你正在搜索 AgentScope 多智能体协作模式大概率已经遇到过这样的困境单个大模型智能体在处理复杂任务时要么上下文塞爆要么职责混乱要么一个环节出错整条链路崩掉。AgentScope 是阿里巴巴开源的一套面向智能体编程的框架它把「多个专业智能体分工协作」这件事从概念变成了可落地的工程结构。简单说它让你能像搭积木一样把 SQL 生成、质量评审、路由分发、任务交接这些能力拆成独立智能体再按不同拓扑组合起来。它适合谁适合已经写过单 Agent Demo、但发现单 Agent 撑不住真实业务复杂度的 Java 开发者也适合想系统理解多智能体协作范式、而不是只会调一个 API 的技术负责人。AgentScope 的核心价值在于它提供了 7 种经过工程验证的协作模式Pipeline 流水线、Routing 路由、Handoffs 交接、Supervisor 监督器、Subagent 子智能体、Skills 技能系统、Workflow 工作流。每种模式对应一类典型场景选错了模式后面写再多代码都是白费。我试过把同一个「自然语言转 SQL 并校验」的需求分别用单 Agent 和 Pipeline 模式实现单 Agent 版本在第三轮对话就开始丢失表结构约束而 Pipeline 版本把生成和评分拆成两个智能体后评分智能体可以独立拿到原始请求和生成的 SQL 做交叉验证稳定性提升非常明显。这就是多智能体协作的意义不是让模型更聪明而是让系统结构更可靠。在动手之前你需要先理解一个关键点AgentScope 的协作模式不是互斥的而是可以嵌套的。比如 Supervisor 模式内部可以挂一个 Pipeline 作为子流程Routing 模式的路由目标本身可以是 Handoffs 链。所以学习路径应该是先逐个吃透 7 种模式的最小可运行单元再考虑组合。接下来的内容会从统一接入配置开始逐步给出每种模式的可复制片段和验证方法。2. TaoToken 统一接入一个 Key 打通多模型通道在搭建多智能体系统时最容易被低估的摩擦点其实是模型接入。AgentScope 默认走 DashScope 通道但实际项目里你往往需要对比不同模型在路由分类、SQL 生成、质量评分等环节的表现。如果每个模型都单独申请 Key、单独配环境变量、单独处理 Base URL光是配置管理就会消耗大量精力。TaoToken 在这里的角色是提供一个统一的 API 通道让你用同一套 Key 和 Base URL 访问多个模型AgentScope 侧只需要改 modelName 就能切换。先说清楚接入位置。TaoToken 的 API 端点是https://taotoken.net/api这个地址不加任何查询参数直接作为 OpenAI 兼容协议的 Base URL 使用。你需要在 TaoToken 控制台创建一个 API Key然后把它放进环境变量。注意不要硬编码在代码或 application.yml 里多智能体项目通常会有多个模块共享配置硬编码一旦泄露影响面很大。环境变量设置方式如下Windows PowerShell 和 Linux/macOS 分开写# Linux / macOS export TAOTOKEN_API_KEYsk-你的TaoToken密钥 # Windows PowerShell $env:TAOTOKEN_API_KEY sk-你的TaoToken密钥然后在 AgentScope 的模型构建处把 Base URL 指向 TaoToken 的 API 地址。AgentScope 底层用的是 OpenAI 兼容的 ChatModel 接口所以配置方式和标准 OpenAI SDK 一致。下面是一个最小可运行的模型 Bean 配置放在你的Configuration类里Configuration public class ModelConfig { Bean public Model taoTokenChatModel() { return OpenAIChatModel.builder() .apiKey(System.getenv(TAOTOKEN_API_KEY)) .baseUrl(https://taotoken.net/api) .modelName(qwen-plus) .build(); } }这里有三个参数必须同时正确Base URL 是https://taotoken.net/apiAPI Key 从环境变量读取Model ID 按你实际要用的模型填写。这三个要素缺一个就会在请求时失败后面排障章节会详细对照报错。如果你用的是 Spring AI Alibaba 的 starter配置方式略有不同需要在 application.yml 里指定 base-urlspring: ai: openai: api-key: ${TAOTOKEN_API_KEY} base-url: https://taotoken.net/api chat: options: model: qwen-plus配置完成后建议先不要急着跑多智能体而是用一个最简单的单 Agent 请求验证通道是否打通。验证方法在下一节给出。这里要强调一点TaoToken 是统一接入通道不是替代 AgentScope 的编排能力。AgentScope 负责智能体之间的协作逻辑TaoToken 负责模型请求的通道统一两者是互补关系。你可以在 Pipeline 的 SQL 生成节点用 qwen-plus在评分节点用 qwen-turbo只需要在各自的 AgentScopeAgent 构建时传入不同的 Model Bean 即可。3. 7 种协作模式的可复制配置片段这一节是全文的核心操作部分。我会按模式逐个给出最小可运行的配置片段每个片段都基于上一节的 TaoToken 模型 Bean。你不需要一次全部跑通建议按顺序来每跑通一个再进入下一个。3.1 Pipeline 流水线顺序、并行、循环三种形态Pipeline 是最基础的协作模式适合任务有明确阶段划分的场景。顺序流水线的典型例子是「自然语言 → SQL 生成 → SQL 评分」两个智能体通过 outputKey 和 instruction 占位符传递数据Bean(sequentialSqlAgent) public SequentialAgent sequentialSqlAgent(Model model) { AgentScopeAgent sqlGenerator AgentScopeAgent.fromBuilder( ReActAgent.builder() .name(sql_generator) .model(model) .sysPrompt(你是MySQL专家根据自然语言输出可执行SQL只输出SQL语句。) .memory(new InMemoryMemory())) .name(sql_generator) .instruction({input}) .outputKey(sql) .includeContents(false) .build(); AgentScopeAgent sqlRater AgentScopeAgent.fromBuilder( ReActAgent.builder() .name(sql_rater) .model(model) .sysPrompt(你是SQL质量评审员根据用户请求和生成的SQL输出0到1的评分只输出数字。) .memory(new InMemoryMemory())) .name(sql_rater) .instruction(用户请求{input}生成的SQL{sql}) .outputKey(score) .build(); return SequentialAgent.builder() .name(sequential_sql_agent) .subAgents(List.of(sqlGenerator, sqlRater)) .build(); }并行流水线适合多角度分析后合并的场景比如对同一主题从技术、金融、市场三个维度同时分析。关键参数是 mergeStrategy 和 maxConcurrencyBean(parallelResearchAgent) public ParallelAgent parallelResearchAgent(Model model) { AgentScopeAgent techAgent buildExpert(model, tech_expert, 从技术可行性角度分析, tech_view); AgentScopeAgent financeAgent buildExpert(model, finance_expert, 从财务回报角度分析, finance_view); AgentScopeAgent marketAgent buildExpert(model, market_expert, 从市场竞争角度分析, market_view); return ParallelAgent.builder() .name(parallel_research_agent) .subAgents(List.of(techAgent, financeAgent, marketAgent)) .mergeStrategy(new ParallelAgent.DefaultMergeStrategy()) .mergeOutputKey(research_report) .maxConcurrency(3) .build(); }循环流水线用于迭代优化直到满足条件比如 SQL 评分低于 0.5 就重新生成。这里用 LoopMode.condition 定义停止条件Bean(loopSqlRefinementAgent) public LoopAgent loopSqlRefinementAgent(Model model) { SequentialAgent inner SequentialAgent.builder() .name(sql_agent) .subAgents(List.of(sqlGenerator(model), sqlRater(model))) .build(); return LoopAgent.builder() .name(loop_sql_refinement_agent) .subAgent(inner) .loopStrategy(LoopMode.condition(messages - { String last messages.get(messages.size() - 1).getText(); double score Double.parseDouble(last.trim()); return score 0.5; })) .build(); }3.2 Routing 路由按输入类型分发到专家Routing 模式解决的是「不同问题找不同专家」的问题。核心是 AgentScopeRoutingAgent它先用 LLM 对输入分类再并行调用匹配的专家智能体。每个专家需要注册自己的工具集instruction 里的占位符格式是{agentName_input}Bean public AgentScopeRoutingAgent routerAgent(Model model, AgentScopeAgent githubAgent, AgentScopeAgent notionAgent, AgentScopeAgent slackAgent) { return AgentScopeRoutingAgent.builder() .name(router) .model(model) .description(根据查询内容路由到GitHub、Notion或Slack专家) .subAgents(List.of(githubAgent, notionAgent, slackAgent)) .build(); }专家智能体的构建要点是工具注册和 outputKey 命名。以 GitHub 专家为例Bean public AgentScopeAgent githubAgent(Model model, GitHubStubTools tools) { Toolkit toolkit new Toolkit(); toolkit.registerTool(tools); return AgentScopeAgent.fromBuilder( ReActAgent.builder() .name(github) .sysPrompt(你是GitHub专家擅长搜索代码和PR。) .model(model) .toolkit(toolkit) .memory(new InMemoryMemory())) .name(github) .instruction(请处理请求{github_input}) .outputKey(github_key) .build(); }3.3 Handoffs 交接与 Supervisor 监督器Handoffs 模式让智能体之间通过工具调用相互转交任务适合销售转客服、多部门协作这类流程。核心实现是定义一个交接工具智能体在判断需要转交时调用它。Supervisor 模式则是主从架构一个监督器智能体负责任务分配和结果整合子智能体各自独立执行。这两种模式的配置片段较长建议先跑通 Pipeline 和 Routing 后再进入。3.4 Subagent、Skills 与 WorkflowSubagent 模式通过 delegate_task 这类任务工具动态委派子智能体适合技术尽调这种需要实时决定处理方案的场景。Skills 模式实现按需加载技能智能体初始只加载基础能力需要时再动态加载专业技能适合大型知识库管理。Workflow 模式用 StateGraph 自定义图编排支持条件分支、并行执行和循环处理是最灵活的编排方式StateGraph graph new StateGraph(workflow_graph, () - { MapString, KeyStrategy strategies new HashMap(); strategies.put(messages, new AppendStrategy(false)); strategies.put(input, new ReplaceStrategy()); return strategies; }); graph.addNode(preprocess, node_async(new PreprocessNode())); graph.addNode(generate, sqlGenerator.asNode()); graph.addNode(rate, sqlRater.asNode()); graph.addEdge(START, preprocess); graph.addEdge(preprocess, generate); graph.addEdge(generate, rate); graph.addEdge(rate, END); CompiledGraph compiled graph.compile();4. 本地运行验证与成功结果确认配置写完后最关键的一步是验证。很多人卡在这里不是因为代码错而是因为不知道「什么样算成功」。这一节给出从单 Agent 到多智能体的递进验证方法。第一步先验证 TaoToken 通道本身是否通。写一个最小的单 Agent 请求不要涉及任何协作逻辑Model model taoTokenChatModel(); ReActAgent agent ReActAgent.builder() .name(ping_agent) .model(model) .sysPrompt(你是一个测试助手收到消息后回复pong。) .memory(new InMemoryMemory()) .build(); Msg reply agent.reply(Msg.builder().textContent(ping).build()); System.out.println(reply.getText());如果这一步输出包含 pong 或类似响应说明 Base URL、API Key、Model ID 三要素正确。如果报 401说明 Key 有问题如果报连接失败说明 Base URL 写错了。第二步验证顺序流水线。调用sequentialSqlAgent.invoke(查询最近30天订单总额超过500的所有订单)然后从返回的 OverAllState 里取 sql 和 score 两个键OptionalOverAllState result sequentialSqlAgent.invoke(查询最近30天订单总额超过500的所有订单); String sql result.get().value(sql).map(Object::toString).orElse(null); String score result.get().value(score).map(Object::toString).orElse(null); System.out.println(生成的SQL: sql); System.out.println(评分: score);成功的结果应该是一段带 WHERE 条件的 SELECT 语句以及一个 0 到 1 之间的数字。如果 sql 为 null检查 outputKey 是否和取值时的键名一致如果 score 不是数字检查评分智能体的 sysPrompt 是否明确要求「只输出数字」。第三步验证并行流水线。调用后检查 research_report 键是否包含三个维度的分析内容。并行模式的常见问题是某个子智能体超时导致整体失败这时可以调低 maxConcurrency 或检查各子智能体的 prompt 是否过长。第四步验证循环流水线。故意给一个模糊的查询观察是否触发重试。你可以在评分智能体里临时把阈值调高强制循环多次确认 LoopMode.condition 的判断逻辑生效。实测下来最容易出问题的环节是状态键的传递。AgentScope 用 AppendStrategy 和 ReplaceStrategy 管理状态messages 通常用 AppendStrategy而 input、sql 这类单值用 ReplaceStrategy。如果策略配错前序智能体的输出会被覆盖或无限追加。建议在验证阶段打印完整的 OverAllState确认每个键的值符合预期。5. 常见报错排查对照表多智能体系统的报错往往不在代码本身而在配置和状态传递。下面按真实报错信息给出排查路径。401 Unauthorized 或 invalid api key这是最常见的接入错误。检查三件事环境变量 TAOTOKEN_API_KEY 是否在当前终端会话生效用echo $TAOTOKEN_API_KEY确认Base URL 是否写成了https://taotoken.net/api而不是其他路径Model ID 是否在 TaoToken 支持的模型列表里。注意 Base URL 末尾不要多加斜杠。local proxy failed 或 connection refused这类报错通常和网络环境有关。先确认你的运行环境能正常访问外部 API再检查是否有本地代理配置干扰。如果你在容器里运行确认容器网络策略允许出站请求。reading choices 相关空指针这个报错说明模型返回了响应但响应结构里没有 choices 字段。常见原因是 Base URL 指向了一个不兼容 OpenAI 协议的端点或者 Model ID 写成了不存在的模型。回到 TaoToken 的模型列表确认 modelName 拼写。OAuth 或 token expired如果你用的是需要 OAuth 的通道检查 token 是否过期。TaoToken 的 API Key 方式不涉及 OAuth 流程如果你看到这个报错说明配置里混入了其他认证方式检查是否有残留的旧配置覆盖了 apiKey 设置。outputKey 取值为 null不是报错但结果不对。检查 AgentScopeAgent 构建时的 outputKey 和取值时的键名是否完全一致大小写敏感。另外确认 includeContents 参数是否符合预期false 表示不传递历史消息。循环流水线不停止LoopMode.condition 的判断逻辑有问题。检查 messages 最后一条的内容格式如果评分智能体输出的是「评分0.8」而不是纯数字Double.parseDouble 会抛异常。建议在评分智能体的 sysPrompt 里强制「只输出数字不要任何其他文字」。并行流水线部分结果缺失检查 mergeStrategy 和 mergeOutputKey 配置。DefaultMergeStrategy 会把各子智能体的输出合并到一个键如果某个子智能体没有产出检查它的 instruction 占位符是否被正确替换。如果你在排查过程中需要确认模型通道是否正常可以先用模型对话功能单独测试如果确认是接入配置问题对照接入文档逐项核对 Base URL、Key、Model ID 三要素。长期跑编码类 Agent 任务的话Coding Plan 在配额和稳定性上更适合持续调用。6. 模式选型与后续接入建议7 种模式不是让你全部用上而是让你在遇到具体场景时有对应的结构可选。任务有固定阶段划分就用 Pipeline需要按输入类型分发就用 Routing智能体之间需要相互转交就用 Handoffs一个主智能体协调多个子智能体就用 Supervisor需要动态委派就用 Subagent按需加载专业能力就用 Skills需要复杂条件分支和自定义图编排就用 Workflow。选型的核心判断标准是你的任务流程是「确定的」还是「动态的」。确定流程用 Pipeline 和 Workflow动态决策用 Routing、Handoffs、Supervisor 和 Subagent。Skills 比较特殊它解决的是知识加载效率问题可以和其他模式叠加使用。接入层面建议把 TaoToken 的 Base URL 和 Key 统一放在环境变量或配置中心不要在每个模块里重复写。AgentScope 的每个 AgentScopeAgent 可以传入不同的 Model Bean这意味着你可以在同一个协作流程里让不同环节用不同模型比如路由分类用轻量模型、SQL 生成用强模型、评分用中等模型。这种混合配置在 TaoToken 统一通道下只需要改 modelName 参数不需要维护多套 Key。最后给一个实操建议先把顺序流水线跑通确认状态传递和 outputKey 机制理解正确再逐步尝试并行和循环。多智能体系统的调试成本主要花在状态追踪上建议在开发阶段打开详细日志打印每个节点执行后的完整状态快照。等你把 Pipeline 和 Routing 两个模式吃透剩下的模式本质上都是这两种的变体组合。 
长河君 · 2026/10/9 17:36:41 · 阅读 1.2k AgentScope 实战训练营：7 种多智能体协作模式详解与 TaoToken 统一接入
1. AgentScope 多智能体协作模式到底解决什么问题如果你正在搜索 AgentScope 多智能体协作模式大概率已经遇到过这样的困境单个大模型智能体在处理复杂任务时要么上下文塞爆要么职责混乱要么一个环节出错整条链路崩掉。AgentScope 是阿里巴巴开源的一套面向智能体编程的框架它把「多个专业智能体分工协作」这件事从概念变成了可落地的工程结构。简单说它让你能像搭积木一样把 SQL 生成、质量评审、路由分发、任务交接这些能力拆成独立智能体再按不同拓扑组合起来。它适合谁适合已经写过单 Agent Demo、但发现单 Agent 撑不住真实业务复杂度的 Java 开发者也适合想系统理解多智能体协作范式、而不是只会调一个 API 的技术负责人。AgentScope 的核心价值在于它提供了 7 种经过工程验证的协作模式Pipeline 流水线、Routing 路由、Handoffs 交接、Supervisor 监督器、Subagent 子智能体、Skills 技能系统、Workflow 工作流。每种模式对应一类典型场景选错了模式后面写再多代码都是白费。我试过把同一个「自然语言转 SQL 并校验」的需求分别用单 Agent 和 Pipeline 模式实现单 Agent 版本在第三轮对话就开始丢失表结构约束而 Pipeline 版本把生成和评分拆成两个智能体后评分智能体可以独立拿到原始请求和生成的 SQL 做交叉验证稳定性提升非常明显。这就是多智能体协作的意义不是让模型更聪明而是让系统结构更可靠。在动手之前你需要先理解一个关键点AgentScope 的协作模式不是互斥的而是可以嵌套的。比如 Supervisor 模式内部可以挂一个 Pipeline 作为子流程Routing 模式的路由目标本身可以是 Handoffs 链。所以学习路径应该是先逐个吃透 7 种模式的最小可运行单元再考虑组合。接下来的内容会从统一接入配置开始逐步给出每种模式的可复制片段和验证方法。2. TaoToken 统一接入一个 Key 打通多模型通道在搭建多智能体系统时最容易被低估的摩擦点其实是模型接入。AgentScope 默认走 DashScope 通道但实际项目里你往往需要对比不同模型在路由分类、SQL 生成、质量评分等环节的表现。如果每个模型都单独申请 Key、单独配环境变量、单独处理 Base URL光是配置管理就会消耗大量精力。TaoToken 在这里的角色是提供一个统一的 API 通道让你用同一套 Key 和 Base URL 访问多个模型AgentScope 侧只需要改 modelName 就能切换。先说清楚接入位置。TaoToken 的 API 端点是https://taotoken.net/api这个地址不加任何查询参数直接作为 OpenAI 兼容协议的 Base URL 使用。你需要在 TaoToken 控制台创建一个 API Key然后把它放进环境变量。注意不要硬编码在代码或 application.yml 里多智能体项目通常会有多个模块共享配置硬编码一旦泄露影响面很大。环境变量设置方式如下Windows PowerShell 和 Linux/macOS 分开写# Linux / macOS export TAOTOKEN_API_KEYsk-你的TaoToken密钥 # Windows PowerShell $env:TAOTOKEN_API_KEY sk-你的TaoToken密钥然后在 AgentScope 的模型构建处把 Base URL 指向 TaoToken 的 API 地址。AgentScope 底层用的是 OpenAI 兼容的 ChatModel 接口所以配置方式和标准 OpenAI SDK 一致。下面是一个最小可运行的模型 Bean 配置放在你的Configuration类里Configuration public class ModelConfig { Bean public Model taoTokenChatModel() { return OpenAIChatModel.builder() .apiKey(System.getenv(TAOTOKEN_API_KEY)) .baseUrl(https://taotoken.net/api) .modelName(qwen-plus) .build(); } }这里有三个参数必须同时正确Base URL 是https://taotoken.net/apiAPI Key 从环境变量读取Model ID 按你实际要用的模型填写。这三个要素缺一个就会在请求时失败后面排障章节会详细对照报错。如果你用的是 Spring AI Alibaba 的 starter配置方式略有不同需要在 application.yml 里指定 base-urlspring: ai: openai: api-key: ${TAOTOKEN_API_KEY} base-url: https://taotoken.net/api chat: options: model: qwen-plus配置完成后建议先不要急着跑多智能体而是用一个最简单的单 Agent 请求验证通道是否打通。验证方法在下一节给出。这里要强调一点TaoToken 是统一接入通道不是替代 AgentScope 的编排能力。AgentScope 负责智能体之间的协作逻辑TaoToken 负责模型请求的通道统一两者是互补关系。你可以在 Pipeline 的 SQL 生成节点用 qwen-plus在评分节点用 qwen-turbo只需要在各自的 AgentScopeAgent 构建时传入不同的 Model Bean 即可。3. 7 种协作模式的可复制配置片段这一节是全文的核心操作部分。我会按模式逐个给出最小可运行的配置片段每个片段都基于上一节的 TaoToken 模型 Bean。你不需要一次全部跑通建议按顺序来每跑通一个再进入下一个。3.1 Pipeline 流水线顺序、并行、循环三种形态Pipeline 是最基础的协作模式适合任务有明确阶段划分的场景。顺序流水线的典型例子是「自然语言 → SQL 生成 → SQL 评分」两个智能体通过 outputKey 和 instruction 占位符传递数据Bean(sequentialSqlAgent) public SequentialAgent sequentialSqlAgent(Model model) { AgentScopeAgent sqlGenerator AgentScopeAgent.fromBuilder( ReActAgent.builder() .name(sql_generator) .model(model) .sysPrompt(你是MySQL专家根据自然语言输出可执行SQL只输出SQL语句。) .memory(new InMemoryMemory())) .name(sql_generator) .instruction({input}) .outputKey(sql) .includeContents(false) .build(); AgentScopeAgent sqlRater AgentScopeAgent.fromBuilder( ReActAgent.builder() .name(sql_rater) .model(model) .sysPrompt(你是SQL质量评审员根据用户请求和生成的SQL输出0到1的评分只输出数字。) .memory(new InMemoryMemory())) .name(sql_rater) .instruction(用户请求{input}生成的SQL{sql}) .outputKey(score) .build(); return SequentialAgent.builder() .name(sequential_sql_agent) .subAgents(List.of(sqlGenerator, sqlRater)) .build(); }并行流水线适合多角度分析后合并的场景比如对同一主题从技术、金融、市场三个维度同时分析。关键参数是 mergeStrategy 和 maxConcurrencyBean(parallelResearchAgent) public ParallelAgent parallelResearchAgent(Model model) { AgentScopeAgent techAgent buildExpert(model, tech_expert, 从技术可行性角度分析, tech_view); AgentScopeAgent financeAgent buildExpert(model, finance_expert, 从财务回报角度分析, finance_view); AgentScopeAgent marketAgent buildExpert(model, market_expert, 从市场竞争角度分析, market_view); return ParallelAgent.builder() .name(parallel_research_agent) .subAgents(List.of(techAgent, financeAgent, marketAgent)) .mergeStrategy(new ParallelAgent.DefaultMergeStrategy()) .mergeOutputKey(research_report) .maxConcurrency(3) .build(); }循环流水线用于迭代优化直到满足条件比如 SQL 评分低于 0.5 就重新生成。这里用 LoopMode.condition 定义停止条件Bean(loopSqlRefinementAgent) public LoopAgent loopSqlRefinementAgent(Model model) { SequentialAgent inner SequentialAgent.builder() .name(sql_agent) .subAgents(List.of(sqlGenerator(model), sqlRater(model))) .build(); return LoopAgent.builder() .name(loop_sql_refinement_agent) .subAgent(inner) .loopStrategy(LoopMode.condition(messages - { String last messages.get(messages.size() - 1).getText(); double score Double.parseDouble(last.trim()); return score 0.5; })) .build(); }3.2 Routing 路由按输入类型分发到专家Routing 模式解决的是「不同问题找不同专家」的问题。核心是 AgentScopeRoutingAgent它先用 LLM 对输入分类再并行调用匹配的专家智能体。每个专家需要注册自己的工具集instruction 里的占位符格式是{agentName_input}Bean public AgentScopeRoutingAgent routerAgent(Model model, AgentScopeAgent githubAgent, AgentScopeAgent notionAgent, AgentScopeAgent slackAgent) { return AgentScopeRoutingAgent.builder() .name(router) .model(model) .description(根据查询内容路由到GitHub、Notion或Slack专家) .subAgents(List.of(githubAgent, notionAgent, slackAgent)) .build(); }专家智能体的构建要点是工具注册和 outputKey 命名。以 GitHub 专家为例Bean public AgentScopeAgent githubAgent(Model model, GitHubStubTools tools) { Toolkit toolkit new Toolkit(); toolkit.registerTool(tools); return AgentScopeAgent.fromBuilder( ReActAgent.builder() .name(github) .sysPrompt(你是GitHub专家擅长搜索代码和PR。) .model(model) .toolkit(toolkit) .memory(new InMemoryMemory())) .name(github) .instruction(请处理请求{github_input}) .outputKey(github_key) .build(); }3.3 Handoffs 交接与 Supervisor 监督器Handoffs 模式让智能体之间通过工具调用相互转交任务适合销售转客服、多部门协作这类流程。核心实现是定义一个交接工具智能体在判断需要转交时调用它。Supervisor 模式则是主从架构一个监督器智能体负责任务分配和结果整合子智能体各自独立执行。这两种模式的配置片段较长建议先跑通 Pipeline 和 Routing 后再进入。3.4 Subagent、Skills 与 WorkflowSubagent 模式通过 delegate_task 这类任务工具动态委派子智能体适合技术尽调这种需要实时决定处理方案的场景。Skills 模式实现按需加载技能智能体初始只加载基础能力需要时再动态加载专业技能适合大型知识库管理。Workflow 模式用 StateGraph 自定义图编排支持条件分支、并行执行和循环处理是最灵活的编排方式StateGraph graph new StateGraph(workflow_graph, () - { MapString, KeyStrategy strategies new HashMap(); strategies.put(messages, new AppendStrategy(false)); strategies.put(input, new ReplaceStrategy()); return strategies; }); graph.addNode(preprocess, node_async(new PreprocessNode())); graph.addNode(generate, sqlGenerator.asNode()); graph.addNode(rate, sqlRater.asNode()); graph.addEdge(START, preprocess); graph.addEdge(preprocess, generate); graph.addEdge(generate, rate); graph.addEdge(rate, END); CompiledGraph compiled graph.compile();4. 本地运行验证与成功结果确认配置写完后最关键的一步是验证。很多人卡在这里不是因为代码错而是因为不知道「什么样算成功」。这一节给出从单 Agent 到多智能体的递进验证方法。第一步先验证 TaoToken 通道本身是否通。写一个最小的单 Agent 请求不要涉及任何协作逻辑Model model taoTokenChatModel(); ReActAgent agent ReActAgent.builder() .name(ping_agent) .model(model) .sysPrompt(你是一个测试助手收到消息后回复pong。) .memory(new InMemoryMemory()) .build(); Msg reply agent.reply(Msg.builder().textContent(ping).build()); System.out.println(reply.getText());如果这一步输出包含 pong 或类似响应说明 Base URL、API Key、Model ID 三要素正确。如果报 401说明 Key 有问题如果报连接失败说明 Base URL 写错了。第二步验证顺序流水线。调用sequentialSqlAgent.invoke(查询最近30天订单总额超过500的所有订单)然后从返回的 OverAllState 里取 sql 和 score 两个键OptionalOverAllState result sequentialSqlAgent.invoke(查询最近30天订单总额超过500的所有订单); String sql result.get().value(sql).map(Object::toString).orElse(null); String score result.get().value(score).map(Object::toString).orElse(null); System.out.println(生成的SQL: sql); System.out.println(评分: score);成功的结果应该是一段带 WHERE 条件的 SELECT 语句以及一个 0 到 1 之间的数字。如果 sql 为 null检查 outputKey 是否和取值时的键名一致如果 score 不是数字检查评分智能体的 sysPrompt 是否明确要求「只输出数字」。第三步验证并行流水线。调用后检查 research_report 键是否包含三个维度的分析内容。并行模式的常见问题是某个子智能体超时导致整体失败这时可以调低 maxConcurrency 或检查各子智能体的 prompt 是否过长。第四步验证循环流水线。故意给一个模糊的查询观察是否触发重试。你可以在评分智能体里临时把阈值调高强制循环多次确认 LoopMode.condition 的判断逻辑生效。实测下来最容易出问题的环节是状态键的传递。AgentScope 用 AppendStrategy 和 ReplaceStrategy 管理状态messages 通常用 AppendStrategy而 input、sql 这类单值用 ReplaceStrategy。如果策略配错前序智能体的输出会被覆盖或无限追加。建议在验证阶段打印完整的 OverAllState确认每个键的值符合预期。5. 常见报错排查对照表多智能体系统的报错往往不在代码本身而在配置和状态传递。下面按真实报错信息给出排查路径。401 Unauthorized 或 invalid api key这是最常见的接入错误。检查三件事环境变量 TAOTOKEN_API_KEY 是否在当前终端会话生效用echo $TAOTOKEN_API_KEY确认Base URL 是否写成了https://taotoken.net/api而不是其他路径Model ID 是否在 TaoToken 支持的模型列表里。注意 Base URL 末尾不要多加斜杠。local proxy failed 或 connection refused这类报错通常和网络环境有关。先确认你的运行环境能正常访问外部 API再检查是否有本地代理配置干扰。如果你在容器里运行确认容器网络策略允许出站请求。reading choices 相关空指针这个报错说明模型返回了响应但响应结构里没有 choices 字段。常见原因是 Base URL 指向了一个不兼容 OpenAI 协议的端点或者 Model ID 写成了不存在的模型。回到 TaoToken 的模型列表确认 modelName 拼写。OAuth 或 token expired如果你用的是需要 OAuth 的通道检查 token 是否过期。TaoToken 的 API Key 方式不涉及 OAuth 流程如果你看到这个报错说明配置里混入了其他认证方式检查是否有残留的旧配置覆盖了 apiKey 设置。outputKey 取值为 null不是报错但结果不对。检查 AgentScopeAgent 构建时的 outputKey 和取值时的键名是否完全一致大小写敏感。另外确认 includeContents 参数是否符合预期false 表示不传递历史消息。循环流水线不停止LoopMode.condition 的判断逻辑有问题。检查 messages 最后一条的内容格式如果评分智能体输出的是「评分0.8」而不是纯数字Double.parseDouble 会抛异常。建议在评分智能体的 sysPrompt 里强制「只输出数字不要任何其他文字」。并行流水线部分结果缺失检查 mergeStrategy 和 mergeOutputKey 配置。DefaultMergeStrategy 会把各子智能体的输出合并到一个键如果某个子智能体没有产出检查它的 instruction 占位符是否被正确替换。如果你在排查过程中需要确认模型通道是否正常可以先用模型对话功能单独测试如果确认是接入配置问题对照接入文档逐项核对 Base URL、Key、Model ID 三要素。长期跑编码类 Agent 任务的话Coding Plan 在配额和稳定性上更适合持续调用。6. 模式选型与后续接入建议7 种模式不是让你全部用上而是让你在遇到具体场景时有对应的结构可选。任务有固定阶段划分就用 Pipeline需要按输入类型分发就用 Routing智能体之间需要相互转交就用 Handoffs一个主智能体协调多个子智能体就用 Supervisor需要动态委派就用 Subagent按需加载专业能力就用 Skills需要复杂条件分支和自定义图编排就用 Workflow。选型的核心判断标准是你的任务流程是「确定的」还是「动态的」。确定流程用 Pipeline 和 Workflow动态决策用 Routing、Handoffs、Supervisor 和 Subagent。Skills 比较特殊它解决的是知识加载效率问题可以和其他模式叠加使用。接入层面建议把 TaoToken 的 Base URL 和 Key 统一放在环境变量或配置中心不要在每个模块里重复写。AgentScope 的每个 AgentScopeAgent 可以传入不同的 Model Bean这意味着你可以在同一个协作流程里让不同环节用不同模型比如路由分类用轻量模型、SQL 生成用强模型、评分用中等模型。这种混合配置在 TaoToken 统一通道下只需要改 modelName 参数不需要维护多套 Key。最后给一个实操建议先把顺序流水线跑通确认状态传递和 outputKey 机制理解正确再逐步尝试并行和循环。多智能体系统的调试成本主要花在状态追踪上建议在开发阶段打开详细日志打印每个节点执行后的完整状态快照。等你把 Pipeline 和 Routing 两个模式吃透剩下的模式本质上都是这两种的变体组合。