跳到主要内容

文档索引

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

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

异步子智能体允许主管智能体启动后台任务，并立即返回，从而使主管可以在子智能体并发工作时继续与用户交互。主管可以在任何时候检查进度、发送后续指令或取消任务。 这是建立在子智能体（同步运行并阻塞主管直到完成）基础之上的。当任务运行时间长、可并行化或需要中途干预时，请使用异步子智能体。
异步子智能体是 deepagents 0.5.0 中的预览功能。预览功能处于积极开发阶段，API 可能会有所变化。
异步子智能体可以与任何实现了 Agent Protocol（智能体协议） 的服务器通信。你可以使用 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",
        # 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.1-pro-preview",
    subagents=async_subagents,
)
字段类型描述
名称str必需。唯一标识符。主管在启动任务时使用它。
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 像调用其他工具一样调用这些工具。中间件会自动处理线程创建、运行管理和状态持久化。

​
理解生命周期

典型的交互遵循以下顺序
  • 启动 (Launch)：在服务器上创建一个新线程，以任务描述作为输入启动运行，并返回线程 ID 作为任务 ID。主管将此 ID 报告给用户，且不会轮询完成情况。
  • 检查 (Check)：获取当前运行状态。如果运行成功，它会检索线程状态以提取子智能体的最终输出。如果仍在运行，则向用户报告该状态。
  • 更新 (Update)：在同一线程上使用中断多任务策略创建新的运行。之前的运行被中断，子智能体在完整的对话历史记录加上新指令的情况下重新启动。任务 ID 保持不变。
  • 取消 (Cancel)：在服务器上调用 runs.cancel() 并将任务标记为 "cancelled"。
  • 列表 (List)：遍历所有已跟踪的任务。对于非终结状态的任务，它会并行从服务器获取实时状态。终结状态（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 传输在另一台服务器上。当子智能体需要不同的计算配置文件或独立扩展时使用。

​
混合

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

​
混合

在混合部署中，部分子智能体通过 ASGI 共同部署，其他则通过 HTTP 远程部署 
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)
    ),
]

​
最佳实践

​
本地开发时的 Worker 池大小调整

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

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

主管使用描述来决定启动哪个子智能体。请务必具体且以行动为导向 
# Good
AsyncSubAgent(
    name="researcher",
    description="Conducts in-depth research using web search. Use for questions requiring multiple searches and synthesis.",
    graph_id="researcher",
)

# Bad
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，切勿截断或缩写”。

​
子智能体启动排队而非立即运行

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

​
参考实现

async-deep-agents 仓库包含可部署到 LangSmith 部署的 Python 和 TypeScript 工作示例。它演示了一个带有研究员和程序员子智能体作为后台任务运行的主管。
将这些文档连接到 Claude、VSCode 等，以获得实时答案。
在 GitHub 上编辑此页面 或 提交问题。
© . This site is unofficial and not affiliated with LangChain, Inc.