企业官网建设流程全解析

1. 为什么主 Agent 越跑越乱：Subagents 子智能体设计模式要解决的真实问题

如果你正在做 Agent 工程，大概率遇到过这种场景：一个主 Agent 挂着十几个工具，既要查天气、又要查景点、还要写代码、还要总结，聊到第五轮之后，系统提示词被历史消息挤爆，模型开始胡言乱语，工具调用也开始串台。这不是模型不行，而是上下文污染和工具权限过载同时发生了。

Subagents（子智能体）设计模式就是冲着这两个问题来的。它的核心思想很朴素：主 Agent 不亲自干活，而是把任务通过 TaskTool 派发给专职的子智能体，子智能体在独立上下文窗口里跑完，只把最终结果回传给主 Agent。主对话保持聚焦，子智能体各自带着最小必要的系统提示和工具集，互不干扰。

这个模式适合谁？适合已经写过基础 ReAct Agent、手里有 3 个以上工具、开始感觉提示词管理吃力的开发者。如果你还在单 Agent 阶段，先把基础打牢；如果你已经在多 Agent 协作里被上下文膨胀折磨过，那这篇就是给你写的。

我这次用 AgentScope 1.0.11 + JDK 21 复现整个链路，模型通道统一走 TaoToken 的 OpenAI 兼容接口，这样主 Agent 和所有子智能体共用一套 Key，不用为每个子 Agent 单独配环境变量。下面从设计模式拆解到可复制配置，一步步来。

先明确 Subagents 和 Supervisor 的区别，很多人会混。Supervisor 是严格中心化控制，监督者是唯一决策节点，所有子智能体只能和监督者通信；Subagents 模式里主 Agent 负责分发，但子智能体拥有更强的上下文隔离和工具权限隔离，主 Agent 只接收子智能体的最终输出，不继承它的推理过程。这个差异决定了 Subagents 更适合工具权限物理隔离的场景，比如一个子智能体只能访问内部 API，另一个只能读文件系统。

2. TaoToken 统一 Key 通道前置准备：让主 Agent 和子智能体共用一套凭证

在动手写代码之前，先把模型通道理顺。Subagents 模式里会同时存在主 Agent 和多个子智能体，如果每个都去读不同的 API Key 环境变量，配置会迅速失控。我的做法是统一走 TaoToken 的 OpenAI 兼容接口，主 Agent 和子智能体共用同一个 Base URL 和 Key，只在 Model ID 上按需区分。

TaoToken 在这里扮演的是统一模型网关的角色，官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点是 https://taotoken.net/api 。注意 API 地址后面不加任何 UTM 参数，保持干净。

你需要准备三样东西，我把它叫做「三件套」：

生成 Key 的路径是进入控制台后创建 API Key，具体页面在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。如果你还没决定用哪个模型，可以先到模型对话页面试一下响应质量，地址是 https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

这里有个容易踩的坑：AgentScope 的 DashScopeChatModel 默认走的是 DashScope 协议，如果你直接填 TaoToken 的地址会报协议不匹配。解决办法是用 OpenAI 兼容的模型类，或者把 Base URL 配到支持 OpenAI 协议的模型构造器里。我在项目里统一封装了一个模型工厂，主 Agent 和子智能体都从这里取模型实例。

环境变量我建议这样设置，避免硬编码：

export TAOTOKEN_API_KEY="sk-你的key" export TAOTOKEN_BASE_URL="https://taotoken.net/api" export TAOTOKEN_MODEL="你的模型ID"

如果你打算长期跑编码类 Agent，可以顺带了解下 Coding Plan，地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，它更适合高频调用的场景。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，遇到参数问题先查这里。

把通道准备好之后，主 Agent 和子智能体就都能用同一套凭证跑起来，后面配置子智能体时只需要关心它的系统提示和工具权限，不用再操心 Key 的问题。

3. 可复制配置：TaskTool 拆分子任务与子智能体独立上下文落地

这一节是全文的核心，我会给出可以直接复制的配置片段。整个 Subagents 模式落地要解决两个问题：主 Agent 怎么唤起子智能体，以及两者怎么交换信息。我的方案是「工具 + 任务存储器」：TaskTool 负责派发，TaskOutputTool 负责取回结果，中间用一个 TaskRepository 做异步任务管理。

先看子智能体的定义文件。我用 Markdown + YAML front matter 的方式声明子智能体，这样新增一个子智能体只需要加一个 md 文件，不用改主代码。文件放在src/main/resources/agents/tourism-planning.md：

--- name: 旅游规划助手 description: 你是一个旅游规划助手，通过使用 scenic_spot_info 工具获取景点信息，然后规划简单旅游攻略。 tools: scenic_spot_info --- 你是一个旅游规划助手，通过获取到的景点信息，然后规划简单旅游攻略。 **你的能力:** - 使用 scenic_spot_info 工具进行景点查询 - 根据查询景点，简单规划一份旅游攻略

这个文件的name字段就是 TaskTool 里的subagent_type，tools字段决定了这个子智能体能访问哪些工具，这就是工具权限隔离的落点。主 Agent 即使挂了十个工具，旅游规划助手也只能看到scenic_spot_info一个。

接下来是 TaskTool 的调用参数。主 Agent 调用时传入四个参数：

{ "description": "查询广州景点", "prompt": "查询广州越秀公园的景点信息并规划攻略", "subagent_type": "旅游规划助手", "run_in_background": true }

run_in_background=true时 TaskTool 会立刻返回一个 task_id，主 Agent 可以继续和用户交互，等需要结果时再调 TaskOutputTool。这就是 Subagents 模式里「主对话保持聚焦」的关键——子智能体在后台跑，主 Agent 不被阻塞。

TaskOutputTool 的调用参数：

{ "task_id": "task_xxxx", "block": true, "timeout": 30000 }

block=true表示等待子智能体完成，timeout最大 600000 毫秒。如果子智能体跑得慢，主 Agent 可能会多次调用 TaskOutputTool 轮询，直到拿到结果。

如果你用的是 Cline 或 Claude Code 这类工具，配置方式类似，核心还是三件套。以 Cline 的 MCP 配置为例，Base URL 填https://taotoken.net/api，Key 填你的凭证，Model ID 填对应模型。Codex 的auth.json也是同样思路，把 Base URL 和 Key 写进去即可。CC Switch 切换配置时，确保 Base URL、Key、Model ID 三项一致，否则会出现 401。

子智能体的独立上下文是怎么实现的？在 AgentSpecReActAgentFactory 里，每个子智能体都用new InMemoryMemory()创建独立记忆，系统提示来自 md 文件的 body 部分，工具集来自tools字段。主 Agent 只拿到子智能体call()返回的最终文本，不继承它的中间推理。这就是上下文物理隔离。

4. 端到端验证：跑通主 Agent 派发两个子智能体的完整请求

配置写完之后，必须验证调度效果。我设计了一个测试用例：用户问「今天去广州越秀公园参观，应该穿什么？有什么景点可以逛？」这个问题同时涉及穿搭和景点，正好触发两个子智能体。

主 Agent 的系统提示这样写：

ReActAgent orchestratorReActAgent = ReActAgent.builder() .name("聊天助手") .description("你是一个聊天助手，如果遇到用户穿搭和景点规划问题，可以委托给子Agent处理，最后归纳总结。") .model(model) .sysPrompt("你是一个聊天助手，如果遇到用户穿搭和景点规划问题，可以委托给\"出门穿搭推荐助手\"、\"旅游规划助手\"的子Agent进行处理，最后你归纳总结。") .toolkit(orchestratorToolkit) .memory(new InMemoryMemory()) .build();

主 Agent 的 Toolkit 里只注册两个工具：TaskTool 和 TaskOutputTool。它自己没有任何业务工具，所有业务能力都通过子智能体提供。

运行之后，控制台会依次打印这些日志：

=====执行task工具======= =====执行getWeather工具======= =====执行task工具======= =====执行getScenicSpotInfo工具======= =====执行taskOutput工具======= =====执行taskOutput工具======= ==================回复的信息===========================

从日志能读出完整的调度链路：主 Agent 先调 TaskTool 派发穿搭任务，穿搭子智能体调用 getWeather 拿到天气；主 Agent 再调 TaskTool 派发景点任务，景点子智能体调用 getScenicSpotInfo 拿到景点信息；然后主 Agent 两次调用 TaskOutputTool 取回两个子智能体的结果，最后汇总输出。

这里有个细节值得注意：TaskOutputTool 被调用了两次，而不是一次。因为两个子智能体是异步跑的，主 Agent 需要分别取回。如果某个子智能体跑得慢，主 Agent 可能会对同一个 task_id 多次轮询，这是正常行为，不是 bug。

验证成功的标志是最终输出里同时包含穿搭建议和景点攻略，且两个子智能体的工具调用日志各自独立。如果你看到主 Agent 直接自己回答了问题而没有调 TaskTool，说明系统提示里的委托意图不够明确，需要加强「必须委托给子 Agent」的措辞。

实测下来，这种「主 Agent 只做编排、子智能体做执行」的结构，在工具数量超过 5 个之后优势非常明显。主 Agent 的上下文始终保持在很小的规模，不会因为某个子智能体的长推理而膨胀。

5. 常见报错排查：401、local proxy failed 与 reading choices 的真实原因

跑 Subagents 的过程中，我踩过几个典型报错，这里逐个拆解。

401 Unauthorized：最常见的原因是 Key 没生效或 Base URL 写错。检查三件套是否一致——Base URL 必须是https://taotoken.net/api，注意结尾没有斜杠，也没有多余路径。如果你在 Cline 或 CC Switch 里配置，确认 Key 没有多余空格。还有一种情况是环境变量没被读到，Java 里用System.getenv("TAOTOKEN_API_KEY")时，确保启动前已经 export。

local proxy failed：这个报错通常出现在你本地配了代理但代理没启动，或者代理地址填错。Subagents 模式下主 Agent 和子智能体都会走同一个通道，如果代理配置只对主 Agent 生效、子智能体没继承，就会出现部分请求失败。解决办法是统一在模型工厂里配置，不要分散设置。

reading choices 相关报错：这类错误一般是响应体解析失败，常见于模型返回了非标准 JSON，或者你用的模型类不兼容 OpenAI 协议。如果你用 DashScopeChatModel 去连 TaoToken 的 OpenAI 端点，就会在解析choices字段时报错。换成 OpenAI 兼容的模型构造器即可。

OAuth 相关报错：如果你在 Claude Code 或类似工具里看到 OAuth 失败，说明你走的是账号授权流程而不是 API Key 流程。Subagents 场景建议统一用 API Key，避免授权态过期导致子智能体调用中断。

子智能体找不到工具：检查 md 文件里tools字段的工具名是否和代码里注册的名字一致。比如scenic_spot_info是工具名，如果你在代码里注册的是getScenicSpotInfo，就会匹配不上。工具名以@Tool(name=...)里的为准。

TaskOutputTool 一直返回 running：说明子智能体还没跑完，或者子智能体内部卡住了。先看子智能体的日志有没有报错，再检查 timeout 是否设得太短。默认 30000 毫秒对复杂任务可能不够，可以调到 120000。

排查顺序建议：先确认三件套，再看子智能体日志，最后看主 Agent 的调度日志。大部分问题都出在配置层，而不是代码逻辑。

6. 把 Subagents 用起来：从单 Agent 到多子智能体协作的下一步

走到这里，你已经有了一个能跑通的主 Agent + 两个子智能体的最小闭环。接下来可以做的扩展方向有几个。

第一，把子智能体的定义全部迁移到 md 文件，主代码里只保留 TaskTool 和 TaskOutputTool 的注册。这样新增一个子智能体就是加一个文件，团队协作时每个人负责自己的 md，互不冲突。

第二，给不同子智能体配不同的 Model ID。比如穿搭推荐用便宜快速的模型，旅游规划用推理能力强的模型。因为走的是 TaoToken 统一通道，切换模型只需要改 md 文件里的model字段，不用动 Key。

第三，把 TaskRepository 换成持久化实现。当前用的是内存版，进程重启任务就丢了。生产环境可以换成 Redis 或数据库，让后台任务跨进程存活。

如果你打算把这套模式用到编码 Agent 上，可以看看 Coding Plan 的额度方案，地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。需要生成新的 API Key 时走 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，接入细节查 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

最后说一个我踩过的坑：子智能体的系统提示不要写得太长。独立上下文的优势在于精简，如果你把主 Agent 的完整提示复制给子智能体，隔离就失去意义了。子智能体只需要知道「我是谁、我能用什么工具、我要输出什么格式」，其余交给主 Agent 编排。