1. 为什么你的 Multi-Agent 跑着跑着就“变傻”了如果你最近在用 LangChain 搭 Multi-Agent大概率遇到过这种场景主 Agent 一开始思路清晰任务拆得明明白白可当它连续调用十几次工具之后回答开始重复、逻辑开始打结甚至把已经查到的结论又推翻重查一遍。这不是模型不行而是上下文被中间结果塞满了。LangChain 团队推出的 DeepAgents 框架正是冲着这个痛点来的。它用两个核心原语把 Multi-Agent 的工程复杂度压了下来subagents子智能体负责上下文隔离skills技能负责能力的渐进式披露。前者让主 Agent 只看到结论、看不到过程后者让 Agent 启动时只加载技能名和描述真正需要时才读完整指令。这篇文章面向的是已经会写基础 LangChain Agent、想进一步落地 Multi-Agent 协作链路的开发者。我会给出可复制的config.toml骨架、subagents 拆分思路、skills 挂载方式以及用 TaoToken 统一 Key 接入的完整示例最后附上本地运行验证步骤。跟着做你能在半小时内跑通一条多智能体协作链路。2. 前置准备环境、依赖与 TaoToken 统一 Key2.1 安装依赖DeepAgents 目前通过 LangChain 生态的扩展包提供建议用独立虚拟环境避免和现有项目依赖打架。python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate pip install -U langchain deepagents langgraph pip install -U langchain-openai如果你打算让 subagent 调用不同厂商的模型langchain-openai这一层可以统一走兼容接口后面会讲怎么配。2.2 为什么用 TaoToken 统一 KeyMulti-Agent 最烦的一点是主 Agent 用一个模型研究 subagent 用另一个代码 subagent 又想换一个。每个厂商一套 Key、一套计费、一套限流管理成本直接翻倍。TaoToken 的思路是把这些模型的调用收敛到一个入口你只需要维护一份 Key在config.toml里按 subagent 指定不同模型名即可。对 Multi-Agent 这种“一个主 Agent 带 N 个 subagent”的结构特别友好不用在每个 subagent 里重复写鉴权逻辑。先拿到你的 Key访问 TaoToken API Keys 管理页 创建然后写进环境变量别硬编码进代码。export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api注意base_url用https://taotoken.net/api不要带任何查询参数否则部分 SDK 会拼接出错误路径。2.3 目录结构先定好DeepAgents 的 skills 依赖目录约定建议一开始就把结构摆清楚后面加技能不用改代码。my-deepagent/ ├── config.toml ├── main.py ├── skills/ │ ├── deploy/ │ │ └── SKILL.md │ └── research/ │ └── SKILL.md └── tools/ └── custom_tools.py3. 可复制配置config.toml 骨架与 subagents 拆分3.1 config.toml 完整骨架下面这份配置是我实测下来比较稳的结构主 Agent 和 subagent 的模型、工具、技能都在这里声明代码里只负责读取。[main] name orchestrator model gpt-4o system_prompt 你是主协调智能体。你的职责是拆解任务并委托给合适的 subagent。 不要自己执行多步骤的搜索或代码探索直接委托。 [main.skills] dir ./skills [[subagents]] name research-agent description 深度研究问题并综合发现适合需要多次检索的任务 model gpt-4o-mini system_prompt 你是研究员。使用检索工具收集信息输出结构化摘要 每条结论必须附来源总长度控制在 300 字以内。 tools [internet_search] [[subagents]] name code-agent description 探索代码库、定位实现细节并给出修改建议 model gpt-4o system_prompt 你是代码分析专家。只读不写输出文件路径、行号和修改建议。 tools [read_file, list_dir] [llm] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY几个关键点description是主 Agent 决定调用哪个 subagent 的唯一依据必须写清楚“做什么”而不是“是什么”。tools只给真正需要的给 code-agent 塞internet_search只会增加它的决策负担。3.2 subagents 拆分的三条原则拆分粒度是 Multi-Agent 最容易翻车的地方。我踩过的坑是一开始按“功能”拆结果每个 subagent 都要调一堆工具上下文照样爆。后来改成按“上下文边界”拆效果好很多。第一条按上下文隔离需求拆。凡是会产生大量中间结果的任务代码库探索、多轮检索、日志分析单独拆一个 subagent主 Agent 只收结论。第二条按模型成本拆。简单检索用gpt-4o-mini复杂推理用gpt-4o在config.toml里按 subagent 指定成本能降一大截。第三条按工具集拆。一个 subagent 的工具不超过 5 个超过就说明它职责太杂该继续拆。3.3 加载配置的代码import os import tomllib from langchain_openai import ChatOpenAI from deepagents import create_deep_agent with open(config.toml, rb) as f: cfg tomllib.load(f) def build_llm(model_name: str) - ChatOpenAI: return ChatOpenAI( modelmodel_name, base_urlcfg[llm][base_url], api_keyos.environ[cfg[llm][api_key_env]], temperature0, ) subagents [ { name: s[name], description: s[description], system_prompt: s[system_prompt], tools: s.get(tools, []), model: build_llm(s[model]), } for s in cfg.get(subagents, []) ] agent create_deep_agent( modelbuild_llm(cfg[main][model]), system_promptcfg[main][system_prompt], subagentssubagents, skills_dircfg[main][skills][dir], )这段代码把配置和逻辑彻底分开加一个 subagent 只需要改config.toml不用动 Python。4. skills 挂载渐进式披露怎么写才生效4.1 SKILL.md 的标准结构skills 用的是 agentskills.io 规范核心就是 YAML 元数据加 Markdown 正文。元数据里的name和description会被预加载进上下文正文只在 Agent 决定使用时才读取。--- name: deploy description: 部署应用到生产环境包含测试、构建、发布和健康检查 version: 1.0.0 --- # 部署到生产环境 当用户要求部署时严格按以下步骤执行 1. 运行测试npm test 2. 构建应用npm run build 3. 发布到生产npm run deploy:prod 4. 验证部署请求 /healthz确认返回 200 如果任一步骤失败停止后续步骤并报告错误输出。description要写成“什么场景下用”而不是“这个技能是什么”。主 Agent 靠它判断是否加载写得太泛会导致该用的时候不用、不该用的时候乱用。4.2 skills 和 subagents 怎么配合这两者不是二选一。我的做法是skills 定义流程subagents 执行流程。比如 deploy 这个 skill 描述的是部署步骤而真正执行部署的可以是一个专门的 deploy-agent它挂载这个 skill 来管理自己的上下文。在config.toml里给 subagent 也挂 skills 目录[[subagents]] name deploy-agent description 执行部署流程按标准步骤发布并验证 model gpt-4o-mini system_prompt 你是部署执行者严格按 skill 指令操作。 tools [run_shell] skills_dir ./skills这样 deploy-agent 启动时只看到deploy这个技能名和描述真正执行时才读完整步骤token 占用极低。4.3 技能数量多了怎么办当你有几十个技能时预加载的描述本身也会占上下文。这时候可以按领域分目录主 Agent 只挂载当前任务相关的子目录。比如skills/research/、skills/deploy/、skills/data/在配置里按需指定而不是一股脑全挂上。5. 验证请求跑通第一条多智能体协作链路5.1 写一个最小验证脚本# main.py from langchain_core.messages import HumanMessage result agent.invoke({ messages: [ HumanMessage(content帮我调研一下 DeepAgents 的 subagents 机制给出三条要点) ] }) for msg in result[messages]: print(f[{msg.type}] {msg.content}\n)运行python main.py5.2 预期输出长什么样正常跑通的话你会看到主 Agent 先输出一段“我将委托 research-agent 处理”然后 research-agent 在独立上下文里完成检索最后主 Agent 汇总出三条要点。关键观察点是主 Agent 的消息历史里不应该出现 research-agent 的中间检索结果只有最终摘要。如果主 Agent 自己开始调internet_search说明description没写清楚或者主 Agent 的 system_prompt 没有强调“不要自己执行多步骤任务”。5.3 用模型对话快速验证 Key 是否通在跑完整链路之前建议先用 TaoToken 模型对话 发一条消息确认 Key 和 base_url 配置正确。这一步能帮你排除掉 80% 的“跑不通其实是鉴权问题”。6. 本篇常见错排查6.1 报错KeyError: TAOTOKEN_API_KEY环境变量没导出或者导出在了另一个终端会话。检查echo $TAOTOKEN_API_KEY是否有输出。在 IDE 里运行时注意 IDE 可能不继承 shell 的环境变量需要在运行配置里单独设置。6.2 subagent 从不被调用九成是description写得太模糊。主 Agent 判断是否委托靠的是语义匹配。把“做金融相关的事情”改成“分析财务数据并生成带置信度评分的投资洞察”命中率立刻上来。另外确认主 Agent 的 system_prompt 里明确写了“委托给 subagent”。6.3 skills 不生效先检查目录结构skills/skill-name/SKILL.md文件名必须是大写SKILL.md小写不认。再检查 YAML 头部的---是否闭合少一个---整个文件会被当成普通文本。6.4 上下文还是爆说明 subagent 的system_prompt没有限制输出长度。在 subagent 的提示里明确写“输出控制在 300 字以内”“只返回结论不返回过程”。上下文隔离的前提是 subagent 自己也要克制。6.5 模型返回 404 或路径错误base_url写成了https://taotoken.net/api/多了斜杠或带了查询参数。统一用https://taotoken.net/apiSDK 会自己拼接/v1/chat/completions。7. 下一步把链路接到真实工程里跑通最小链路之后接下来通常是两件事一是把 subagents 扩展到真实业务比如加一个data-agent专门查数据库、一个report-agent专门生成报告二是把这条链路接进 CI 或定时任务。如果你打算长期跑编码类或 Agent 类任务建议了解一下 TaoToken Coding Plan它针对高频调用场景做了额度优化比按次计费更适合 Multi-Agent 这种一次任务触发多次模型调用的结构。接入细节和参数说明可以查 TaoToken 接入文档里面有各语言 SDK 的完整示例。控制台在 TaoToken Console可以实时看每个 subagent 的调用量和 token 消耗方便你判断哪个 subagent 该换小模型。最后提醒一句主 Agent 的上下文是稀缺资源像管理内存一样管理它。subagents 做隔离skills 做披露两者组合起来Multi-Agent 才真正跑得稳。