02 Dynamic subagents：用代码编排子智能体（解释器运行时）

先分清：静态子智能体 vs 动态子智能体#

01 篇 讲的是静态子智能体的配置面：subagents=[...] 怎么写、name/description/system_prompt 各管什么、mode 怎么选。那一篇里，派活这个动作是模型做的——模型看到一个 task 工具，自己决定调谁、调几次、什么时候停。

本篇完全换了一个位置：派活这个动作交给代码做。

一句话：静态 = 模型决定派谁；动态 = 代码决定什么时候派、派几个、怎么收敛。

底层机制（subagents= 本质上就是一个 task 工具）见 14 篇 和模式原理 04 篇；异步版见 03 篇。

它解决什么问题#

静态派活有三个绕不过去的局限：

① 一次只能派一个。 模型调用 task 工具，等结果回来，再决定下一次调用。审查 20 个文件就是 20 个串行的来回，墙钟时间线性叠加。

② 派几次、按什么顺序，由模型决定。 “把这批工单都处理一遍”这种需求，模型可能处理 8 个就”觉得差不多了”，也可能重复处理同一个。这是概率行为，不是确定性行为——你没法保证它一定遍历完 src/routes/ 下的每个文件。

③ 子智能体之间不能互相比较、筛选。 模型拿到的是一堆文本消息。让它”从 5 个方案里按这个标准挑最好的”，它只能靠”读一遍再拍脑袋”。它没法真的 sort，也没法真的做多数投票。

换成代码编排，换来的是三件事：

• 确定性：循环次数、并发度、停止条件都写在代码里，可复现、可单测。
• 并发：Promise.all 一次把 N 个 task() 同时发出去，墙钟时间从 N× 变成约 1×。
• 可计算的结果处理：结构化输出直接是 JS 对象，能在代码里排序、去重、投票、打分——真正意义上的”结果收敛（reduce）”。

代价也很直白：编排逻辑从提示词搬到了代码里，出问题时要看代码而不是看提示词；而且并发和循环都是 token 放大器，失控的 while 和无限扇出能把账单打穿。

整体机制#

1
graph TB
2
    U["用户任务<br/>User Task"] --> S["主管智能体<br/>Supervisor"]
3
    S -->|"写一段 JS 交出去"| I["解释器 Interpreter<br/>QuickJS 运行时"]
4
    I --> C{"代码编排<br/>Code Orchestration<br/>循环 / 分支 / Promise.all"}
5
    C -->|"task()"| A1["子智能体 A<br/>Subagent A"]
6
    C -->|"task()"| A2["子智能体 B<br/>Subagent B"]
7
    C -->|"task()"| A3["子智能体 C<br/>Subagent C"]
8
    A1 --> R["结果收敛<br/>Reduce / Synthesize<br/>filter / sort / 投票"]
9
    A2 --> R
10
    A3 --> R
11
    R --> F["最终答案<br/>Final Answer"]

这张图在说什么：

① 主管不再直接调子智能体，而是写一段 JavaScript 丢给解释器（Interpreter）——也就是把”怎么编排”这件事从模型脑子里搬进代码里。 ② 解释器里的代码负责编排（Code Orchestration）：循环、分支、Promise.all 并发，通过内置的 task() 把活派给子智能体（Subagent）。派几个、什么顺序、要不要重试，全由这段代码说了算。 ③ 子智能体返回的是 JS 值，不是对话文本，所以代码能做真正的收敛（Reduce）——过滤、排序、投票、打分——最后只把收敛后的结论交回主管。

换成 ASCII 看形状：

1
        用户任务："审查 src/routes/ 下每个文件，汇总 top 风险"
2
                            │
3
                            ▼
4
              ┌────────────────────────────┐
5
              │  主管 Supervisor（LLM）      │ 产出：一段 JS 代码
6
              └─────────────┬──────────────┘
7
                            │ eval
8
                            ▼
9
┌──────────────── 解释器 Interpreter（QuickJS）────────────────┐
10
│  files = (await tools.glob({pattern:"src/routes/**/*.ts"}))  │
11
│            .split("\n").filter(Boolean);     ← PTC 打开才有   │
12
│                                                              │
13
│  reviews = await Promise.all(   ← 代码决定并发几个            │
14
│    files.map(f => task({ description: `Review ${f}`,         │
15
│                          subagentType: "reviewer" })));      │
16
│  issues = reviews.flatMap(r => r.issues).sort(bySeverity);   │
17
│                                              ← 结果收敛 Reduce│
18
└──────────────────────────────┬───────────────────────────────┘
19
       ┌──────────┬────────────┴────────────┬──────────┐
20
       ▼          ▼                         ▼          ▼
21
   reviewer   reviewer      ......      reviewer   reviewer
22
    file 1     file 2                   file N-1    file N
23
       └──────────┴────────────┬────────────┴──────────┘
24
                  issues（已排序、已去重）→ 最终答案 → 主管 → 用户

⚠️ 版本要求：解释器（interpreter）运行时目前是 beta，官方明确说 API 和生命周期行为可能随版本变化。它依赖 langchain-quickjs>=0.2.0 和 Python 3.11+。

本机实测（2026-09-01）：本机 deepagents 是 0.7.5，包内没有解释器运行时——deepagents 包下不存在 interpreters 相关模块（deepagents.interpreters 的模块 spec 为 None），顶层导出里也没有任何解释器 / CodeInterpreter 相关符号；langchain_quickjs 也未安装。所以动态子智能体在本机不可用，下面的 Quickstart 和模式代码都跑不起来，需要 pip install langchain-quickjs 并升级到包含解释器运行时的深版本（beta）后再试。

本篇的价值不在”照抄能跑”，而在于讲清编排思路与六种模式。这些代码骨架可以直接迁移到任何”代码编排 + 调用 Agent”的实现上——用 LangGraph 自己搭图，或者就用普通 Python 写循环和线程池，思路完全一样。

快速上手（Quickstart）#

动态子智能体不是一套新 API，而是给已有的 agent 多挂一个中间件。三步：

1. 装解释器运行时：pip install "langchain-quickjs>=0.2.0"（Python 3.11+）。
2. 在 create_deep_agent(...) 的 middleware=[...] 里挂上 CodeInterpreterMiddleware()。
3. 在 subagents=[...] 里配好子智能体——它们的 name 就是代码里 subagentType 能填的取值，description 是模型判断”该找谁”的依据。

原文档给了 7 个模型厂商的版本（Google / OpenAI / Anthropic / OpenRouter / Fireworks / Baseten / Ollama），差别只在 model= 那一行；这里只保留 OpenAI 版：

1
from deepagents import create_deep_agent
2
from langchain_quickjs import CodeInterpreterMiddleware
3

4
agent = create_deep_agent(
5
    model="openai:gpt-5.5",
6
    subagents=[{
7
        "name": "reviewer",
8
        "description": "Reviews code for security issues, citing lines and severity",
9
        "system_prompt": "You are a security-focused code reviewer. Report issues with line numbers and severity.",
10
    }],
11
    middleware=[CodeInterpreterMiddleware()],  # 关键：挂上解释器，task() 才会出现
12
)

说明几点：

• 只要 subagents 非空、又挂了 CodeInterpreterMiddleware()，解释器里就会自动多出一个全局函数 task()——不需要你额外注册什么。
• 不需要额外配置就能做基础扇出：Deep Agents 内置的 general-purpose 子智能体（默认子智能体）可以直接被 task() 调用。
• 想要专业分工，才需要自己配子智能体，把名字、描述、系统提示词写清楚。

再用一句”workflow”触发它：

1
result = agent.invoke({
2
    "messages": [{"role": "user", "content": "Run a workflow that reviews every file in src/routes/ and summarizes the top risks."}]
3
})

💡 提示：“workflow” 这个词是一个有用的触发器。解释器的系统提示词把 “workflow” 当成信号——看到它就倾向于”通过解释器组织工作”，用代码里的 task() 派子智能体，而不是一个一个地做模型选的工具调用。把需求描述成一个 “workflow”，就是你主动打开动态编排的拉杆。反过来，如果只是一次直接的委派，就平铺直叙地说，别用这个词，免得白白绕进解释器。

📌 注意：dcode（LangChain 的终端编码 agent）自带了代码解释器，所以在 dcode 里动态子智能体开箱即用，不用自己挂中间件。

它是怎么工作的#

这一段是全篇重点，把机制拆开讲。

1
const review = await task({
2
  description: "Review src/auth/login.ts for auth issues. Cite line numbers.",
3
  subagentType: "reviewer",
4
  responseSchema: {
5
    type: "object",
6
    properties: {
7
      issues: { type: "array", items: { type: "object", properties: {
8
        file: { type: "string" }, line: { type: "number" },
9
        severity: { type: "string" }, description: { type: "string" },
10
      }}},
11
    },
12
  },
13
});
14

15
// 带 responseSchema 时，拿到的已经是类型化对象，不需要 JSON.parse
16
const critical = review.issues.filter((issue) => issue.severity === "high");

1
const files = (await tools.glob({ pattern: "src/routes/**/*.ts" }))
2
  .split("\n")
3
  .filter(Boolean);          // 在代码里发现 / 过滤输入
4
const reviews = await Promise.all(files.map((f) => task({  // 再用 task() 派活
5
  description: `Review ${f}`, subagentType: "reviewer",
6
})));

1
# 纯文本伪代码：同一套编排思路，与语言和框架无关
2
files   = discover_inputs("src/routes/**/*.ts")     # 发现输入（对应 tools.glob）
3
reviews = parallel_map(files, limit = 4,            # 并发要有上限（对应 Promise.all）
4
                       fn = call_subagent("reviewer", 结构化输出))
5
issues  = flatten(r.issues for r in reviews)        # 显式收敛（对应 flatMap）
6
issues  = dedupe(sort_by_severity(issues))          # 排序 + 去重
7
return  issues                                      # 收敛后的结论才是答案

六种编排模式#

原文的 Patterns 一节说得很清楚：这些模式不是配置出来的，是模型根据任务形状自己写的解释器代码”长”出来的；你能控制的只有”放哪些子智能体进去”。但六种模式共享同一套编排姿势：把工作握在 JS 变量里 → 用 task() 派子智能体 → 在代码里合并结果。

下面逐个讲，每种给：适用场景 / 代码骨架 / 为什么这么写 / 代价。

1
// 前提：tickets 已经带上 category 字段（分类可以在同一段代码里先派一个分类子智能体做）
2
const SPECIALIST = { bug: "bug-fixer", feature: "feature-analyst", question: "support-agent" };
3

4
const handled = await Promise.all(
5
  tickets.map((ticket) =>
6
    task({
7
      description: `Handle this ${ticket.category}:\n${ticket.text}`,
8
      subagentType: SPECIALIST[ticket.category],
9
    }),
10
  ),
11
);
12
// ... 把 handled 按 category 分组，拼成一份分诊报告
13
handled;

1
// 每个文件派一个 reviewer 并行审，最后把发现合并
2
const files = (await tools.glob({ pattern: "src/routes/**/*.ts" }))
3
  .split("\n")
4
  .filter(Boolean);
5

6
const reviews = await Promise.all(
7
  files.map((file) =>
8
    task({
9
      description: `Review ${file} for authentication issues. Cite line numbers.`,
10
      subagentType: "reviewer",
11
      responseSchema: issuesSchema, // -> { issues: [{ file, line, severity }] }
12
    }),
13
  ),
14
);
15

16
const issues = reviews.flatMap((r) => r.issues);
17
// ... 按严重级别排序、去重，总结 top 风险
18
issues;

1
// 第一趟：审计；第二趟：逐条独立验证，只保留被确认的
2
const { findings } = await task({
3
  description: "Audit the payments module for vulnerabilities.",
4
  subagentType: "reviewer",
5
  responseSchema: findingsSchema, // -> { findings: [{ id, file, line, description }] }
6
});
7

8
const verdicts = await Promise.all(
9
  findings.map((f) =>
10
    task({
11
      description: `Verify ${f.file}:${f.line} (${f.description}). Confirm or refute.`,
12
      subagentType: "verifier",
13
      responseSchema: verdictSchema, // -> { confirmed: boolean }
14
    }),
15
  ),
16
);
17

18
const confirmed = findings.filter((_, i) => verdicts[i]?.confirmed);
19
// ... 只报告被确认的漏洞
20
confirmed;

1
// 并发生成多个独立方案，再按需求打分留最优
2
const proposals = await Promise.all(
3
  [1, 2, 3].map((n) =>
4
    task({
5
      description: `Approach ${n}: redesign the orders schema, with tradeoffs.`,
6
      subagentType: "architect",
7
      responseSchema: designSchema, // -> { design, tradeoffs }
8
    }),
9
  ),
10
);
11

12
// ... 按需求给每个方案打分
13
const best = proposals.sort((a, b) => score(b) - score(a))[0];
14
best;

1
// 先生成变体，再两两判胜负，直到决出唯一冠军
2
let bracket = await Promise.all(
3
  [1, 2, 3, 4, 5].map((n) =>
4
    task({ description: `Rewrite processOrder for readability (variant ${n}).`, subagentType: "writer" }),
5
  ),
6
);
7

8
while (bracket.length > 1) {
9
  const winners = [];
10
  for (let i = 0; i < bracket.length; i += 2) {
11
    if (bracket[i + 1] === undefined) { winners.push(bracket[i]); break; } // 轮空直接晋级
12
    const { winner } = await task({
13
      description: `Pick the more readable:\n\nA:\n${bracket[i]}\n\nB:\n${bracket[i + 1]}`,
14
      subagentType: "judge",
15
      responseSchema: pickSchema, // -> { winner: "A" | "B" }
16
    });
17
    winners.push(winner === "A" ? bracket[i] : bracket[i + 1]);
18
  }
19
  bracket = winners;
20
}
21
bracket[0]; // 冠军

1
// 反复派活，每轮和"已找到的"去重，直到某一轮没有新东西
2
const seen = new Set();
3
const found = [];
4

5
while (true) {
6
  const { items } = await task({
7
    description: `Find dead code. Already found: ${[...seen].join(", ") || "(none)"}.`,
8
    subagentType: "analyzer",
9
    responseSchema: itemsSchema, // -> { items: [{ id, file }] }
10
  });
11
  const fresh = items.filter((i) => !seen.has(i.id));
12
  if (fresh.length === 0) break; // 收敛：没有新东西了
13
  for (const i of fresh) { seen.add(i.id); found.push(i); }
14
}
15
found;

关掉动态子智能体#

只要有子智能体，动态派发就是默认开的。 如果你想保留子智能体、但只允许它们从常规的 task 工具路径被调用（模型一个个派，不接受代码编排），就在中间件上关掉：

1
from deepagents import create_deep_agent
2
from langchain_quickjs import CodeInterpreterMiddleware
3

4
agent = create_deep_agent(
5
    model="openai:gpt-5.5",
6
    subagents=[{"name": "reviewer", "description": "Reviews code", "system_prompt": "Review code."}],
7
    middleware=[CodeInterpreterMiddleware(subagents=False)],  # 关掉代码里的 task()
8
)

原文档同样给了 7 个厂商的版本，差别只在 model= 一行，这里保留一版。

这个开关适合的场景：你已经有一套稳定的静态委派提示词和工作流，不想让模型某天突然”自由发挥”写一段解释器代码；或者你需要在每次派发前做审批——因为 task() 不逐次经过 interrupt_on，关掉它是拿到逐次审批最省事的办法。

常见坑#

① 子智能体依然是无状态的。 每次 task() 都是全新的上下文，上一次的结论不会自动带过去。想让第二轮知道第一轮发现了什么，必须显式写进 description（就像”循环直到达标”里回灌 seen 那样），或者塞进 responseSchema 要求它自己带上。这点和 01 篇 的静态子智能体完全一致。

② 并发一定要有上限。 Promise.all(files.map(...)) 看着优雅，但 200 个文件就是 200 个同时跑的 agent loop。上线前按 chunk 分批、按 limit 限流、或者只对筛选后的输入扇出。

③ 结果必须显式收敛。 代码块最后要有一个”值”被交回去（原文每个例子的末尾都孤零零站着一个 handled; / issues; / confirmed; / best; / found;——那不是笔误，那是把结果送回模型的方式）。只循环不收敛，模型拿不到任何东西。

④ 不能把不收敛的循环留在生产。 while (true) 只适合”每轮严格去重、必然收敛”的场景。去重键不稳定、子智能体不听话、或者任务本身是开放的，都会变成烧钱黑洞。加最大轮数兜底。

⑤ task() 绕过了逐次审批。 它从 eval 内部派发，interrupt_on 不生效。要审批就拦 eval 工具本身，或者直接 subagents=False。

⑥ 没有 responseSchema 就没有”可编程的结果”。 拿到一段散文，filter / sort / 投票全都无从谈起，动态编排就退化成了”并发地要几段文本”。能用 schema 就用 schema。

⑦ PTC 默认关闭。 代码里想用 tools.* 发现输入，必须在中间件上给白名单（ptc=["glob"]），否则解释器看不见文件系统。

⑧ 这是 beta，本机也跑不起来。 本机 deepagents 0.7.5 没有解释器运行时、langchain_quickjs 未安装，所以上面的代码骨架在本机只能读不能跑。API 和生命周期行为在正式版前都可能变——迁移时记得锁版本。

小结#

1. 动态子智能体 = 把编排逻辑从提示词搬进代码。 模型不再”一次一个”地调 task 工具，而是在解释器里写 JS：循环、分支、Promise.all、投票、排序。
2. 机制上只多了一个零件：CodeInterpreterMiddleware() 挂上、subagents 非空，解释器里就出现内置的 task() 全局函数，入参 description / subagentType / responseSchema，一次调用跑完一整轮子智能体的 agent loop。
3. 它和 task 工具是同一个能力的两种用法：同一批子智能体、同一套配置，区别只在谁发起、并发几个、结果以什么形态回来。但 task() 不逐次走审批路径。
4. 六种模式共享一套姿势：把工作握在变量里 → 用 task() 派活 → 在代码里 filter/sort/投票收敛。分类、扇出是”把活干完”；对抗验证、生成筛选、锦标赛、循环到达标是”用 token 换质量”。
5. 两个配套能力：tools.*（PTC，默认关，需白名单）负责”发现输入”，mode="thread" 负责”跨轮持久化解释器变量”；底层思路来自递归语言模型（RLM）。
6. 本机不可用：deepagents 0.7.5 包内无解释器运行时、langchain_quickjs 未安装，官方标注 beta。本篇价值在于编排思路，代码骨架可平移到 LangGraph 或普通 Python。

一句话选型#

一次委派、职责隔离 → 用 01 篇 的静态子智能体；一批活要遍历完、要多视角互验、要按结果排序筛选 → 用代码编排。

判断标准很简单：如果”派几次、派给谁”这件事你希望它是确定的，就把它写进代码。

延伸阅读：01 静态子智能体配置面 ｜ 03 异步子智能体 ｜ 04 Subagents 模式原理 ｜ 14 底层机制与抓包