异步子代理是
deepagents 0.5.0 中可用的预览功能。预览功能正在积极开发中，API 可能会发生变化。异步子代理可以与任何实现了 Agent Protocol 的服务器通信。您可以使用 LangSmith 部署，或自行托管任何兼容 Agent Protocol 的服务器。每个子代理独立于主管运行，主管通过 SDK 控制它们来启动、检查、更新和取消。
何时使用异步子代理
配置异步子代理
将异步子代理定义为一组AsyncSubAgent 规范，每个规范指向一个 Agent Protocol 服务器：
对于基于 LangGraph 的部署，在同一个
langgraph.json 中注册所有图以实现共部署：
使用异步子代理工具
当配置了异步子代理时，包含在默认中间件栈中的 @[AsyncSubagentMiddleware] 会为主管提供五个工具：
主管的 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 调用将通过网络到达远程 Agent Protocol 服务器：
LANGSMITH_API_KEY（或 LANGGRAPH_API_KEY）处理。自托管的 Agent Protocol 服务器可能使用不同的身份验证机制。
当子代理需要独立扩展、不同的资源配置或由不同团队维护时，请使用 HTTP 传输。
选择部署拓扑
单一部署
单一部署意味着所有代理都使用 ASGI 传输共部署在同一台服务器上。对于基于 LangGraph 的部署，在一个langgraph.json 中注册所有图。这是推荐的起点 —— 只需管理一台服务器，代理之间零网络延迟。
分离部署
主管在一台服务器上，子代理通过 HTTP 传输在另一台上。当子代理需要不同的计算配置或独立扩展时使用。混合部署
在混合部署中，一些子代理通过 ASGI 共部署，另一些通过 HTTP 远程部署：最佳实践
为本地开发调整工作线程池大小
使用langgraph dev 在本地运行时，增加工作线程池以容纳并发的子代理运行。每个活跃的运行占用一个工作线程槽位。一个拥有 3 个并发子代理任务的主管需要 4 个槽位（1 个主管 + 3 个子代理）。配置不足会导致启动排队。
编写清晰的子代理描述
主管使用描述来决定启动哪个子代理。请具体且以行动为导向：使用线程 ID 进行追踪
使用基于 LangGraph 的部署时，每个异步子代理运行都是一个标准的 LangGraph 运行，在 LangSmith 中完全可见。主管的追踪显示launch、check、update、cancel 和 list 的工具调用。每个子代理运行都显示为一个单独的追踪，通过线程 ID 链接。使用线程 ID（任务 ID）来关联主管的编排追踪和子代理的执行追踪。
故障排除
主管在启动后立即轮询
问题：主管在启动后立即循环调用check，将异步执行变成了阻塞执行。
解决方案：中间件注入系统提示规则来防止这种情况。如果轮询仍然存在，请在您的主管系统提示中强化此行为：
主管报告过时状态
问题：主管引用了对话历史中较早的任务状态，而不是进行新的check 调用。
解决方案：中间件提示指示模型“对话历史中的任务状态总是过时的”。如果仍然发生，请添加明确的指示，要求在报告状态前总是调用 check 或 list。
任务 ID 查找失败
问题：主管截断或重新格式化任务 ID，导致check 或 cancel 失败。
解决方案：中间件提示指示模型始终使用完整的任务 ID。如果截断持续存在，这通常是特定模型的问题 —— 请尝试不同的模型，或在您的系统提示中添加“始终显示完整的 task_id，永远不要截断或缩写它”。
子代理启动排队而非运行
问题：启动子代理挂起或需要很长时间才能开始。 解决方案：工作线程池可能已耗尽。使用--n-jobs-per-worker 增加池大小。请参阅调整工作线程池大小。
参考实现
async-deep-agents 仓库包含 Python 和 TypeScript 的工作示例，可部署到 LangSmith Deployments。它演示了一个主管，其研究员和程序员子代理作为后台任务运行。Connect these docs to Claude, VSCode, and more via MCP for real-time answers.