异步 subagents 允许 supervisor agent 启动会立即返回的后台任务，因此 supervisor 可以在 subagents 并发工作时继续与用户交互。Supervisor 可以随时检查进度、发送后续指令或取消任务。 这建立在subagents 之上。Subagents 会同步运行，并阻塞 supervisor 直到完成。当任务长时间运行、可并行化，或需要在执行过程中调整方向时，请使用异步 subagents。
异步 subagents 是 deepagents 1.9.0 中提供的 preview feature。Preview features 正在积极开发中，API 可能发生变化。
异步 subagents 会与任何实现 Agent Protocol 的 server 通信。你可以使用 LangSmith Deployments，也可以 self-host 任何兼容 Agent Protocol 的 server。每个 subagent 都独立于 supervisor 运行，supervisor 通过 SDK 控制它们的启动、检查、更新和取消。

​
何时使用异步 subagents

维度同步 subagents异步 subagents
执行模型Supervisor 阻塞直到 subagent 完成立即返回 job ID，supervisor 继续运行
并发并行但阻塞并行且非阻塞
任务中更新不可能通过 update_async_task 发送后续指令
取消不可能通过 cancel_async_task 取消正在运行的任务
有状态性无状态，调用之间没有持久 state有状态，在自己的 thread 上跨交互维护 state
最适合Agent 应先等待结果再继续的任务在 chat 中交互式管理的长时间运行复杂任务

​
配置异步 subagents

将异步 subagents 定义为 AsyncSubAgent specs 的列表，每个 spec 都指向一个 Agent Protocol server： 
import { createDeepAgent, AsyncSubAgent } from "deepagents";

const asyncSubagents: AsyncSubAgent[] = [
  {
    name: "researcher",
    description: "Research agent for information gathering and synthesis",
    graphId: "researcher",
    // No url → ASGI transport (co-deployed in the same deployment)
  },
  {
    name: "coder",
    description: "Coding agent for code generation and review",
    graphId: "coder",
    // url: "https://coder-deployment.langsmith.dev"  // Optional: HTTP transport for remote
  },
];

const agent = createDeepAgent({
  model: "google_genai:gemini-3.5-flash",
  subagents: [...asyncSubagents],
});
字段类型描述
namestring必需。唯一标识符。Supervisor 启动任务时使用它。
descriptionstring必需。说明该 subagent 做什么。Supervisor 用它决定委派给哪个 agent。
graphIdstring必需。Agent Protocol server 上的 graph ID（或 assistant ID）。对于基于 LangGraph 的部署，它必须匹配 langgraph.json 中注册的 graph。
urlstring可选。省略时使用 ASGI transport（in-process）。设置后使用 HTTP transport 连接远程 Agent Protocol server。
headersRecord<string, string>可选。发送到远程 server 的额外 headers。用于 self-hosted Agent Protocol servers 的自定义认证。
对于基于 LangGraph 的部署，请在同一个 langgraph.json 中注册所有 graphs，以用于 co-deployed 设置： 
{
  "graphs": {
    "supervisor": "./src/supervisor.py:graph",
    "researcher": "./src/researcher.py:graph",
    "coder": "./src/coder.py:graph"
  }
}

​
使用异步 subagent tools

AsyncSubAgentMiddleware 会为 supervisor 提供五个 tools：
Tool用途返回
start_async_task启动新的后台任务Task ID（立即返回）
check_async_task获取任务当前状态和结果Status + result（如果完成）
update_async_task向正在运行的任务发送新指令Confirmation + updated status
cancel_async_task停止正在运行的任务Confirmation
list_async_tasks列出所有被跟踪任务及其实时状态所有任务摘要
Supervisor 的 LLM 会像调用其他 tool 一样调用这些 tools。Middleware 会自动处理 thread 创建、run 管理和 state 持久化。

​
理解生命周期

典型交互遵循以下顺序：
  • Launch 会在 server 上创建新 thread，使用任务描述作为输入启动 run，并将 thread ID 作为 task ID 返回。Supervisor 会将此 ID 报告给用户，并且不会轮询完成状态。
  • Check 获取当前 run 状态。如果 run 成功，它会检索 thread state 以提取 subagent 的最终输出。如果仍在运行，则向用户报告该状态。
  • Update 使用 interrupt multitask strategy 在同一 thread 上创建新 run。之前的 run 会被中断，subagent 会带着完整对话历史和新指令重新启动。Task ID 保持不变。
  • Cancel 会在 server 上调用 runs.cancel()，并将任务标记为 "cancelled"。
  • List 遍历所有被跟踪任务。对于非终止任务，它会并行从 server 获取实时状态。终止状态（success、error、cancelled）从 cache 返回。

​
理解 state 管理

任务 metadata 存储在 supervisor graph 的专用 state channel（asyncTasks）中，与消息历史分离。这很关键，因为当上下文窗口填满时，deep agents 会压缩消息历史。如果 task ID 只存在于 tool messages 中，它们会在压缩期间丢失。专用 channel 确保 supervisor 即使经过多轮 summarization，也始终能通过 list_async_tasks 回忆自己的任务。 每个被跟踪任务都会记录 task ID、agent name、thread ID、run ID、status 和 timestamps（createdAt、checkedAt、updatedAt）。

​
选择 transport

​
ASGI transport（co-deployed）

当 subagent spec 省略 url 字段时，LangGraph SDK 会使用 ASGI transport，即 SDK calls 通过 in-process function calls 路由，而不是 HTTP。对于基于 LangGraph 的部署，这要求两个 graphs 都注册在同一个 langgraph.json 中。 ASGI transport 消除网络延迟，且不需要额外 auth 配置。Subagent 仍作为拥有自身 state 的独立 thread 运行。这是推荐的默认方式。

​
HTTP transport（remote）

添加 url 字段即可切换到 HTTP transport，此时 SDK calls 会通过网络发送到远程 Agent Protocol server： 
{
  name: "researcher",
  description: "Research agent",
  graphId: "researcher",
  url: "https://my-research-deployment.langsmith.dev",
}
对于 LangGraph deployments，认证由 LangGraph SDK 使用环境变量中的 LANGSMITH_API_KEY（或 LANGGRAPH_API_KEY）处理。Self-hosted Agent Protocol servers 可能使用不同认证机制。 当 subagents 需要独立扩缩容、不同资源配置，或由不同团队维护时，使用 HTTP transport。

​
选择部署拓扑

​
单一部署

单一部署意味着所有 agents 都使用 ASGI transport co-deploy 在同一 server 上。对于基于 LangGraph 的部署，请在一个 langgraph.json 中注册所有 graphs。这是推荐起点：一个 server 需要管理，agents 之间零网络延迟。

​
拆分部署

Supervisor 在一个 server 上，subagents 通过 HTTP transport 位于另一个 server 上。当 subagents 需要不同 compute profile 或独立扩缩容时使用。

​
Hybrid

在 hybrid deployment 中，一些 subagents 通过 ASGI co-deploy，另一些通过 HTTP remote： 
const asyncSubagents: AsyncSubAgent[] = [
  {
    name: "researcher",
    description: "Research agent",
    graphId: "researcher",
    // No url → ASGI (co-deployed)
  },
  {
    name: "coder",
    description: "Coding agent",
    graphId: "coder",
    url: "https://coder-deployment.langsmith.dev",
    // url present → HTTP (remote)
  },
];

​
最佳实践

​
为本地开发调整 worker pool 大小

使用 langgraph dev 在本地运行时，请增大 worker pool，以容纳并发 subagent runs。每个活动 run 占用一个 worker slot。一个带有 3 个并发 subagent tasks 的 supervisor 需要 4 个 slots（1 个 supervisor + 3 个 subagents）。配置不足会导致 launch 排队。 
langgraph dev --n-jobs-per-worker 10

​
编写清晰的 subagent descriptions

Supervisor 使用 descriptions 决定启动哪个 subagent。请具体且行动导向： 
// Good
{
  name: "researcher",
  description: "Conducts in-depth research using web search. Use for questions requiring multiple searches and synthesis.",
  graphId: "researcher",
}

// Bad
{
  name: "helper",
  description: "helps with stuff",
  graphId: "helper",
}

​
使用 thread IDs 进行 tracing

使用基于 LangGraph 的部署时，每个异步 subagent run 都是标准 LangGraph run，并且在 LangSmith 中完全可见。Supervisor trace 会显示 launch、check、update、cancel 和 list 的 tool calls。每个 subagent run 都会作为单独 trace 出现，并由 thread ID 链接。使用 thread ID（task ID）关联 supervisor 编排 trace 和 subagent 执行 trace。

​
故障排除

​
Supervisor 在 launch 后立即轮询

问题：Supervisor 在启动后立即循环调用 check，把异步执行变成阻塞执行。 解决方案：Middleware 会注入 system prompt rules 以防止这种情况。如果轮询仍然存在，请在 supervisor 的 system prompt 中强化该行为： 
const agent = createDeepAgent({
  model: "google_genai:gemini-3.5-flash",
  systemPrompt: `...your instructions...

    After launching an async subagent, ALWAYS return control to the user.
    Never call check_async_task immediately after launch.`,
  subagents: [...asyncSubagents],
});

​
Supervisor 报告过期状态

问题：Supervisor 引用了对话历史中较早的任务状态，而不是重新调用 check。 解决方案：Middleware prompt 会指示模型 “task statuses in conversation history are always stale”。如果仍然发生，请添加显式指令，要求在报告状态前始终调用 check 或 list。

​
Task ID 查找失败

问题：Supervisor 截断或重新格式化 task ID，导致 check 或 cancel 失败。 解决方案：Middleware prompt 会指示模型始终使用完整 task ID。如果仍然发生截断，这通常是模型特定问题，请尝试其他模型，或在 system prompt 中添加 “always show the full task_id, never truncate or abbreviate it”。

​
Subagent launch 排队而不是运行

问题：启动 subagent 挂起或需要很长时间才能开始。 解决方案：Worker pool 可能已经耗尽。使用 --n-jobs-per-worker 增大 pool size。请参阅调整 worker pool 大小。

​
参考实现

async-deep-agents 仓库包含可部署到 LangSmith Deployments 的 Python 和 TypeScript 工作示例。它演示了一个带 researcher 和 coder subagents 的 supervisor，这些 subagents 以后台任务运行。
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.
Edit this page on GitHub or file an issue.