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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。注意 API 地址后面不加任何 UTM 参数保持干净。你需要准备三样东西我把它叫做「三件套」配置项值说明Base URLhttps://taotoken.net/apiOpenAI 兼容端点不加 UTMAPI Key在控制台生成主 Agent 和子智能体共用Model ID按需选择子智能体可用更便宜的模型生成 Key 的路径是进入控制台后创建 API Key具体页面在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你还没决定用哪个模型可以先到模型对话页面试一下响应质量地址是 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。这里有个容易踩的坑AgentScope 的 DashScopeChatModel 默认走的是 DashScope 协议如果你直接填 TaoToken 的地址会报协议不匹配。解决办法是用 OpenAI 兼容的模型类或者把 Base URL 配到支持 OpenAI 协议的模型构造器里。我在项目里统一封装了一个模型工厂主 Agent 和子智能体都从这里取模型实例。环境变量我建议这样设置避免硬编码export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_MODEL你的模型ID如果你打算长期跑编码类 Agent可以顺带了解下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它更适合高频调用的场景。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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_typetools字段决定了这个子智能体能访问哪些工具这就是工具权限隔离的落点。主 Agent 即使挂了十个工具旅游规划助手也只能看到scenic_spot_info一个。接下来是 TaskTool 的调用参数。主 Agent 调用时传入四个参数{ description: 查询广州景点, prompt: 查询广州越秀公园的景点信息并规划攻略, subagent_type: 旅游规划助手, run_in_background: true }run_in_backgroundtrue时 TaskTool 会立刻返回一个 task_id主 Agent 可以继续和用户交互等需要结果时再调 TaskOutputTool。这就是 Subagents 模式里「主对话保持聚焦」的关键——子智能体在后台跑主 Agent 不被阻塞。TaskOutputTool 的调用参数{ task_id: task_xxxx, block: true, timeout: 30000 }blocktrue表示等待子智能体完成timeout最大 600000 毫秒。如果子智能体跑得慢主 Agent 可能会多次调用 TaskOutputTool 轮询直到拿到结果。如果你用的是 Cline 或 Claude Code 这类工具配置方式类似核心还是三件套。以 Cline 的 MCP 配置为例Base URL 填https://taotoken.net/apiKey 填你的凭证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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。需要生成新的 API Key 时走 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入细节查 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后说一个我踩过的坑子智能体的系统提示不要写得太长。独立上下文的优势在于精简如果你把主 Agent 的完整提示复制给子智能体隔离就失去意义了。子智能体只需要知道「我是谁、我能用什么工具、我要输出什么格式」其余交给主 Agent 编排。