DeepAgents 实战：SubAgentMiddleware 驱动 Sub-Agent 协同演化的 Harness 拆解与 TaoToken 接入-北京尧图网络

1. 从一次差旅编排说起SubAgentMiddleware 到底解决什么问题如果你用 LangChain 写过稍微复杂一点的 Agent大概率遇到过这种场景主 Agent 一边要查日历、一边要订机票、一边还要订酒店工具调用日志刷满屏幕上下文窗口被中间结果塞爆最后模型开始胡言乱语。这不是模型不行而是上下文被污染了。DeepAgents 给出的解法是 SubAgentMiddleware它把细节工作隔离到独立的 Sub-Agent 里执行主 Agent 只接收最终结果。你可以把它理解成一个项目经理——项目经理不需要亲自去查每个航班的舱位他只需要把任务派给出行专员和住宿专员等他们交回一份简报即可。SubAgentMiddleware 是 LangChain DeepAgents 框架里的一个中间件它能做什么简单说三件事注册多个 Sub-Agent、自动生成一个名为task的工具、在模型调用前后注入系统提示词。适合谁适合正在做多 Agent 协同、想让主 Agent 保持高层协调视角、又不想被工具调用细节淹没的开发者。我试过把差旅助手拆成三个角色后主 Agent 的上下文长度从 8000 token 降到 2000 以内响应速度肉眼可见地变快。这篇就带你从 Harness 视角拆解 SubAgentMiddleware 的调度链路给出可复制的配置片段并把 endpoint 切到 TaoToken 统一通道做连通性验证。2. TaoToken 前置准备统一 Key 与 API 通道在动手写 SubAgentMiddleware 之前先把模型通道理顺。DeepAgents 里每个 Sub-Agent 都可以指定自己的 model如果每个都去配不同的 Key维护成本会很高。TaoToken 提供统一的 API 通道一个 Key 就能覆盖多个模型特别适合这种主 Agent 多个 Sub-Agent的架构。你需要准备三样东西Base URL、API Key、Model ID。Base URL 用https://taotoken.net/apiAPI Key 到控制台创建Model ID 按你实际要用的模型填。这三件套在后面的配置里会反复出现建议先记下来。创建 Key 的入口在控制台的 API Keys 页面创建后复制保存页面关闭后就看不到了。如果你用的是 Claude Code 这类工具TaoToken 也提供了对应的接入文档配置方式类似都是把 Base URL 指向统一通道。这里有个容易踩的坑很多人以为 Sub-Agent 必须用和主 Agent 一样的模型。其实不是。SubAgentMiddleware 允许每个 Sub-Agent 单独指定 model你可以让主 Agent 用推理能力强的模型做协调让 Sub-Agent 用更经济的模型做执行。TaoToken 的统一通道正好支持这种混搭不用为每个模型单独申请 Key。配置环境变量时建议用.env文件管理避免把 Key 硬编码进代码。下面是一个最小化的.env示例TAOTOKEN_API_KEYsk-你的key TAOTOKEN_BASE_URLhttps://taotoken.net/api然后在代码里通过load_dotenv()加载。这样做的另一个好处是切换环境时只改.env不用动业务代码。3. 可复制配置SubAgentMiddleware 注册与协同触发现在进入核心部分。SubAgentMiddleware 的配置分两步先定义 Sub-Agent再把它们注册进中间件。Sub-Agent 有两种形式CompiledSubAgent和SubAgent前者是已经编译好的 Runnable后者是配置字典运行时才组装。先看完整的配置片段。这段代码可以直接复制运行注意把 model 换成你 TaoToken 通道里可用的 Model IDfrom typing import TypedDict from langchain.agents import create_agent from langchain.tools import tool from deepagents.middleware import CompiledSubAgent, SubAgentMiddleware, SubAgent from langchain_openai import ChatOpenAI from deepagents.backends import FilesystemBackend from dotenv import load_dotenv from datetime import datetime, date load_dotenv() class Event(TypedDict): title: str description: str start_time: datetime end_time: datetime tool def book_hotel(city: str, check_in_date: str, check_out_date: str): 酒店预订工具提供城市、入住日期和退房日期返回预订信息 return fHotel booked in {city} from {check_in_date} to {check_out_date} tool def buy_air_ticket(origin: str, destination: str, departure_date: str): 机票购买工具提供出发地、目的地和出发日期返回购买信息 return fFlight ticket bought from {origin} to {destination} on {departure_date} tool def check_calendar(date: date) - list[Event]: 日程查询工具提供日期返回该日期的日程信息 if date datetime.now().date(): return [ Event( title团队会议, description与团队成员讨论项目进展, start_timedatetime.strptime(f{date} 10:00, %Y-%m-%d %H:%M), end_timedatetime.strptime(f{date} 11:00, %Y-%m-%d %H:%M), ), ] return [] transport_agent create_agent( modelChatOpenAI( modelgpt-5.2-chat, base_urlhttps://taotoken.net/api, api_keysk-你的key, ), tools[buy_air_ticket], system_prompt( 你是一个专注于出行安排的个人助手可以帮助用户调用buy_air_ticket工具购买机票。达成购买机票的目标是首要任务你可以自行决定航司、航班和舱位等级。将购买信息以清晰的格式返回给用户。 ), ) transport_agent CompiledSubAgent( nametransport_agent, description一个专注于出行安排的个人助手负责处理与机票购买相关的安排。, runnabletransport_agent, ) accommodation_agent: SubAgent { name: accommodation_agent, description: 一个专注于住宿安排的个人助手负责处理与酒店预订相关的安排。, system_prompt: ( 你是一个专注于住宿安排的个人助手可以帮助用户调用book_hotel工具预订酒店。达成预订酒店的目标是首要任务你可以自行决定酒店、房型和价格等级。将预订信息以清晰的格式返回给用户。 ), model: ChatOpenAI( modelgpt-5.2-chat, base_urlhttps://taotoken.net/api, api_keysk-你的key, ), tools: [book_hotel], } middleware SubAgentMiddleware( backendFilesystemBackend(root_dir./agent_data, virtual_modeTrue), subagents[transport_agent, accommodation_agent], ) agent create_agent( modelChatOpenAI( modelgpt-5.2-chat, base_urlhttps://taotoken.net/api, api_keysk-你的key, ), tools[check_calendar], system_prompt( 你是一个差旅助手可以帮助用户安排差旅计划。你可以调用check_calendar工具查询用户的日程安排以便更好地规划差旅计划。如果没有日程安排冲突你可以直接调用注册工具购买机票和预订酒店。 ), middleware[middleware], )这段配置里有几个关键点值得展开。第一backend参数强烈建议指定。如果不指定中间件会走旧版 API必须用default_model指定默认模型而且 Sub-Agent 之间无法共享文件系统。指定FilesystemBackend后主 Agent 和 Sub-Agent 在同一个文件平面上工作Sub-Agent 写出的报告主 Agent 能直接读到。第二CompiledSubAgent和SubAgent的区别。前者适合你已经用create_agent编译好的 Agent直接包一层就能注册后者适合用字典描述配置运行时才组装。两种可以混用上面的例子就是混用的。第三每个 Sub-Agent 的description字段很重要。SubAgentMiddleware 会把所有 Sub-Agent 的名称和描述拼进task工具的描述里主 Agent 靠这段描述来决定派哪个 Sub-Agent。描述写得越清楚调度越准确。如果你用 Cline 或 Claude Code 这类工具做开发配置逻辑是一样的都是 Base URL Key Model ID 三件套。Cline 的 MCP 配置里也是把 endpoint 指向统一通道然后按需切换模型。4. 验证请求从 task 工具到协同触发配置写完后怎么确认 SubAgentMiddleware 真的生效了最直接的办法是打印它生成的task工具看看描述里有没有你的 Sub-Agent 列表。tools middleware.tools for tool in tools: print(fname: {tool.name}) print(fresponse_format: {tool.response_format}) print(args:) for k, v in tool.args.items(): print(f {k}: type: {v[type]}, title: {v[title]}) print(description:\n, tool.description)运行后会看到工具名为taskresponse_format为content参数有两个description任务描述和subagent_typeSub-Agent 类型。描述里会列出所有可用的 Sub-Agent比如transport_agent和accommodation_agent。接下来跑一次真实的协同触发result agent.invoke({ messages: [{ role: user, content: 明天两天有一个从上海到北京的差旅计划请帮购买往返机票明天出发后天返回和预订酒店入住明天退房后天。 }] }) print(result[messages][-1].content)如果一切正常主 Agent 会先调用check_calendar查日程确认没有冲突后并行启动两个task调用分别派给transport_agent和accommodation_agent。两个 Sub-Agent 各自执行工具调用返回结果主 Agent 汇总后输出一份完整的差旅行程。这里有个细节Sub-Agent 的执行过程对主 Agent 是不可见的。主 Agent 只看到task工具返回的最终结果中间的工具调用日志不会进入主 Agent 的上下文。这正是 SubAgentMiddleware 的核心价值——上下文隔离。验证连通性时如果模型通道有问题通常会在这一步暴露。比如 Key 无效会报 401Base URL 写错会报连接失败。确认 TaoToken 通道正常后整个链路就通了。5. 常见报错排查401、local proxy failed 与 OAuth实际跑的时候报错基本集中在几个地方。下面按真实报错对照排查。401 Unauthorized最常见。检查.env里的TAOTOKEN_API_KEY是否正确有没有多余空格。如果用的是ChatOpenAI确认api_key参数传对了。还有一种情况是 Key 过期或被删除到控制台重新创建一个即可。local proxy failed / connection refused通常是 Base URL 写错。确认是https://taotoken.net/api不要漏掉/api后缀也不要写成http。如果你在容器里跑检查网络是否能访问外网。reading choices of undefined这个报错说明请求发出去了但返回结构不对。多半是 Model ID 填错了或者该模型不在你的通道权限内。到模型对话页面确认一下可用的 Model ID换成能用的再试。OAuth 相关报错如果你用 Claude Code 接入可能会遇到 OAuth 流程问题。这种情况建议直接用 API Key 方式接入配置更简单。Claude Code 的接入文档里有详细步骤核心还是 Base URL Key Model ID。Sub-Agent 没有被调用如果主 Agent 一直自己干活不派task检查 Sub-Agent 的description是否足够清晰。描述太模糊主 Agent 不知道什么时候该派。另外如果任务本身很简单主 Agent 可能判断不需要 Sub-Agent这是正常行为。文件写入后主 Agent 读不到确认backend参数指定了FilesystemBackend并且root_dir路径存在。如果没指定 backendSub-Agent 用的是私有 StateBackend写出的文件主 Agent 看不到。排查时建议先单独测模型通道确认ChatOpenAI能正常返回再测 SubAgentMiddleware。分层排查比一上来就查中间件效率高得多。6. 把通道固定下来长期编码与 Agent 协同的接入建议跑通一次不难难的是长期稳定。我的建议是把模型通道固定成一套配置主 Agent 和 Sub-Agent 都走同一个 Base URLKey 统一管理。这样切换模型时只改 Model ID不用动其他代码。如果你要做长期的编码类 Agent或者多 Agent 协同的项目可以考虑用 Coding Plan 来管理额度避免频繁切换 Key。模型对话页面适合做单次验证确认某个 Model ID 是否可用。接入文档里有各种工具的配置示例遇到不确定的配置项可以先查文档。最后留一个实用技巧Sub-Agent 的description建议写成什么时候用我而不是我是什么。比如当需要购买机票时使用比机票助手更能触发主 Agent 的调度。这个细节在多 Sub-Agent 场景下尤其明显描述写得好调度准确率能提升不少。

DeepAgents 实战：SubAgentMiddleware 驱动 Sub-Agent 协同演化的 Harness 拆解与 TaoToken 接入

相关推荐

Elastic-Job-Lite作业分片策略源码解析与调优实战

如何快速把 Windows 11 任务栏与开始菜单改回 Windows 10 经典界面：ExplorerPatcher 完整实战指南

T型三电平逆变器与VSG自适应控制仿真实践

更多资讯

Command 浏览器扩展完全解析：Slack 风格斜杠命令如何让任何网页秒变生产力神器

系列总结：vLLM-2080Ti-Definitive 0.2.x 版本演进路线图与社区资源完整指南

手机远程操控 AI Agent：从架构设计到移动端落地实践

华为沃土数字平台四层解耦架构与集成实践指南

原生HTML+CSS+JS实现高可用Banner轮播图

MMPose Webcam API 快速上手：基于 ViTPose 构建摄像头实时姿态估计交互应用

今日更新

防关联浏览器哪个好？三款产品实测差异解析

2026钢铁行业AI转型系统选型对比：多基地排产、大宗原燃料采购与质量追溯，六家厂商能力差异在哪里

影刀RPA深度实战：大模型Fine-tuning定制RPA专用Prompt与指令生成

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？