异步子智能体让主管智能体启动立即返回的后台任务，这样主管可以在子智能体并发工作的同时继续与用户交互。主管可以随时检查进度、发送后续指令或取消任务。 这建立在子智能体的基础上，子智能体同步运行并阻塞主管直到完成。当任务是长时间运行的、可并行的或需要中途转向时，使用异步子智能体。
异步子智能体是 deepagents 0.5.0 中的预览功能。预览功能正在积极开发中，API 可能会发生变化。
异步子智能体与任何实现 智能体协议 的服务器通信。您可以使用 LangSmith Deployments，或自托管任何智能体协议兼容的服务器。每个子智能体独立于主管运行，主管通过 SDK 控制它们来启动、检查、更新和取消。

​
何时使用异步子智能体

维度同步子智能体异步子智能体
执行模型主管阻塞直到子智能体完成立即返回任务 ID；主管继续
并发性并行但阻塞并行且非阻塞
中途更新不可能通过 update_async_task 发送后续指令
取消不可能通过 cancel_async_task 取消运行中的任务
有状态性无状态 - 调用之间无持久状态有状态 - 在跨交互的自己的线程上维护状态
适用于智能体应等待结果后再继续的任务在聊天中交互管理的长时间运行的复杂任务

​
配置异步子智能体

将异步子智能体定义为 AsyncSubAgent 规范的列表，每个都指向一个智能体协议服务器： 
from deepagents import AsyncSubAgent, create_deep_agent

async_subagents = [
    AsyncSubAgent(
        name="researcher",
        description="用于信息收集和综合的研究智能体",
        graph_id="researcher",
        # 无 url → ASGI 传输（共同部署在同一部署中）
    ),
    AsyncSubAgent(
        name="coder",
        description="用于代码生成和审查的编码智能体",
        graph_id="coder",
        # url="https://coder-deployment.langsmith.dev"  # 可选：远程 HTTP 传输
    ),
]

agent = create_deep_agent(
    model="claude-sonnet-4-6",
    subagents=async_subagents,
)
字段类型描述
namestr必需。唯一标识符。主管在启动任务时使用此名称。
descriptionstr必需。此子智能体的用途。主管使用此描述来决定委托给哪个智能体。
graph_idstr必需。智能体协议服务器上的图形 ID（或助手 ID）。对于基于 LangGraph 的部署，这必须与 langgraph.json 中注册的图形匹配。
urlstr可选。省略时使用 ASGI 传输（进程内）。设置时使用 HTTP 传输到远程智能体协议服务器。
headersdict[str, str]可选。发送到远程服务器的附加请求头。用于自托管智能体协议服务器的自定义身份验证。
对于基于 LangGraph 的部署，为共同部署设置在同一个 langgraph.json 中注册所有图形： 
{
  "graphs": {
    "supervisor": "./src/supervisor.py:graph",
    "researcher": "./src/researcher.py:graph",
    "coder": "./src/coder.py:graph"
  }
}

​
使用异步子智能体工具

AsyncSubAgentMiddleware 为主管提供五个工具：
工具用途返回值
start_async_task启动新的后台任务任务 ID（立即返回）
check_async_task获取任务的当前状态和结果状态 + 结果（如已完成）
update_async_task向运行中的任务发送新指令确认 + 更新后的状态
cancel_async_task停止运行中的任务确认
list_async_tasks列出所有跟踪的任务及其实时状态所有任务的摘要
主管的 LLM 像调用任何其他工具一样调用这些工具。中间件自动处理线程创建、运行管理和状态持久化。

​
理解生命周期

典型的交互遵循此序列：
  • 启动 在服务器上创建一个新线程，使用任务描述作为输入开始运行，并返回线程 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 调用通过网络发送到远程智能体协议服务器： 
AsyncSubAgent(
    name="researcher",
    description="研究智能体",
    graph_id="researcher",
    url="https://my-research-deployment.langsmith.dev",
)
对于 LangGraph 部署，身份验证由 LangGraph SDK 使用环境变量中的 LANGSMITH_API_KEY（或 LANGGRAPH_API_KEY）处理。自托管智能体协议服务器可能使用不同的身份验证机制。 当子智能体需要独立扩展、不同的资源配置文件或由不同团队维护时，使用 HTTP 传输。

​
选择部署拓扑

​
单个部署

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

​
分离部署

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

​
混合部署

在混合部署中，某些子智能体通过 ASGI 共同部署，其他通过 HTTP 远程部署： 
async_subagents = [
    AsyncSubAgent(
        name="researcher",
        description="研究智能体",
        graph_id="researcher",
        # 无 url → ASGI（共同部署）
    ),
    AsyncSubAgent(
        name="coder",
        description="编码智能体",
        graph_id="coder",
        url="https://coder-deployment.langsmith.dev",
        # 有 url → HTTP（远程）
    ),
]

​
最佳实践

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

使用 langgraph dev 本地运行时，增加工作池以容纳并发子智能体运行。每个活动运行占用一个工作槽。具有 3 个并发子智能体任务的主管需要 4 个槽（1 个主管 + 3 个子智能体）。资源不足会导致启动排队。 
langgraph dev --n-jobs-per-worker 10

​
编写清晰的子智能体描述

主管使用描述来决定启动哪个子智能体。要具体且以动作为导向： 
# 好
AsyncSubAgent(
    name="researcher",
    description="使用网络搜索进行深入研究。用于需要多次搜索和综合的问题。",
    graph_id="researcher",
)

# 差
AsyncSubAgent(
    name="helper",
    description="帮忙处理事情",
    graph_id="helper",
)

​
使用线程 ID 进行追踪

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

​
故障排除

​
主管在启动后立即轮询

问题：主管在启动后立即循环调用 check，将异步执行变成阻塞执行。 解决方案：中间件注入系统提示规则以防止这种情况。如果轮询仍然存在，在主管的系统提示中强化行为： 
agent = create_deep_agent(
    model="claude-sonnet-4-6",
    system_prompt="""...您的指令...

    启动异步子智能体后，始终将控制权返回给用户。
    启动后永远不要立即调用 check_async_task。""",
    subagents=async_subagents,
)

​
主管报告过时的状态

问题：主管引用对话历史中较早的任务状态，而不是进行新的 check 调用。 解决方案：中间件提示告诉模型”对话历史中的任务状态始终是过时的”。如果仍然发生，添加明确的指令以始终在报告状态之前调用 check 或 list。

​
任务 ID 查找失败

问题：主管截断或重新格式化任务 ID，导致 check 或 cancel 失败。 解决方案：中间件提示指示模型始终使用完整的任务 ID。如果截断仍然存在，这通常是模型特定的问题——尝试不同的模型或在系统提示中添加”始终显示完整的 task_id，永远不要截断或缩写它”。

​
子智能体启动排队而不是运行

问题：启动子智能体挂起或启动时间很长。 解决方案：工作池可能已耗尽。使用 --n-jobs-per-worker 增加池大小。请参阅调整工作池大小。

​
参考实现

async-deep-agents 仓库包含 Python 和 TypeScript 中的工作示例，部署到 LangSmith Deployments。它演示了一个主管与研究员和程序员子智能体作为后台任务运行。
在 GitHub 上编辑此页面 或提交问题。
通过 MCP 将这些文档 连接到 Claude、VSCode 等，获取实时答案。