💡 一句话概括：Dynamic SubAgents 把「子 Agent 编排」从主 Agent 逐回合的隐式推理升级为一段在沙箱里确定执行的编排代码。主 Agent 写出一段 JS 脚本，脚本里用内置的 task() 全局函数、配合 for 循环 / 条件分支 / Promise.all 并行，把任务成批派发给已注册的子 Agent，并在脚本内直接聚合结果。

本文基于 langchain-ai/deepagents 源码与 LangChain 官方文档撰写，力求「以图表代替文字堆砌」。

1. 一图看懂：两种委派模式的差别

传统 task 委派：主 Agent 每个回合只发起一次委派，编排逻辑存在于「模型的脑子里」。Dynamic SubAgents：主 Agent 一次性写出编排脚本，由沙箱确定执行。

flowchart LR
    subgraph trad["传统 task 委派 逐回合"]
        TA["主 Agent 模型"]
        TA -->|"回合 1"| T1["子 Agent 1"]
        TA -->|"回合 2"| T2["子 Agent 2"]
        TA -->|"回合 N"| T3["子 Agent N"]
        T1 -->|"结果回灌上下文"| TA
        T2 -->|"结果回灌上下文"| TA
        T3 -->|"结果回灌上下文"| TA
    end
    subgraph dyn["Dynamic SubAgents 一段脚本"]
        DA["主 Agent 写编排脚本"] --> LOOP["for / Promise.all 派发循环"]
        LOOP --> D1["子 Agent 1"]
        LOOP --> D2["子 Agent 2"]
        LOOP --> D3["子 Agent N"]
        D1 --> AGG["脚本内聚合 过滤 归并"]
        D2 --> AGG
        D3 --> AGG
        AGG -->|"仅回传聚合结果"| DA
    end

2. 核心概念速查

💡 重要区分：「Dynamic Subagents（解释器路径）」依赖的 CodeInterpreterMiddleware 不在 deepagents 仓库里，而是独立 PyPI 包 langchain-quickjs，通过 create_deep_agent(..., middleware=[CodeInterpreterMiddleware()]) 装配。它与仓库内的 AsyncSubAgentMiddleware（远程 Agent Protocol 后台任务，另一条路）不是一回事。

3. 整体架构

三层协作：主 Agent 进程内的两个中间件（解释器 + 子 Agent）+ 独立的 QuickJS 沙箱 + 一组子 Agent 子图。

flowchart TB
    U["用户 / 上游任务"] --> MA["主 Agent 模型循环"]
    subgraph proc["主 Agent 进程"]
        MA
        CIM["CodeInterpreterMiddleware eval 工具"]
        SAM["SubAgentMiddleware task 工具"]
    end
    subgraph box["QuickJS 沙箱 按 thread_id 隔离"]
        JS["编排脚本 JS"]
        TG["task 全局函数"]
        PT["tools.* PTC 可选"]
    end
    subgraph subs["子 Agent 子图"]
        S1["general-purpose"]
        S2["自定义子 Agent A"]
        S3["自定义子 Agent B"]
    end
    MA -->|"emit eval 工具调用"| CIM
    CIM -->|"执行 JS"| JS
    JS --> TG
    JS -. 可选 .-> PT
    TG -->|"桥接回 Python"| SAM
    SAM -->|"invoke 子图"| S1
    SAM --> S2
    SAM --> S3
    S1 -->|"结构化结果"| SAM
    SAM -->|"resolve promise"| TG
    CIM -->|"eval 结果 ToolMessage"| MA

组件对应源码见 graph.py 与 subagents.py。

4. 原理

4.1 双层桥接：JS 世界 ↔ Python 世界

Dynamic SubAgents 的关键是一条「JS 全局 → Python 工具 → 子图」的桥。主 Agent 从不直接调子图，而是写脚本让沙箱代为派发。

4.2 变量持久化：mode 的三档语义

4.3 并行与预算

• 并行：脚本用 await Promise.all([task(...), task(...), ...]) 扇出；桥接层对每个 REPL 有并发上限；顶层不可解析的 promise 会抛 Deadlock。
• 沙箱限制：默认 memory_limit=64MB、timeout=5.0s、max_result_chars=4000（结果截断）。
• PTC 预算：max_ptc_calls=256/次 eval，超出抛 PTCCallBudgetExceeded。

以上解释器配置与语义以 langchain-quickjs 及 Dynamic subagents 文档 为准。

5. 实现流程（源码分析）

5.1 SubAgentMiddleware 与 task 工具（subagents.py）

5.2 create_deep_agent 装配与 general-purpose 自动注入（graph.py）

子 Agent 按 spec 结构判别路由；处理完用户子 Agent 后，若未自定义同名且未禁用，则把 general-purpose 插入首位。

flowchart TB
    A["subagents 列表项 spec"] --> B{"结构判别"}
    B -->|"含 graph_id"| C["AsyncSubAgent 进 async_subagents"]
    B -->|"含 runnable"| D["CompiledSubAgent 原样 inline"]
    B -->|"其它"| E["SubAgent 补默认值加中间件栈 进 inline"]
    E --> F{"已存在 general-purpose ?"}
    F -->|"否 且未禁用"| G["insert 0 注入 general-purpose"]
    F -->|"是"| H["跳过自动注入"]
    G --> I["实例化 SubAgentMiddleware 暴露 task 工具"]
    D --> I
    C --> J["若非空则装配 AsyncSubAgentMiddleware"]
    H --> I

5.3 自定义子 Agent 的配置 Schema

6. 一次真实调用的完整流程

以「主 Agent 派发一批子 Agent 并聚合」为例，8 个关键跃迁如下时序图所示。

sequenceDiagram
    participant M as 主 Agent
    participant I as CodeInterpreter eval
    participant Q as QuickJS 沙箱
    participant T as task 全局
    participant B as SubAgentMiddleware
    participant S as 子 Agent 子图
    M->>I: 调用 eval 传入 JS 编排脚本
    I->>Q: 在持久上下文执行 JS
    Q->>T: await task description subagentType responseSchema
    T->>B: 桥接到 Python task 工具
    B->>B: 校验类型 构造 subagent_state
    B->>S: invoke subagent_state
    S->>S: 运行完整 agentic loop
    S-->>B: 返回 messages 或 structured_response
    B-->>T: Command update resolve promise
    T-->>Q: 结果注入脚本
    Q->>Q: Promise.all 聚合 过滤
    Q-->>I: 脚本返回值
    I-->>M: eval 结果 ToolMessage 截断至 max_result_chars

7. 优势

上述优势的官方阐述见 LangChain 官方博客。

8. 适用场景

❌ **何时不要用：**只做一次性、单点委派时，直接调用 task 工具更简单；套解释器 + 编排脚本反而是额外开销。Dynamic SubAgents 的价值只在「规模」或「编排复杂度」上来后才体现。

9. 触发与配置

在 Deep Agents 中启用只需把解释器中间件传入 create_deep_agent；task() 全局默认开启（可 subagents=False 关闭），PTC 需显式白名单。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
    model="...",
    tools=[search_web],
    subagents=[research_subagent, critic_subagent],  # 注册角色
    middleware=[
        CodeInterpreterMiddleware(
            mode="thread",      # 变量跨回合持久
            subagents=True,     # 注入 task() 全局（默认）
            ptc=["search_web"], # 可选：开放 tools.searchWeb
        )
    ],
)
# 注意：PTC 桥接为 async host function，需用 ainvoke 驱动

📌 **触发信号：**当任务出现「对上百个单元逐一处理」「多阶段并行+汇总」「多视角交叉验证」「超长材料递归分析」等特征，且已注册可复用的子 Agent 角色时，主 Agent 会倾向写编排脚本，用 task() 成批驱动子 Agent，而非逐回合单点委派。

10. 与 Claude Code Dynamic Workflows 的对比

💡 同源哲学，不同载体：两者都遵循「让模型写代码来编排，而非逐回合单点工具调用」。区别在于——DeepAgents Dynamic SubAgents 是一个 Python 框架能力(靠 QuickJS 中间件),而 Claude Code Dynamic Workflows 是 Anthropic 官方的端到端产品能力：Claude 为任务临时写一段 JS 脚本，由专用 runtime 在后台执行，一次可并行编排数十到数百个子 Agent。

10.1 一图看懂两者的编排链路

flowchart TB
    subgraph DA["DeepAgents Dynamic SubAgents 框架"]
        direction TB
        DM["主 Agent 模型"] -->|"emit eval 工具调用"| DQ["QuickJS 沙箱 进程内中间件"]
        DQ -->|"task 全局"| DS["子 Agent 子图"]
        DS -->|"resolve"| DQ
        DQ -->|"eval 结果"| DM
    end
    subgraph CC["Claude Code Dynamic Workflows 产品"]
        direction TB
        CM["Claude 主循环"] -->|"生成 JS 脚本"| CR["专用 workflow runtime 隔离后台"]
        CR -->|"agent / pipeline / parallel"| CS["subagents md 定义"]
        CS -->|"结果留在脚本变量"| CR
        CR -->|"仅最终答案"| CM
    end

10.2 逐维度对比

Claude Code 侧事实依据见 Dynamic workflows 文档 与 A harness for every task 博客。

10.3 关键异同小结

✅ 相同点

• 都让模型写 JS 脚本编排，而非逐回合工具调用
• 代码派发的都是子 Agent（跑各自完整 agentic loop）
• 中间结果留在脚本，只回传聚合/最终结果，省主上下文
• 都支持循环 / 分支 / 并行的代码化编排

💡 不同点

• 框架能力 vs 官方产品能力
• 进程内 QuickJS 中间件 vs 专用后台 runtime
• 单一 task() vs 一组 agent/pipeline/parallel/phase 原语
• DeepAgents 靠 mode 控持久；Claude Code 强制确定性 + 运行可恢复
• 子 Agent 用代码 TypedDict vs 用 .md 文件定义

10.4 别混淆：Claude Code 三条「代码代替逐轮工具调用」的能力

Anthropic 有三个共享同一哲学、但目标不同的能力，与 DeepAgents 对应的只有第三条。

三者的官方出处分别为 Code execution with MCP、Programmatic tool calling 与 Dynamic workflows 文档。

10.5 Workflows vs Agents：为什么叫「Dynamic」

📌 Anthropic 在《Building effective agents》里把 workflow 定义为「通过预定义代码路径编排 LLM 与工具」，把 agent 定义为「LLM 自主决定流程」[Building effective agents]。Dynamic Workflow 正是二者的融合：一方面「把计划落成代码」拿到确定性与可复现，另一方面这段代码路径由模型按任务动态编写——即为每个用例现写一套量身定制的 harness，而非通用静态脚本 [A harness for every task]。DeepAgents Dynamic SubAgents 走的是同一条「动态生成 + 确定执行」路线。

参考来源：subagents.py · graph.py · langchain-quickjs · Subagents 文档 · Dynamic subagents 文档 · LangChain 博客