Deep Agents 中的动态子代理介绍

随着代理承担的任务越来越复杂，它们会面临以下挑战：

• 大规模可靠地完成任务
• 管理自身上下文

我们一直在以“动态子代理（dynamic subagents）“的形式尝试应对这些挑战：主代理不再通过通用工具调用来分发子任务，而是编写一段简短的脚本，驱动子代理执行。这样一来，模型可以利用自己擅长编写的代码模式（如循环、分支或并发）来编写适合任务的编排逻辑。

为什么需要动态子代理？

Deep Agents 已经支持子代理。它们可以隔离上下文，让主代理委派离散的工作单元，并将中间结果排除在主上下文窗口之外。那么，为什么我们还需要动态子代理呢？

使用普通子代理时，每次只能调用一个，由主模型直接调用。在小规模场景下这没问题。但当需要生成数百个子代理，或者编排逻辑是条件式的、多阶段的时候，这种方式就会失效。

动态子代理通过程序化编排解决了这个问题。代理不再逐轮调用工具，而是编写一段简短的脚本来编排和调用子代理，并在轻量级解释器中执行。

典型的例子：针对一份 300 页的文档，每页使用一个子代理。与其调用 300 次子代理工具，代理可以编写一个循环：

const results = await Promise.all(pages.map(page =>
  task({ description: `Summarize page ${page.number}`, subagentType: "summarizer" })
));

这解锁了基于工具调用的编排无法可靠实现的两点：

大规模确定性覆盖。 没有结构化约束时，代理会对范围做出判断，检查 500 项中的 75 项就认为完成了。而调度循环不会这样。覆盖变成了结构性保证，而不是提示工程问题。

可靠的复杂编排。 将编排写为代码比让模型将其作为一系列工具调用重现更为可靠，尤其在扇出 + 合成、多阶段流水线或条件分支场景下。

这与 Claude Code 和递归语言模型（RLMs）中的工作流思路相同：模型编写代码，代码再调度更多代理。

快速入门

动态子代理需要两个要素：用于委派工作的子代理，以及一个代码解释器：一个安全、轻量级的运行时，模型在其中编写并执行编排代码。Deep Agents 包含一个基于 QuickJS 的可选代码解释器。要使用它，请先安装 QuickJS 中间件包，然后在 create_deep_agent 时通过 middleware 参数传入 CodeInterpreterMiddleware。

pip install -U "deepagents[quickjs]"

from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
    model="openai:gpt-5.5",
    middleware=[CodeInterpreterMiddleware()],
)

Deep Agents 内置了一个通用子代理，因此工作流中已经可以使用一个通用子代理配置。对于专门的工作流，可以配置自定义子代理，指定其名称、描述和系统提示词：名称和描述用于让代理知道应该调用哪个角色。

要触发动态子代理，请在提示词中使用“工作流“这个词，例如：

result = await agent.ainvoke({
    "messages": [{"role": "user", "content": "运行一个工作流，检查 src/routes/ 中的每个文件，并总结主要风险。"}]
})

与编码代理一起使用

体验动态子代理最快的方式是使用 dcode，这是我们基于 Deep Agent 构建的终端编码代理。它默认启用了代码解释器，因此无需额外配置——动态子代理开箱即用。

安装

curl -LsSf https://langch.in/dcode | bash

运行

dcode

要触发动态子代理，只需要求一个“工作流”。代理不会自己埋头苦干，也不会尝试用原生任务工具管理子代理扇出，而是编写一个编排脚本，调用内置的 task() 全局函数，并在代码解释器中执行。例如：“运行一个工作流，检查 src/ 下的每个文件是否存在 SQL 注入。”

随着子代理生成，dcode 会在动态子代理面板中实时显示它们，并按调度阶段分组。

你可以通过 dcode 最快地体验，也可以通过 ACP（例如 Zed）在你选择的工具中使用。

工作原理

代理被赋予一个 eval 工具。它编写 JavaScript 代码，在解释器中安全执行。当配置了子代理时，解释器会暴露一个内置的 task() 全局函数，用于从代码中分发任务。根据手头的任务，模型会编写不同的代码——循环、分支、Promise.all——解释器会确定性地执行它们。

task() 接受 description、subagentType 和可选的 responseSchema——当提供 schema 时，结果已经是类型化对象，可以直接过滤或传递到下一步。

const result = await task({
  description: "检查 src/auth/login.ts 是否存在安全问题。",
  subagentType: "reviewer",
  responseSchema: {
    type: "object",
    properties: {
      severity: { type: "string", enum: ["high", "medium", "low"] },
      issues: { type: "array", items: { type: "string" } },
    },
  },
});

const critical = result.severity === "high" ? result.issues : [];
critical; // 模型看到最后一行

更多信息，请参阅文档中的程序化子代理和解释器。

常见编排模式

Anthropic 的动态工作流普及了一套用于并行代理工作的编排模式。它们不是需要开启的功能，而是自然而然地根据工作需求形成的形状，代理会根据任务变化切换到不同的模式。下表将每种形状映射到适合的工作类型。

下面我们将深入探讨每种模式在 Deep Agents 中的工作方式，并附带实时追踪。此外，我们还制作了一个视频解释这六种模式，可以在这里查看。

分类与执行

首先对项目进行分类，然后根据分类结果由专门的子代理处理相应项目。这样可以在同一批次中处理混合输入，不同项目需要不同的专业知识。

用例： 分类支持工单、错误日志、用户反馈，或任何需要根据类型进行不同处理的批量项目。

示例： 对积压的支持工单进行分类。代理读取工单，将每个工单分类为错误、功能请求或问题。错误交给错误调查员，功能请求交给功能分析师，问题交给支持应答员。最终结果按类别分组汇总。

查看追踪信息请点击这里。

扇出与合成

代理并行地将同一类工作分发到多个项目，然后合并结果。

用例： 跨目录代码审查、分析一批文档、处理日志文件、跨多个服务运行相同检查。

示例： 对源码树进行按文件的安全审查。代理发现 src/ 下所有 TypeScript 文件，然后为每个文件并行调度一个安全审查子代理。最后将结果合并成一份按严重性排序的报告，包含需要修改的代码行。

查看追踪信息请点击这里。

对抗验证

两遍模式。第一遍产生发现。第二遍将每个发现交给独立的验证器，只有通过验证的发现才被保留。当置信度比速度更重要时，可减少误报。

用例： 误报成本高的安全审计、合规检查、任何需要高置信度的审查。

示例： 误报不可接受的安全审计。审计员广泛搜寻潜在漏洞，然后每个漏洞交给一个独立的验证器，验证器重新阅读代码并返回 CONFIRMED 或 REFUTED 结果。只有被确认的漏洞才进入最终报告。

查看追踪信息请点击这里。

生成并过滤

多个子代理独立生成同一问题的解决方案。代理在代码中对结果进行比较、评分和过滤，只保留最好的。

用例： 架构方案、重构策略、内容变体，任何在最终确定前探索多个选项能产生更好结果的任务。

示例： 竞速实现限流器重构方案，并进行排名。代理让架构子代理生成多个独立的重构方案，每个方案写入不同文件以避免覆盖。然后根据突发正确性、多实例支持和复杂度进行评分。得分最高的方案胜出，并附有理由。

查看追踪信息请点击这里。

锦标赛

不同变体由判断子代理进行两两比较，胜者通过淘汰轮次晋级。

用例： 在主观标准下进行优化、样式选择、在竞争性实现中做出选择。

示例： 对混乱的 createOrder 处理器进行成对淘汰赛。多个编写子代理各自生成候选重写方案，具有不同优先级，然后判断子代理两两比较，逐轮晋级，直到选出一个最佳方案。最终返回判断理由。

查看追踪信息请点击这里。

循环直到完成

代理运行探索循环，对已发现的结果进行去重，直到没有新结果出现。当工作范围事先未知时非常有用。

用例： 穷尽搜索、死代码检测、依赖审计，任何需要全面性而非固定结果数量的扫描。

示例： 基于轮次的安全扫描。代理运行一轮扫描，在代码中检查发现了什么，只有当前轮次发现了新问题时才启动下一轮。当某轮次没有新发现时停止。最终报告汇总结果，并说明共进行了多少轮。

查看追踪信息请点击这里。

结论

动态子代理是赋予代理更多自主性和更高可靠性的方式。代码负责覆盖和中间上下文，模型仍负责需要判断的重任。上述模式只是起点。在实践中，代理会根据任务需求组合和混合这些模式。

这是递归语言模型概念的最简形式。一个代理编写代码，代码再调度更多代理。代理递归地调用自身，不受上下文窗口限制，也不被固定工作流束缚。代理可以对问题进行任意深度的分解，然后以任何适合的形状重新组装各部分。上面强调的编排模式只是初步展示可能性，随着模型编写代码能力的提升，天花板只会越来越高。

动态子代理是 Deep Agents 今天能够提供给你的能力。现在就开始：为你的代理添加代码解释器，或者直接使用 dcode，动态子代理开箱即用。

致谢

合著者：@colifran_ 和 @huntlovell。感谢 @hwchase17、@masondrxy 和 @chester_curme 的审阅意见。