跳到主要内容

文档索引

在以下地址获取完整的文档索引：https://docs.langchain.org.cn/llms.txt

在进一步探索之前，请使用此文件发现所有可用页面。

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

​
何时使用异步子代理

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

​
配置异步子代理

将异步子代理定义为AsyncSubAgent规范的列表，每个规范指向一个代理协议服务器 
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.1-pro-preview",
  subagents: [...asyncSubagents],
});
字段类型描述
名称字符串必填。唯一标识符。主管在启动任务时使用此标识符。
description字符串必填。此子代理的功能。主管使用此信息来决定将任务委托给哪个代理。
graphId字符串必填。代理协议服务器上的图ID（或助手ID）。对于基于 LangGraph 的部署，这必须与 langgraph.json 中注册的图匹配。
URL字符串可选。省略时，使用 ASGI 传输（进程内）。设置时，使用 HTTP 传输到远程代理协议服务器。
headersRecord<string, string>可选。发送到远程服务器的请求的附加标头。用于自托管代理协议服务器的自定义身份验证。
对于基于 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）从缓存中返回。

​
理解状态管理

任务元数据存储在主管图上的专用状态通道（asyncTasks）中，与消息历史记录分开。这至关重要，因为当上下文窗口填满时，深度代理会压缩其消息历史记录。如果任务 ID 仅存在于工具消息中，它们将在压缩期间丢失。专用通道确保主管即使在多轮摘要后也能通过list_async_tasks始终回忆起其任务。 每个跟踪的任务都记录任务 ID、代理名称、线程 ID、运行 ID、状态和时间戳（createdAt、checkedAt、updatedAt）。

​
选择传输方式

​
ASGI 传输（协同部署）

当子代理规范省略url字段时，LangGraph SDK 使用 ASGI 传输——SDK 调用通过进程内函数调用而不是 HTTP 进行路由。对于基于 LangGraph 的部署，这要求两个图都在同一个langgraph.json中注册。 ASGI 传输消除了网络延迟，无需额外的身份验证配置。子代理仍作为具有其自身状态的独立线程运行。这是推荐的默认设置。

​
HTTP 传输（远程）

添加url字段以切换到 HTTP 传输，其中 SDK 调用通过网络发送到远程代理协议服务器 
{
  name: "researcher",
  description: "Research agent",
  graphId: "researcher",
  url: "https://my-research-deployment.langsmith.dev",
}
对于 LangGraph 部署，身份验证由 LangGraph SDK 使用环境变量中的LANGSMITH_API_KEY（或LANGGRAPH_API_KEY）处理。自托管代理协议服务器可能使用不同的身份验证机制。 当子代理需要独立扩展、不同的资源配置文件或由不同团队维护时，请使用 HTTP 传输。

​
选择部署拓扑

​
单一部署

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

​
分离部署

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

​
混合

在分离部署中，主管部署在一个服务器上，子代理通过 HTTP 传输部署在另一个服务器上。当子代理需要不同的计算配置文件或独立扩展时使用。

​
混合

在混合部署中，一些子代理通过 ASGI 协同部署，另一些则通过 HTTP 远程部署 
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)
  },
];

​
最佳实践

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

使用langgraph dev在本地运行时，增加工作进程池以适应并发的子代理运行。每个活跃运行占用一个工作进程槽。一个拥有 3 个并发子代理任务的主管需要 4 个槽（1 个主管 + 3 个子代理）。资源配置不足会导致启动排队。 
langgraph dev --n-jobs-per-worker 10

​
编写清晰的子代理描述

主管使用描述来决定启动哪个子代理。请具体化并面向行动 
// 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",
}

​
使用线程ID进行追踪

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

​
故障排除

​
主管在启动后立即轮询

问题：主管在启动后立即循环调用check，将异步执行变为阻塞。 解决方案：中间件注入系统提示规则以防止这种情况。如果轮询仍然存在，请在主管的系统提示中强化此行为：
const agent = createDeepAgent({
  model: "google_genai:gemini-3.1-pro-preview",
  systemPrompt: `...your instructions...

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

​
主管报告过时状态

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

​
任务ID查找失败

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

​
子代理启动时排队而非立即运行

问题：启动子代理挂起或需要很长时间才能开始。 解决方案：工作进程池可能已耗尽。使用--n-jobs-per-worker增加池大小。请参阅调整工作进程池大小。

​
参考实现

async-deep-agents 存储库包含 Python 和 TypeScript 的工作示例，它们部署到 LangSmith Deployments。它展示了一个主管，其中包含作为后台任务运行的研究员和编码员子代理。
将这些文档连接到 Claude、VSCode 等，以获得实时答案。
在 GitHub 上编辑此页面 或 提出问题。
© . This site is unofficial and not affiliated with LangChain, Inc.