DeepAgents框架架构03：Sub-Agent委派系统

Sub-Agent委派系统从task工具到舱壁隔离的多Agent可治理设计多Agent协作的本质不是增加人手而是明确职责边界、隔离执行域、标准化协作流程。边界模糊的多Agent系统规模越大越混乱。一、传统多Agent架构的四大致命缺陷一个看起来很聪明的多Agent Demo主Agent负责搜索、读文件、写代码、整理计划、跑测试、做审稿。演示效果不错。但一到真实任务问题立刻暴露缺陷一上下文污染Context Bloat主Agent需承载规划、工具调用、子任务结果等全量信息。搜索带回几万字材料、文件读取返回大段代码——这些中间结果快速耗尽上下文窗口关键信息淹没、推理漂移、Token成本激增。缺陷二职责边界模糊主Agent同时承担决策指挥与任务执行双重角色。路由逻辑与业务逻辑高度耦合主循环代码越来越臃肿迭代风险极高——没人敢改因为改了不知道哪里会炸。缺陷三故障无隔离Single Point of Failure子Agent执行报错、工具调用异常、输出格式错误时错误直接扩散至主Agent状态。一个子任务崩了主线程跟着迷路。缺陷四调度不可控子Agent生命周期、并发数、执行状态无统一管理。容易出现无限派生子Agent递归创建孙Agent、资源耗尽、任务追踪困难。核心根因主Agent又当指挥又干杂活。多Agent协作的本质不是堆更多Agent而是明确职责边界、隔离执行域、标准化协作流程。改造为DeepAgents星型委派task工具task工具task工具ToolMessageToolMessageToolMessage主Agent只决策与委派Sub-Agent A隔离执行Sub-Agent B隔离执行Sub-Agent C隔离执行传统模式网状直连互相污染级联嵌套主Agent决策执行混在一起子Agent A子Agent B子Agent C二、DeepAgents的核心对策主Agent只决策子Agent只执行DeepAgents摒弃Agent间自由通信的网状模式采用“Sub Agent委派 工具化封装 中间件接管 状态隔离”的极简架构主Agent决策与委派task工具唯一委派通道Sub-Agent A隔离执行Sub-Agent B隔离执行通用Sub-Agent兜底ToolMessage干净结果ToolMessage干净结果ToolMessage干净结果三条铁律主Agent不直接操作子图只通过task工具委派子Agent不能把内部消息、待办、技能元数据一股脑塞回主Agent子Agent之间不直接通信所有协作通过主Agent中转这就是整个架构的核心思想主Agent只做决策与委派子Agent只做隔离执行与结果交付多Agent协作收敛为一套可治理的委派系统而非无规则的聊天网络。三、子Agent是什么被裁剪过的独立执行单元先把概念说清楚。子Agent不是主Agent的缩小版也不是一个带独立Prompt的LLM调用。它是一个被裁剪过的独立执行单元。属性说明身份有自己的名字name和职责描述description主Agent靠description匹配指令有自己的系统提示词不和主Agent共用同一套工具可独立配置工具集不配就继承主Agent模型可独立配置模型不配就继承主Agent中间件可独立配置中间件栈默认不加载SubAgentMiddleware禁止子派生权限可独立配置权限不配就继承主Agent每一项都在构建期定死运行期改不了。子Agent的职责一句话替主Agent干杂活失败了自己扛不连累主线程。四、环节一子Agent创建——声明式 动态 兜底DeepAgents支持三种子Agent定义方式静态声明推荐在中间件初始化时预定义子Agent池指定名称、能力、工具、权限。主Agent直接匹配调用避免重复创建开销。这是生产环境的主流用法——子Agent池像部门编制任务来了按描述匹配最合适的执行者。动态创建主Agent根据任务类型通过task工具临时生成专属子Agent如临时数据清洗子Agent任务完成后销毁节省资源。默认兜底通用子Agent未匹配到专属子Agent时自动调用通用子Agent处理杂项任务避免主Agent过载。调用方可以显式关闭也可以自己定义一个同名子Agent覆盖默认。五、环节二任务委派——task工具唯一的合法通道在DeepAgents工程里task不只是一个工具它是委派动作的唯一合法通道。模型可以建议怎么协作但通道只能走这一条。主Agent不直接操作子图只调一个task工具。这个工具收两个参数description任务描述——要干什么subagent_type执行者类型——交给哪个子Agent中间件根据这两个参数找到对应子Agent、准备上下文、启动执行。整个过程对主Agent透明——调task跟调read_file没区别。委派的三不原则委派权严格集中于主Agent。具体体现为三条刚性约束子Agent不可自行派生——Sub-Agent的task工具被直接移除单层委派子Agent不可越权访问主状态——_EXCLUDED_STATE_KEYS阻断私有状态传播子Agent不可直接与用户交互——所有输出走主Agent中转标准化契约思维整个委派体系是标准化契约思维的极致体现定义契约化SubAgentTypedDict明确名称、描述、工具、权限等字段所有子Agent结构统一委派契约化TaskToolSchema定义两个参数description subagent_type规范委派方式结果契约化同步走ToolMessage格式异步走async_tasks结构化字典新增子Agent时只需遵循契约定义无需修改主Agent代码。组件交互可校验、可排障。六、环节三隔离执行——四重安全舱每个子Agent均运行于独立安全舱实现四重隔离task工具传递任务描述task工具传递任务描述ToolMessage仅返回最终结果ToolMessage仅返回最终结果不能直接通信Sub-Agent B 安全舱上下文隔离仅接收任务描述工具隔离专属工具集模型隔离可独立配置模型故障隔离失败不影响其他舱Sub-Agent A 安全舱上下文隔离仅接收任务描述工具隔离专属工具集模型隔离可独立配置模型故障隔离失败不影响其他舱主Agent完整上下文对话历史 待办列表 长期记忆上下文隔离子Agent仅接收主Agent传递的任务必要信息不含主Agent历史对话、临时变量等私有数据。执行过程中的中间结果仅存在于自身上下文不回传主Agent。技术实现_EXCLUDED_STATE_KEYS常量严格阻断主Agent的对话历史、待办列表、长期记忆等私有状态传递给子Agent。子Agent启动时只收到一条干净的HumanMessage——任务描述。工具隔离子Agent使用专属工具集与主Agent、其他子Agent完全隔离。避免工具冲突与权限滥用。模型隔离支持为不同子Agent配置差异化模型。复杂推理子Agent用强模型简单摘要子Agent用轻量模型——优化成本与性能。故障隔离子Agent执行失败仅影响自身。中间件捕获异常后返回标准化错误结果不破坏主Agent状态。一个子Agent调用工具报错主Agent仍可正常委派其他任务。舱壁隔离思维这套设计是舱壁隔离思维Bulkhead的经典落地。源自船舶设计的隔舱板理念——每个舱室拥有独立的资源和故障域一个舱进水不沉整条船。在软件架构中舱壁隔离解决三个问题故障扩散、资源竞争、上下文污染。DeepAgents的子Agent隔离设计让每个子Agent成为独立执行单元边界清晰、风险可控——这也是子Agent能支撑生产级场景的关键前提。七、环节四五同步 vs 异步调度主Agent调度子Agent干活分两条路对比项同步task异步任务适合任务短任务、独立分析、上下文隔离长任务、远端执行、后台处理返回方式等子Agent完成后返回一条ToolMessage先返回task_id后续再查状态管理双向过滤避免污染主图async_tasks账本登记任务索引架构模式命令模式 舱壁隔离先开工单后面按需查失败处理错误回到工具结果或抛出明确异常通过状态查询看到running/success/error/cancelled同步路径主Agent调用task工具 →SubAgentMiddleware过滤主状态 → 创建子Agent实例 → 执行任务 → 过滤中间过程 → 仅回传结构化最终结果 → 主Agent收到ToolMessage→ 继续执行。全流程阻塞式适合秒级短任务。异步路径主Agent发起任务 →AsyncSubAgentMiddleware登记到后台 → 立即返回task_id→ 主Agent继续干别的 → 随时通过list_async_tasks查询进度。异步任务支持五大操作状态查询、结果更新、任务取消、列表查看、按需重试。怎么选任务能在一个回合里干完 → 同步task。任务跨时间、跨远端服务、跨多轮查询 → 异步任务。不是二选一是覆盖不同场景的两条路。八、环节六结果回传——同步走ToolMessage异步走账本同步结果一条干净ToolMessage交回子Agent内部的所有消息被_EXCLUDED_STATE_KEYS拦下只把最后一条AI消息包装成ToolMessage通过Command(update...)写回主Agent的消息历史。主Agent看到的是一个干净的工具调用结果而不是子Agent几十轮的内部对话。这个设计至关重要——它让主Agent的上下文窗口不被子Agent的中间产物撑爆。异步结果任务账本随时查异步任务的结果不能靠等因为它可能跑很久。DeepAgents把异步任务登记到async_tasks字段里用Reducer合并更新。主Agent可以随时通过list_async_tasks查询任务状态不必等到任务完成。为什么要专门搞一个async_tasks字段因为异步任务不能靠聊天历史记住。聊天历史是给模型读的模型一忘任务就丢了。async_tasks是结构化状态不受模型遗忘影响。九、环节七故障处理与状态闭环DeepAgents构建了“执行→监控→恢复→审计”全链路状态闭环检测到异常所有状态执行子Agent执行任务监控实时采集状态/资源/日志故障隔离捕获异常标准化错误信息自动恢复失败重试可配置重试次数与间隔审计追溯async_tasks账本永久保存元数据实时监控中间件实时采集子Agent执行状态运行中/成功/失败、资源占用、工具调用日志故障隔离子Agent报错时中间件捕获异常返回标准化错误信息不扩散至主Agent自动恢复异步任务支持失败重试可配置重试次数与间隔审计追溯async_tasks账本永久保存任务元数据与执行结果十、最小权限与默认收紧子Agent的权限设计遵循最小权限与默认收紧原则默认继承主Agent权限——无需显式配置时仅拥有与主Agent一致的最小权限显式声明才生效——若需调整权限必须在配置中显式声明调用点可直接审查子Agent禁止派生——默认不加载SubAgentMiddleware杜绝无限派生这套设计让子Agent的操作始终处于可控范围是能落地生产的关键保障。十一、小结多Agent系统的本质是边界治理DeepAgents的子Agent不是多个Agent凑一起聊天的花架子而是主Agent发工单、子Agent干完交差的受控派工系统。源码层面的职责分配模块架构角色设计模式工程价值SubAgentMiddleware同步委派网关Middleware/Proxy主Agent不直接接触子图_build_task_tool()命令入口Command/Strategy工具空间稳定扩展成本低_EXCLUDED_STATE_KEYS舱壁规则Bulkhead/State Isolation防止上下文和私有状态污染GENERAL_PURPOSE_SUBAGENT泄压阀Convention over Configuration杂项任务不压主线程子Agentpermissions/interrupt_on策略门禁Policy Gate委派不能绕过安全审查AsyncSubAgentMiddleware后台任务网关Lifecycle Manager长任务不阻塞主AgentAsyncSubAgentState.async_tasks状态账本Reducer/Memento任务可追踪可恢复查询打一个比方主Agent像调度员同步子Agent像短工单执行者异步子Agent像远端后台工单async_tasks像工单台账。每个人各管一摊边界清楚。在企业级AI Agent落地中智能度不是第一优先级可控性、稳定性、可维护性才是。DeepAgents的Sub-Agent委派与隔离机制正是解决这一核心痛点的关键方案。