1. 为什么主智能体需要 SubAgent：从上下文膨胀说起
如果你用 LangChain 的create_agent搭过一个稍微复杂点的任务流，大概率遇到过这种情况：任务跑到第五六步，模型开始"忘事"，前面明明已经查到的信息，它又绕回去重新查一遍；或者工具调用参数开始写错，把query和topic搞混。这不是模型不行，而是上下文被塞爆了。
DeepAgents 的 SubAgent 子智能体机制，本质上是给主智能体配了一支"外包团队"。主智能体只负责拆解任务、分派工作、汇总结果，具体执行细节全部丢给子智能体在自己的独立上下文里完成。子智能体跑完只把最终结论回传给主智能体，中间那些搜索原文、试错过程、冗余 token 全部隔离在外。
这套机制解决的核心问题是上下文隔离。举个实际场景：你要做一个"竞品分析报告"，主智能体需要先搜三家竞品的最新动态，再对比功能差异，最后写一份 800 字总结。如果全在一个上下文里跑，光是三次搜索返回的原始网页内容就能吃掉几千 token，等到写报告时模型已经"晕"了。而用 SubAgent，搜索子智能体各自消化原始内容，只回传提炼后的要点，主智能体的上下文始终清爽。
DeepAgents 在构建时会自动注入一个名为task的工具，主智能体通过调用它来派生子智能体。这里有个关键细节：子智能体的中间执行过程对主智能体完全不可见，只有最终结果会作为task工具的返回值传回。这意味着主智能体不需要知道子智能体用了什么工具、查了几次、中间报了什么错，它只关心"任务完成没有、结果是什么"。
适合用 SubAgent 的场景很明确：多步骤任务（避免上下文杂乱）、专业领域子任务（需要特定工具或提示词）、多模型混合（不同子任务用不同模型降本）、高层协调（主智能体专注规划而非执行）。反过来，简单单步任务、高度依赖中间细节的任务、成本极度敏感的场景，硬上 SubAgent 反而增加开销。
我试过在一个只需要单次搜索的任务里强行拆子智能体，结果主智能体多了一轮调度开销，总耗时反而涨了 30%。所以判断标准很简单：子任务之间是否需要上下文隔离，需要就拆，不需要就别拆。
另外有个容易踩的坑：任何 DeepAgents 对象创建后，内部默认已经配备了一个叫general_purpose的子智能体，它共享主智能体的模型、工具和系统提示词。这就是为什么有时候你没传subagents参数，它也能"自己调用子智能体"——其实是调用了这个默认的通用子智能体。这也意味着，你自定义的每个 SubAgent 的description字段必须写得足够清晰，否则主智能体可能绕过你的专用子智能体，直接找默认的通用子智能体干活，效果就打折了。
2. TaoToken 统一 Key 接入：一次配置跑通主从智能体
DeepAgents 的主从架构里，主智能体和每个子智能体都可能调用模型。如果每个子智能体单独配一套 API Key 和 Base URL，配置会变得非常散乱，尤其是当你想给不同子智能体分配不同模型（比如搜索子智能体用便宜模型、报告子智能体用强模型）时，Key 管理就成了负担。
TaoToken 的思路是提供一个统一的 API 入口，主智能体和所有子智能体共用同一个 Base URL 和 Key，通过model参数区分具体调用哪个模型。这样你只需要在环境变量里维护一份凭证，所有智能体自动继承。
接入前你需要准备两样东西：一个 TaoToken 的 API Key，以及确认你要用的模型 ID。Key 可以在控制台的 API Keys 页面创建，模型 ID 在模型对话页面能看到当前可用的列表。接入文档里有完整的参数说明，建议先扫一遍再动手。
配置方式推荐用.env文件管理，避免 Key 硬编码在代码里。在项目根目录建一个.env：
TAOTOKEN_API_KEY=sk-你的实际key TAOTOKEN_BASE_URL=https://taotoken.net/api然后在 Python 代码里通过load_dotenv()加载。这里要注意一个细节：LangChain 的ChatOpenAI或ChatDeepSeek这类模型类，通常接受base_url和api_key两个参数。TaoToken 的 API 地址是https://taotoken.net/api，注意末尾不要多加/v1，具体路径以接入文档为准。
如果你用的是ChatOpenAI兼容接口，配置大概长这样：
import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI load_dotenv() model = ChatOpenAI( model="deepseek-chat", api_key=os.getenv("TAOTOKEN_API_KEY"), base_url=os.getenv("TAOTOKEN_BASE_URL"), temperature=0, )这段配置的关键在于base_url指向 TaoToken 的统一入口，api_key用同一份 Key。主智能体和子智能体都复用这个model对象，或者基于它派生不同参数的实例。
对于需要给子智能体单独指定模型的场景，比如搜索子智能体用轻量模型、总结子智能体用强模型，可以这样写：
search_model = ChatOpenAI( model="deepseek-chat", api_key=os.getenv("TAOTOKEN_API_KEY"), base_url=os.getenv("TAOTOKEN_BASE_URL"), ) summary_model = ChatOpenAI( model="deepseek-reasoner", api_key=os.getenv("TAOTOKEN_API_KEY"), base_url=os.getenv("TAOTOKEN_BASE_URL"), )两个模型实例共用同一份 Key 和 Base URL，只是model字段不同。这样在 SubAgent 配置里，搜索子智能体挂search_model，总结子智能体挂summary_model，成本和质量都能兼顾。
有个实际经验：TaoToken 的 Key 权限是全局的，如果你在多个项目里共用同一个 Key，建议在控制台给不同项目建不同的 Key，方便后续排查用量和吊销。另外 Base URL 一定要写对，我见过有人写成https://taotoken.net/api/v1导致 404，因为 LangChain 的某些模型类会自动拼接路径，多一层/v1就重复了。拿不准的时候，先用模型对话页面确认接口能通，再往代码里搬。
3. 可复制的 SubAgent 配置片段：字典式与编译式
DeepAgents 提供两种创建子智能体的方式，对应不同复杂度需求。第一种是字典配置，适合快速原型；第二种是编译式，适合已有create_agent对象的复用场景。
先看字典式。核心字段有四个：name（子智能体名字，主智能体调度时用）、description（主智能体据此判断该派谁干活，这个字段最重要）、system_prompt（子智能体的角色设定）、tools（该子智能体可用的工具列表）。可选字段包括model（单独指定模型）、middleware（中间件）、interrupt_on（人在回路）。
from deepagents import create_deep_agent from langchain_core.tools import tool from langchain_openai import ChatOpenAI import os from dotenv import load_dotenv load_dotenv() model = ChatOpenAI( model="deepseek-chat", api_key=os.getenv("TAOTOKEN_API_KEY"), base_url=os.getenv("TAOTOKEN_BASE_URL"), ) @tool def internet_search(query: str, max_results: int = 5) -> str: """执行互联网搜索，返回与 query 相关的摘要信息。""" # 这里替换成你实际的搜索实现 return f"模拟搜索：{query} 的前 {max_results} 条结果" research_subagent = { "name": "research-agent", "description": "用于深度搜索网络信息，当需要获取实时或外部资料时调用", "system_prompt": "你是一个网络搜索专家，负责调用搜索工具获取关键信息并提炼要点", "tools": [internet_search], "model": model, } agent = create_deep_agent( model=model, subagents=[research_subagent], )这段配置里，description写的是"当需要获取实时或外部资料时调用"，主智能体看到这个描述就知道什么时候该派它。如果你写成"搜索工具"，主智能体可能理解不到位，在不需要搜索的时候也乱调。
再看编译式。如果你已经用create_agent建好了智能体对象，想直接复用为子智能体，用CompiledSubAgent包装：
from deepagents import create_deep_agent, CompiledSubAgent from langchain.agents import create_agent summary_agent = create_agent( model=model, system_prompt="你负责根据提供的资料撰写 500 字以内的短篇报告", ) summary_subagent = CompiledSubAgent( name="summary-agent", description="用来根据搜索信息或新闻资料编写短篇报告，500字以内", runnable=summary_agent, ) agent = create_deep_agent( model=model, subagents=[research_subagent, summary_subagent], )编译式的好处是能复用已有的create_agent配置，包括回调、检查点等高级功能。注意CompiledSubAgent的runnable参数接收的是编译后的 agent 对象，不是字典。
两种方式可以混用，就像上面这段代码，research_subagent是字典式，summary_subagent是编译式，一起传给create_deep_agent完全没问题。
配置时有个细节值得强调：每个子智能体的description要写得像"岗位说明书"，说清楚什么时候该找它，而不只是"它能做什么"。主智能体是靠这个字段做路由决策的，描述模糊会导致调度错误。我踩过的坑是把两个子智能体的 description 写得太像，结果主智能体经常派错人，后来把职责边界写清楚才解决。
4. 一轮任务分派验证：确认调用链按预期执行
配置写完后，必须跑一轮实际任务来验证子智能体调用链是否符合预期。验证的核心是观察主智能体是否按你设计的路径派发任务，以及子智能体是否只回传了最终结果。
先准备一个需要多步协作的任务，比如"搜索某技术的最新进展，并写一份 300 字摘要"。这个任务天然需要两个子智能体：一个负责搜索，一个负责总结。
query = "搜索 LangChain DeepAgents 的最新进展，并写一份 300 字以内的摘要" for event in agent.stream( {"messages": [{"role": "user", "content": query}]}, stream_mode="values", ): messages = event.get("messages", []) if messages: last = messages[-1] print(f"[{last.__class__.__name__}] {last.content[:200]}")运行后，你应该在输出里看到这样的调用链：主智能体先输出一段规划文本，然后调用task工具，参数里指定subagent_type为research-agent；搜索子智能体执行完毕后，主智能体再次调用task，这次指定summary-agent；最后主智能体汇总两个子智能体的结果，输出最终回答。
验证时重点看三个地方。第一，task工具的调用参数里subagent_type是否匹配你定义的name。如果看到general_purpose，说明主智能体没找到合适的专用子智能体，大概率是description写得不够明确。第二，子智能体的中间消息是否出现在主流里。正常情况下，你只能看到子智能体的最终返回，看不到它内部的工具调用细节。如果看到了，说明上下文隔离没生效，需要检查配置。第三，最终回答是否基于子智能体的返回结果。如果主智能体自己编了内容，说明它没正确使用task的返回值。
如果想更精细地观察，可以在stream时打印完整的消息结构：
for event in agent.stream( {"messages": [{"role": "user", "content": query}]}, stream_mode="values", ): for msg in event.get("messages", []): if hasattr(msg, "tool_calls") and msg.tool_calls: for tc in msg.tool_calls: print(f"工具调用: {tc['name']}, 参数: {tc['args']}")这样能看到每次task调用的具体参数，确认subagent_type和description是否按预期传递。
验证通过的标准是：主智能体按你设计的顺序派发任务，每个子智能体只被调用一次（除非任务确实需要多次），最终回答质量符合预期。如果发现主智能体跳过了某个子智能体，或者反复调用同一个，先检查description的清晰度，再检查任务描述是否本身就有歧义。
5. 常见报错排查：401、local proxy failed 与 choices 解析失败
接入 TaoToken 跑 DeepAgents 时，有几类报错出现频率最高，这里逐个拆解。
401 Unauthorized。这个最直接，Key 不对或没传进去。先确认.env文件里的TAOTOKEN_API_KEY没有多余空格或引号，然后确认代码里load_dotenv()在读取环境变量之前执行。如果用的是ChatOpenAI，检查api_key参数是否真的传了值，可以临时print(os.getenv("TAOTOKEN_API_KEY")[:8])看前几位。还有一种情况是 Key 被吊销或额度用完，去控制台确认一下 Key 状态。
local proxy failed / connection error。这个报错通常和 Base URL 有关。TaoToken 的 API 地址是https://taotoken.net/api，注意不要写成http，也不要多加路径。如果你在公司网络环境下，检查是否有本地代理拦截了请求。另外确认base_url参数名是否正确，ChatOpenAI用的是base_url，有些旧版本用openai_api_base，参数名写错会静默忽略，然后走默认的 OpenAI 地址，自然连不上。
reading choices / response parsing error。这个报错说明请求发出去了，但返回结构不符合预期。常见原因是模型 ID 写错，比如把deepseek-chat写成deepseek_chat，或者用了 TaoToken 不支持的模型名。去模型对话页面确认当前可用的模型 ID，然后检查代码里的model字段。还有一种可能是流式输出配置和模型不兼容，如果用了stream=True但模型不支持，也会解析失败，可以先关掉流式测试。
OAuth / authentication 相关报错。如果你用的是 Claude Code 或 Codex 这类工具接入，报错信息里可能出现 OAuth 字样。这类工具通常需要配置三件套：Base URL、API Key、Model ID。以 Claude Code 为例，配置文件里需要同时写对这三项，缺一个都会报认证失败。Codex 的auth.json里同样要填全，Base URL 指向 TaoToken 的 API 地址，Key 用 TaoToken 的 Key，Model ID 填你要用的模型。Cline 的 MCP 配置也是同理，三件套缺一不可。
排查时有个通用方法：先用模型对话页面发一条最简单的消息，确认 Key 和模型本身没问题，再回到代码里排查配置。这样能把问题范围缩小到"是凭证问题还是代码问题"。
6. 从单机到协作：SubAgent 的工程化落地建议
跑通基础流程后，有几个工程化细节值得提前考虑。
第一，子智能体的粒度控制。不要为了拆而拆，一个子智能体最好对应一个明确的职责边界。比如"搜索"和"总结"是两个天然独立的职责，适合拆；但"搜索新闻"和"搜索论文"如果用的是同一个工具、同一套提示词，就没必要拆成两个，合并成一个"搜索子智能体"即可。粒度太细会导致主智能体调度开销增加，粒度太粗又失去了上下文隔离的意义。
第二，description的写法要统一风格。建议用"当……时调用"的句式，明确触发条件。比如"当需要获取实时网络信息时调用"比"网络搜索工具"更利于主智能体做路由决策。多个子智能体的 description 之间要有明显的区分度，避免语义重叠。
第三，模型分配策略。主智能体负责规划和调度，对推理能力要求高，建议用强模型；搜索子智能体主要是调用工具和提炼信息，可以用轻量模型降本；总结子智能体对语言组织能力要求高，可以用强模型。通过 TaoToken 统一 Key 接入后，切换模型只需要改model字段，不用动 Key 和 Base URL，调整成本很低。
第四，验证环节要固化。每次修改子智能体配置后，跑一轮标准验证任务，观察调用链是否符合预期。可以把验证脚本单独存一个文件，改完配置就跑一遍，避免配置漂移导致线上行为异常。
第五，注意默认子智能体的干扰。general_purpose子智能体始终存在，如果你的专用子智能体 description 不够清晰，主智能体可能绕过它去找默认的。一个实用技巧是：在系统提示词里明确告诉主智能体"优先使用已定义的专用子智能体"，减少误路由。
如果你打算长期跑编码类或 Agent 类任务，Coding Plan 的额度模型比按次调用更适合高频场景，可以去了解一下。需要先拿到 Key 的话，API Keys 页面创建即可，接入文档里有各语言的最小示例，照着改 Base URL 和 Key 就能跑通。模型对话页面可以快速验证某个模型 ID 是否可用，省得在代码里反复试错。
