1. 多 Skills 打架这件事我踩过不止一次如果你正在用 LangChain 搭 Agent并且给同一个 Agent 挂了三个以上的 Skills大概率见过这些症状模型一会儿按技术文档的格式输出一会儿又切成测试用例的模板工具调用时明明该读文件它偏偏去调搜索上下文窗口被一堆 Skill 提示词塞满真正对话没几轮就开始丢历史。这不是模型变笨了而是多 Skills 共享同一个上下文导致的指令污染。LangChain 的 Skills 机制本质是把专业化提示词和知识注入 Agent 上下文。挂一个 Skill 时行为清晰挂四个就变成四套工作流在同一个脑子里抢方向盘。我试过用提示词里加优先级说明来压制效果有限因为模型在工具选择阶段依然会被不同 Skill 推荐的工具体系干扰。SubAgent 模式解决的就是这个问题主 Agent 只负责路由判断每个子 Agent 只挂自己需要的 Skills上下文互相隔离。子 Agent 内部的工具调用过程对主 Agent 不可见只返回最终文本结果。这样主 Agent 的对话历史不会被十几轮工具调用日志挤占Token 消耗也大幅下降。这篇内容面向已经在写 LangChain Agent、但被多 Skills 冲突卡住的开发者。我会用 TaoToken 作为统一的 Key 和 API 通道把主 Agent 和子 Agent 的模型调用收敛到一个入口然后给出可复制的config.toml与settings.json配置骨架最后用一次路由验证确认子 Agent 隔离生效。整套流程可以在本地复现。2. 为什么用 TaoToken 统一 Key而不是每个 Agent 各配一套SubAgent 架构下你会同时跑主 Agent 和多个子 Agent。如果每个 Agent 各自读环境变量、各自配 base_url 和 api_key会出现三个麻烦一是密钥散落在多个文件里轮换时容易漏改二是不同 Agent 可能指向不同通道排查问题时无法判断是模型行为差异还是通道差异三是子 Agent 动态 import 时如果环境变量没加载会直接报鉴权失败。TaoToken 在这里的角色是统一 Key 与 API 通道。你只需要在 TaoToken 控制台创建一个 API Key然后在配置层把它注入给所有 Agent。主 Agent 和子 Agent 共用同一个 base_url 和 key模型调用链路一致出问题时只需要看一处日志。需要提前准备的东西一个 TaoToken 账号在控制台创建一个 API Key本地 Node.js 环境建议 18 以上因为要用到动态import()一个 LangChain 项目骨架能跑通单 Agent 的基础调用TaoToken 的 API 入口是https://taotoken.net/api这个地址在配置里会作为base_url使用。控制台创建 Key 的入口在 consoleKey 管理在 api-keys。如果你还没决定用哪个模型可以先去 模型对话 试一下调用效果确认通道可用再写进配置。注意不要把 API Key 硬编码进 Agent 源码。SubAgent 会动态 import 多个模块硬编码会导致密钥出现在多个文件里后续维护成本很高。3. 可复制的配置骨架config.toml 与 settings.json这一节给出两个配置文件。config.toml负责声明模型通道和默认参数settings.json负责声明 Agent 与 Skills 的映射关系。两者配合主 Agent 和子 Agent 都从同一份配置读取 Key。3.1 config.toml统一模型通道# config.toml # TaoToken 统一 Key 与 API 通道配置 [provider] name taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY # 从环境变量读取不写死 [models.default] model claude-sonnet-4-5 temperature 0.3 max_tokens 4096 [models.router] # 主 Agent 用于路由判断温度调低让决策更稳定 model claude-sonnet-4-5 temperature 0.1 max_tokens 1024 [subagent] max_history_length 15 # 传给子 Agent 的历史消息窗口 default_timeout_ms 60000这里的关键点是api_key_env。所有 Agent 都通过环境变量拿 Key而不是各自读不同的配置项。启动前执行export TAOTOKEN_API_KEY你的_TaoToken_Key如果你在 Windows PowerShell 下$env:TAOTOKEN_API_KEY你的_TaoToken_Key3.2 settings.jsonAgent 与 Skills 映射{ agents: { main-assistant: { role: router, model: models.router, subagents: [chart-agent, code-assistant-agent, env-resolver-agent], skills: [] }, chart-agent: { role: subagent, model: models.default, skills: [mermaid], description: 负责生成流程图、架构图等图表内容 }, code-assistant-agent: { role: subagent, model: models.default, skills: [git-clone, dev-design], description: 负责代码分析、仓库操作与技术设计 }, env-resolver-agent: { role: subagent, model: models.default, skills: [env-resolver], description: 负责环境排查与依赖问题定位 } }, subagent_registry: { chart-agent: { import_path: /agents/chart-agent, name: 图表生成助手 }, code-assistant-agent: { import_path: /agents/code-assistant-agent, name: 代码助手 }, env-resolver-agent: { import_path: /agents/env-resolver-agent, name: 环境排查助手 } } }注意main-assistant的skills是空数组。这是 SubAgent 模式的核心主 Agent 不挂任何 Skill只保留路由能力。每个子 Agent 的skills只包含自己需要的项互不重叠。3.3 子 Agent 注册表动态 import 打破循环依赖子 Agent 模块会导入/agents/tools而注册表也在该目录下直接静态导入会形成循环依赖。用动态import()惰性加载解决// src/agents/tools/subagentTools.js const SUBAGENT_REGISTRY { chart-agent: { import: () import(/agents/chart-agent), name: 图表生成助手, description: 生成流程图、架构图输入为结构化描述输出为 mermaid 代码 }, code-assistant-agent: { import: () import(/agents/code-assistant-agent), name: 代码助手, description: 分析代码仓库、执行 git 操作、输出技术设计文档 }, env-resolver-agent: { import: () import(/agents/env-resolver-agent), name: 环境排查助手, description: 定位依赖冲突、环境变量缺失、版本不匹配问题 } }; export function getSubagentTools({ include, exclude, userId, sessionId, messages, maxHistoryLength 15 }) { let names Object.keys(SUBAGENT_REGISTRY); if (include) names names.filter(n include.includes(n)); if (exclude) names names.filter(n !exclude.includes(n)); return names.map(agentName ({ name: call_agent, description: 委派任务给子 Agent。可选值${names.join(, )}, schema: { type: object, properties: { agentName: { type: string, enum: names }, description: { type: string, description: 任务描述 }, includeHistory: { type: boolean, default: true } }, required: [agentName, description] }, func: async ({ agentName, description, includeHistory }) { const entry SUBAGENT_REGISTRY[agentName]; if (!entry) return 未知子 Agent: ${agentName}; try { const mod await entry.import(); const agent await mod.default.createAgent(); const input includeHistory ? [...messages.slice(-maxHistoryLength), [委派任务] ${description}] : [description]; const result await agent.invoke({ messages: input }); return result.messages.at(-1).content; } catch (error) { return 子 Agent 调用失败: ${error.message}; } } })); }这段代码里有两个设计点值得说明。第一call_agent采用 Single Dispatch 模式一个工具加agentName参数选择子 Agent比每个子 Agent 一个独立工具更好管理。第二catch块把错误转成文本返回给主 Agent子 Agent 崩溃不会阻塞主流程主 Agent 收到失败信息后可以用自身工具补救。4. 验证请求确认路由与隔离生效配置写完后需要验证三件事主 Agent 是否按预期委派、子 Agent 是否只加载自己的 Skills、主 Agent 上下文是否只增加一条 ToolMessage。4.1 启动与基础调用export TAOTOKEN_API_KEY你的_TaoToken_Key node src/main.js在代码里发起一次会触发委派的请求// src/main.js import { createMainAgent } from /agents/main-assistant; const agent await createMainAgent(); const result await agent.invoke({ messages: [ { role: user, content: 帮我画一个 SubAgent 调用流程图然后检查一下我的 Node 版本是否满足要求 } ] }); console.log(result.messages.at(-1).content);这条请求同时涉及图表和环境排查预期主 Agent 会在单轮中调用两次call_agent分别委派给chart-agent和env-resolver-agent。4.2 观察路由日志在call_agent的func里加一行日志console.log([route] 委派给 ${agentName}, 任务: ${description.slice(0, 50)});预期输出类似[route] 委派给 chart-agent, 任务: 画一个 SubAgent 调用流程图 [route] 委派给 env-resolver-agent, 任务: 检查 Node 版本是否满足要求如果只看到一次委派说明主 Agent 把两个任务合并处理了需要检查models.router的 temperature 是否过高或者call_agent的 description 是否足够清晰。4.3 确认上下文隔离在call_agent返回前打印主 Agent 收到的消息条数const before messages.length; // ... 执行子 Agent const after messages.length; console.log([context] 主 Agent 消息数: ${before} - ${after});预期after - before等于 1即只增加一条 ToolMessage。如果子 Agent 内部的工具调用过程泄漏到主 Agent这个差值会明显大于 1。这正是 SubAgent 隔离带来的 Token 节省子 Agent 内部跑十几次工具调用主 Agent 只看到一条最终结果。4.4 用模型对话快速验证通道如果你在配置阶段想先确认 TaoToken 通道本身可用可以打开 模型对话 发一条测试消息。通道正常后再回到本地跑 Agent能排除掉鉴权类问题。5. 本篇常见错排查5.1 子 Agent 报鉴权失败现象主 Agent 正常委派后返回子 Agent 调用失败: 401。原因通常是子 Agent 动态 import 时环境变量未加载或者子 Agent 内部自己读了一个不存在的配置项。排查步骤在call_agent的func开头打印process.env.TAOTOKEN_API_KEY是否存在。如果为空检查启动命令是否在同一 shell 里 export。如果存在但仍 401检查config.toml里的base_url是否写成了https://taotoken.net/api不要多加路径后缀。5.2 主 Agent 不委派自己硬答现象请求里明确提到图表但主 Agent 没有调用call_agent直接输出了一段文字描述。原因有两个方向。一是call_agent的 description 没有说清楚子 Agent 的能力边界主 Agent 判断自己也能做。解决方法是把每个子 Agent 的 description 写具体比如「生成 mermaid 格式的流程图代码」比「负责图表」更有效。二是models.router的 temperature 偏高路由决策不稳定。把 temperature 降到 0.1 再试。5.3 循环依赖导致启动报错现象ReferenceError: Cannot access SUBAGENT_REGISTRY before initialization。这是静态导入顺序问题。确认子 Agent 注册表里用的是() import(...)而不是顶部import。动态 import 是惰性的只有call_agent被调用时才加载子 Agent 模块从而打破循环。5.4 子 Agent 返回内容被截断现象子 Agent 返回的文本不完整主 Agent 拿到的结果缺尾巴。检查config.toml里models.default的max_tokens。子 Agent 内部可能有多轮工具调用最终结果加上中间推理会消耗较多 token。如果max_tokens设得太小最终文本会被截断。建议子 Agent 用 4096 起步主 Agent 路由用 1024 即可。5.5 新增子 Agent 后主 Agent 不认识现象在注册表里加了新子 Agent但主 Agent 的call_agent枚举里没有它。原因是call_agent的schema.enum是在getSubagentTools调用时生成的。如果你在 Agent 创建之后才改注册表需要重启进程。另外确认新子 Agent 同时注册到了settings.json的subagent_registry和代码里的SUBAGENT_REGISTRY两处缺一不可。6. 把 Key 收敛到一处把职责拆到多个 AgentSubAgent 模式的价值不在于多了一层调用而在于职责隔离。主 Agent 不挂 Skill只做路由每个子 Agent 只挂自己的 Skills上下文互不污染子 Agent 内部的工具调用过程对主 Agent 不可见主 Agent 的对话历史保持干净。这套结构在 Skills 数量增长时优势会越来越明显。TaoToken 在这里承担的是统一 Key 与 API 通道的角色。主 Agent 和所有子 Agent 共用同一个base_url和api_key配置只写一份轮换只改一处。如果你准备把这套结构用到长期编码或 Agent 工作流里可以看一下 Coding Plan它更适合持续性的 Agent 调用场景。接入细节和参数说明在 接入文档 里Key 的创建和管理在 api-keys。最后留一个实操建议新增子 Agent 时先在settings.json里把skills数组写清楚再写 Agent 文件最后注册到SUBAGENT_REGISTRY。顺序反了容易出现「Agent 能跑但主 Agent 不委派」的情况因为call_agent的枚举依赖注册表。