Skip to main content
异步子代理允许主管代理启动后台任务，这些任务会立即返回，因此主管代理可以在子代理并发工作的同时继续与用户交互。主管代理可以随时检查进度、发送后续指令或取消任务。 这建立在子代理的基础上，子代理同步运行并阻塞主管代理直到完成。当任务耗时较长、可并行处理或需要中途调整时，请使用异步子代理。
异步子代理是 deepagents 0.5.0 中提供的预览功能。预览功能正在积极开发中，API 可能会发生变化。
异步子代理可与任何实现代理协议的服务器通信。您可以使用 LangSmith 部署，或自托管任何兼容代理协议的服务器。每个子代理独立于主管代理运行，主管代理通过 SDK 控制它们以启动、检查、更新和取消。

​
何时使用异步子代理

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

​
配置异步子代理

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

async_subagents = [
    AsyncSubAgent(
        name="researcher",
        description="Research agent for information gathering and synthesis",
        graph_id="researcher",
        # 无 url → ASGI 传输（在同一部署中共部署）
    ),
    AsyncSubAgent(
        name="coder",
        description="Coding agent for code generation and review",
        graph_id="coder",
        # url="https://coder-deployment.langsmith.dev"  # 可选：用于远程的 HTTP 传输
    ),
]

agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    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="Research agent",
    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="Research agent",
        graph_id="researcher",
        # 无 url → ASGI（共部署）
    ),
    AsyncSubAgent(
        name="coder",
        description="Coding agent",
        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="Conducts in-depth research using web search. Use for questions requiring multiple searches and synthesis.",
    graph_id="researcher",
)

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

​
使用线程 ID 进行跟踪

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

​
故障排除

​
主管代理在启动后立即轮询

问题：主管代理在启动后立即循环调用 check，将异步执行变为阻塞。 解决方案：中间件注入系统提示规则以防止这种情况。如果轮询持续存在，请在主管代理的系统提示中强化此行为： 
agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    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 部署。它演示了一个主管代理，其研究员和编码员子代理作为后台任务运行。
将这些文档连接到 Claude、VSCode 等，通过 MCP 获取实时答案。
在 GitHub 上编辑此页面 或 提交问题。