异步子智能体

启动在后台并发运行的子智能体，同时主管继续与用户交互

异步子智能体让主管智能体能够启动立即返回的后台任务，这样当子智能体并发工作时，主管可以继续与用户交互。主管可以随时检查进度、发送后续指令或取消任务。

这建立在子智能体之上，后者同步运行，并会阻塞主管直到完成。当任务长时间运行、可并行处理或需要中途引导时，请使用异步子智能体。

graph TB
    User([User]) --> Supervisor[Supervisor Agent]

    Supervisor --> |launch| Researcher[Researcher]
    Supervisor --> |launch| Coder[Coder]

    Researcher --> |check| Supervisor
    Coder --> |check| Supervisor

NOTE

异步子智能体可与任何实现了 Agent Protocol 的服务器通信。你可以使用 LangSmith Deployments，也可以自行托管任何兼容 Agent Protocol 的服务器。每个子智能体都独立于主管运行，主管通过 SDK 对其进行控制，以启动、检查、更新和取消任务。

何时使用异步子智能体

维度	同步子智能体	异步子智能体
执行模型	主管会阻塞直到子智能体完成	立即返回作业 ID；主管继续运行
并发性	并行但阻塞	并行且非阻塞
任务中途更新	无法实现	通过 update_async_task 发送后续指令
取消	无法实现	通过 cancel_async_task 取消正在运行的任务
有状态性	无状态 -- 调用之间没有持久状态	有状态 -- 在自身线程上跨多次交互维护状态
最适合	智能体在继续之前应等待结果的任务	在聊天中以交互方式管理的长时间运行的复杂任务

配置异步子智能体

将异步子智能体定义为一组 AsyncSubAgent 规格，每一项都指向一个 Agent Protocol 服务器：

from deepagents import AsyncSubAgent, create_deep_agent

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

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    subagents=async_subagents,
)

字段	类型	描述
name	str	必填。唯一标识符。主管在启动任务时使用它。
description	str	必填。此子智能体的功能。主管用它来决定委派给哪个智能体。
graph_id	str	必填。Agent Protocol 服务器上的图 ID（或助手 ID）。对于基于 LangGraph 的部署，它必须与 langgraph.json 中注册的某个图匹配。
url	str	可选。省略时使用 ASGI 传输（进程内）。设置后使用 HTTP 传输到远程 Agent Protocol 服务器。
headers	dict[str, str]	可选。向远程服务器发送请求时附加的请求头。用于对自行托管的 Agent Protocol 服务器进行自定义身份认证。

对于基于 LangGraph 的部署，请在同一个 langgraph.json 中注册所有图，以支持共同部署的设置：

{
  "graphs": {
    "supervisor": "./src/supervisor.py:graph",
    "researcher": "./src/researcher.py:graph",
    "coder": "./src/coder.py:graph"
  }
}

使用异步子智能体工具

当配置了异步子智能体时，Deep Agents 技术栈中会包含 AsyncSubAgentMiddleware，它为主管提供五个工具：

工具	用途	返回
start_async_task	启动一个新的后台任务	任务 ID（立即返回）
check_async_task	获取任务的当前状态和结果	状态 + 结果（如果已完成）
update_async_task	向正在运行的任务发送新指令	确认 + 更新后的状态
cancel_async_task	停止正在运行的任务	确认
list_async_tasks	列出所有被跟踪的任务及其实时状态	所有任务的摘要

主管的 LLM 可以像调用任何其他工具一样调用这些工具。中间件会自动处理线程创建、运行管理和状态持久化。

理解生命周期

一次典型的交互遵循以下顺序：

sequenceDiagram
    participant User
    participant Supervisor
    participant Platform as Agent Protocol Server

    User->>Supervisor: "Research topic X"
    Supervisor->>Platform: launch(researcher, "topic X")
    Platform-->>Supervisor: task_id: abc123

    Note over Platform: Researcher working...

    Supervisor-->>User: "Started task abc123"

    Note over User,Platform: User continues conversation

    User->>Supervisor: "How's the research going?"
    Supervisor->>Platform: check(abc123)
    Platform-->>Supervisor: status: success, result: "findings..."
    Supervisor-->>User: "Here are the results"

• 启动 在服务器上创建一个新线程，以任务描述作为输入启动一次运行，并将线程 ID 作为任务 ID 返回。主管将这个 ID 报告给用户，并且不会轮询是否完成。
• 检查 获取当前运行状态。如果运行成功，它会获取线程状态以提取子智能体的最终输出。如果仍在运行，它会将这一情况报告给用户。
• 更新 使用中断多任务策略在同一线程上创建一次新的运行。上一次运行被中断，子智能体带着完整对话历史以及新指令重新启动。任务 ID 保持不变。
• 取消 在服务器上调用 runs.cancel() 并将任务标记为 "cancelled"。
• 列出 遍历所有被跟踪的任务。对于非终态任务，它会并行地从服务器获取实时状态。终态状态（success、error、cancelled）从缓存中返回。

理解状态管理

任务元数据存储在主管图上一个专用的状态通道（async_tasks）中，与消息历史分开。这一点至关重要，因为深度智能体在上下文窗口填满时会压缩其消息历史。如果任务 ID 只存在于工具消息中，它们会在压缩过程中丢失。专用通道确保主管始终可以通过 list_async_tasks 召回其任务，即使经过多轮摘要之后也是如此。

每个被跟踪的任务都会记录任务 ID、智能体名称、线程 ID、运行 ID、状态以及时间戳（created_at、last_checked_at、last_updated_at）。

选择传输方式

ASGI 传输（共同部署）

当子智能体规格省略 url 字段时，LangGraph SDK 使用 ASGI 传输 -- SDK 调用通过进程内函数调用而非 HTTP 进行路由。对于基于 LangGraph 的部署，这要求两个图都注册在同一个 langgraph.json 中。

ASGI 传输消除了网络延迟，且无需额外的身份认证配置。子智能体仍作为具有自身状态的独立线程运行。这是推荐的默认方式。

HTTP 传输（远程）

添加 url 字段即可切换到 HTTP 传输，此时 SDK 调用会通过网络发往远程 Agent Protocol 服务器：

from deepagents import AsyncSubAgent

AsyncSubAgent(
    name="researcher",
    description="Research agent",
    graph_id="researcher",
    url="https://my-research-deployment.langsmith.dev",
)

对于 LangGraph 部署，身份认证由 LangGraph SDK 使用环境变量中的 LANGSMITH_API_KEY（或 LANGGRAPH_API_KEY）来处理。自行托管的 Agent Protocol 服务器可能使用不同的身份认证机制。

当子智能体需要独立扩展、不同的资源配置，或由不同团队维护时，请使用 HTTP 传输。

选择部署拓扑

单一部署

单一部署意味着所有智能体都使用 ASGI 传输共同部署在同一台服务器上。对于基于 LangGraph 的部署，请将所有图注册在一个 langgraph.json 中。这是推荐的起点 -- 只需管理一台服务器，智能体之间零网络延迟。

拆分部署

主管位于一台服务器，子智能体通过 HTTP 传输位于另一台服务器。当子智能体需要不同的计算配置或独立扩展时使用。

混合

在混合部署中，部分子智能体通过 ASGI 共同部署，其他子智能体则通过 HTTP 远程部署：

from deepagents import AsyncSubAgent

async_subagents = [
    AsyncSubAgent(
        name="researcher",
        description="Research agent",
        graph_id="researcher",
        # No url → ASGI (co-deployed)
    ),
    AsyncSubAgent(
        name="coder",
        description="Coding agent",
        graph_id="coder",
        url="https://coder-deployment.langsmith.dev",
        # url present → HTTP (remote)
    ),
]

最佳实践

为本地开发调整工作进程池大小

在本地使用 langgraph dev 运行时，请增大工作进程池以容纳并发的子智能体运行。每个活动运行都会占用一个工作进程槽位。一个带有 3 个并发子智能体任务的主管需要 4 个槽位（1 个主管 + 3 个子智能体）。配置不足会导致启动排队。

langgraph dev --n-jobs-per-worker 10

编写清晰的子智能体描述

主管使用描述来决定启动哪个子智能体。请具体且以行动为导向：

Good

from deepagents import AsyncSubAgent

AsyncSubAgent(
    name="researcher",
    description="Conducts in-depth research using web search. Use for questions requiring multiple searches and synthesis.",
    graph_id="researcher",
)

Bad

from deepagents import AsyncSubAgent

AsyncSubAgent(
    name="helper",
    description="helps with stuff",
    graph_id="helper",
)

使用线程 ID 进行追踪

使用基于 LangGraph 的部署时，每次异步子智能体运行都是一次标准的 LangGraph 运行，在 LangSmith 中完全可见。主管的追踪显示 launch、check、update、cancel 和 list 的工具调用。每个子智能体运行都会出现在单独的追踪中，并通过线程 ID 关联。使用线程 ID（任务 ID）将主管编排追踪与子智能体执行追踪关联起来。

故障排查

主管在启动后立即轮询

问题：主管在启动后立即循环调用 check，使异步执行变成了阻塞。

解决方案：中间件会注入系统提示词规则来防止这种情况。如果轮询仍然存在，请在主管的系统提示词中强化这一行为：

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    system_prompt="""...your instructions...

    After launching an async subagent, ALWAYS return control to the user.
    Never call check_async_task immediately after launch.""",
    subagents=async_subagents,
)

主管报告过时的状态

问题：主管引用对话历史中较早的任务状态，而不是发起新的 check 调用。

解决方案：中间件提示词会指示模型「对话历史中的任务状态始终是过时的」。如果这种情况仍然发生，请添加明确指令，要求始终在报告状态之前调用 check 或 list。

任务 ID 查找失败

问题：主管截断或重新格式化了任务 ID，导致 check 或 cancel 失败。

解决方案：中间件提示词会指示模型始终使用完整的任务 ID。如果截断问题仍然存在，这通常是特定于模型的问题 -- 尝试换一个模型，或在系统提示词中添加「始终显示完整的 task_id，绝不截断或缩写它」。

子智能体启动排队而非直接运行

问题：启动子智能体时挂起或需要很长时间才能开始。

解决方案：工作进程池很可能已耗尽。使用 --n-jobs-per-worker 增大池的大小。参见为本地开发调整工作进程池大小。

参考实现

async-deep-agents 仓库包含可运行的 Python 和 TypeScript 示例，可部署到 LangSmith Deployments。它演示了一个带有 researcher 和 coder 子智能体、以后台任务方式运行的主管。

---