03 Async subagents：后台跑的子智能体（启动、轮询、中途干预）

同步 vs 异步：原文那张对照表#

时间轴：一次真实交互长什么样#

1
时间往下走（主管视角）
2
T0  用户 → 主管: "把这份合同审一下，顺便查下对手公司背景"
3
T1  主管 → start_async_task("审合同", "legal_reviewer")
4
                  └─ 立刻返回 task_id: 7f3a9c（= 服务器上的 thread_id）
5
T2  主管 → 用户: "已开始审查（任务 ID 7f3a9c），你先忙别的"  ← 交回控制权
6
T3  用户 → 主管: "那先聊点别的"   ← 同步子智能体永远到不了这一步
7
T4  用户 → 主管: "审得怎么样了？" → check_async_task("7f3a9c") → running
8
T5  用户 → 主管: "方向改一下，重点看违约金条款"
9
    主管 → update_async_task("7f3a9c", "重点看违约金")   ← 中途干预
10
         （旧 run 被打断，带完整历史 + 新指令重启，task_id 不变）
11
T6  用户 → 主管: "算了别审了" → cancel_async_task("7f3a9c") → cancelled
12
T7  用户 → 主管: "刚发的背景调研呢？"
13
    主管 → check_async_task("b21e04") → success + result  ← 拿结果
14
T8  主管 → 用户: 把结果整理成人话汇报

和 04 篇的”同步子智能体”对照着看#

04 篇那个”三工具模式”（start / status / get result）就是这套东西的极简版；Deep Agents 把它做成了 5 个工具 + 一个中间件 + 一个专用状态通道。

AsyncSubAgent 的字段#

同部署时的 langgraph.json#

LangGraph 部署里，被同部署（co-deployed）的图都要注册在同一个 langgraph.json：

1
{
2
  "graphs": {
3
    "supervisor": "./src/supervisor.py:graph",
4
    "researcher": "./src/researcher.py:graph",
5
    "coder": "./src/coder.py:graph"
6
  }
7
}

这不是可选项：ASGI 传输要求两边在同一份注册表里，否则主管按 graph_id 找不到图。

和静态 SubAgent 的差异（01 篇 对照）#

生命周期状态机#

1
stateDiagram-v2
2
    [*] --> running: start_async_task 新建 thread + run，返回 task_id
3
    running --> running: update_async_task 打断旧 run，带历史 + 新指令重启
4
    running --> success: run 成功，check 时从 thread state 取最终输出
5
    running --> error: run 失败，返回错误信息
6
    running --> cancelled: cancel_async_task 调服务器 runs.cancel()
7
    success --> [*]
8
    error --> [*]
9
    cancelled --> [*]

终态（terminal）就是不会再变的状态。原文明确列了 success、error、cancelled；本机 0.7.5 源码里这个集合是 {cancelled, success, error, timeout, interrupted}——多出来的 timeout / interrupted 属于 SDK 侧状态，原文未提及。

五个动作在服务器上各自做了什么（原文逐个说明）#

• Launch（启动）：在服务器上新建一条 thread，用任务描述作为输入起一个 run，把 thread ID 当 task ID 返回。主管把 ID 报给用户，然后不去轮询等完成。
• Check（查询）：拉当前 run 状态。run 成功了就再取一次 thread state 抽出子智能体的最终输出；还在跑就如实告诉用户还在跑。
• Update（更新）：在同一条 thread 上用 interrupt 多任务策略起一个新 run。旧 run 被打断，子智能体带完整对话历史 + 新指令重启，task ID 不变。
• Cancel（取消）：在服务器上调 runs.cancel()，并把任务标记为 "cancelled"。
• List（列表）：遍历所有被跟踪任务；非终态任务并发去服务器拉实时状态，终态任务直接返回缓存值（省一次网络往返）。

看第 3 条：update 不是”追加一条消息就完了”，而是打断重启。这解释了为什么干预后子智能体还记得前面聊过什么（历史在），也解释了为什么干预本身有成本（一次新 run）。

ASGI 传输（同进程部署）#

规格里不写 url 就用 ASGI 传输：LangGraph SDK 的调用被路由成进程内函数调用，不走 HTTP。LangGraph 部署下要求两张图注册在同一个 langgraph.json。

原文给的结论：省掉网络延迟；不需要额外认证配置；子智能体仍是独立的一条 thread，有自己的状态（不是”变成一次函数调用就没状态了”）；这是推荐的默认选择。

HTTP 传输（远端）#

加个 url 字段就切到 HTTP 传输，SDK 调用走网络打到远端 Agent Protocol 服务器：

1
from deepagents import AsyncSubAgent
2

3
AsyncSubAgent(
4
    name="researcher",
5
    description="Research agent",
6
    graph_id="researcher",
7
    url="https://my-research-deployment.langsmith.dev",
8
)

认证方面（原文）：LangGraph 部署由 SDK 用环境变量 LANGSMITH_API_KEY（或 LANGGRAPH_API_KEY）自动处理；自建的 Agent Protocol 服务器可能用别的认证机制。

什么时候值得付这份网络和运维成本：子智能体要独立扩缩容、资源画像不同（比如要 GPU）、或者干脆是别的团队维护的。

两种传输方式对照#

⚠️ 警告（本机 0.7.5 源码观察，原文未说明）：ASGI 传输（url=None）只在异步调用路径上可用。本机源码里，同步客户端拿到没有 url 的规格会直接报错：ASGI transport (url=None) requires async invocation。所以纯异步子智能体 + ASGI 的组合，要用 ainvoke / astream 这类异步入口跑主管，别用同步 invoke。

💡 提示（本机 0.7.5 源码观察，原文未说明）：HTTP 传输的请求头默认会补上 x-auth-scheme: langsmith（除非你在 headers 里自己给了）。自建服务器一般忽略它，真要覆盖就用 headers。

单部署（Single deployment）#

所有 agent 同部署、同服务器，用 ASGI 传输；LangGraph 部署下所有图注册进一份 langgraph.json。

1
单部署（推荐起步）
2
  一个服务器 / 一份 langgraph.json
3
    主管 supervisor
4
      ├─ ASGI 传输 ─▶ researcher   （同进程，独立 thread + 独立状态）
5
      └─ ASGI 传输 ─▶ coder        （同进程，独立 thread + 独立状态）

一个服务器管到底，零网络延迟；缺点是大家抢同一份资源，谁把 worker 占满大家一起排队。

拆分部署（Split deployment）#

主管一台服务器，子智能体另一台，用 HTTP 传输。

1
拆分部署
2
  服务器 A：主管  ──HTTP + 认证──▶  服务器 B：researcher / coder

适合：子智能体需要不同的计算画像（CPU 密集 / GPU / 内存大户），或者要独立扩缩容。

混合（Hybrid）#

一部分子智能体同部署走 ASGI，另一部分远端走 HTTP：

1
from deepagents import AsyncSubAgent
2

3
async_subagents = [
4
    AsyncSubAgent(          # 不写 url → ASGI（同部署）
5
        name="researcher", description="Research agent",
6
        graph_id="researcher",
7
    ),
8
    AsyncSubAgent(          # 写了 url → HTTP（远端）
9
        name="coder", description="Coding agent",
10
        graph_id="coder", url="https://coder-deployment.langsmith.dev",
11
    ),
12
]

1
混合部署
2
  用户 ─▶ 主管（服务器 A）
3
            ├─ ASGI ─▶ researcher   同进程：轻量、频繁调用
4
            └─ HTTP ─▶ coder        远端：重资源、独立扩缩容

官方混合部署示例的公开 trace：https://smith.langchain.com/public/dddcb1d1-92ac-468b-aa34-5d9070661aa1/r

原文的推荐路线很清楚：从单部署开始（一个服务器管到底、零网络延迟），等真出现资源或组织边界了再拆：拆分部署适合子智能体资源画像差异大、要独立扩缩容的场景（代价是多一套部署 + 认证 + 网络延迟）；混合适合大部分子智能体轻量、个别重的场景（代价是配置更碎）。

本地开发时给工作进程池（worker pool）定容量#

用 langgraph dev 在本地跑时，要把工作进程池调大以容纳并发的子智能体 run。每个活跃 run 占一个 worker 槽位，算账很简单：1 个主管 + 3 个并发子智能体任务 = 需要 4 个槽位；槽位给少了不会报错，而是排队（launch 一直等着），这是最容易被误判成”卡死”的现象。

1
langgraph dev --n-jobs-per-worker 10

子智能体的 description 怎么写#

主管就是靠 description 决定派谁去的，所以要具体、以动作开头。原文给了一好一坏两个例子：

1
AsyncSubAgent(  # 好例子：说清手段 + 什么场景该找我
2
    name="researcher",
3
    description="Conducts in-depth research using web search. Use for questions requiring multiple searches and synthesis.",
4
    graph_id="researcher",
5
)

反面例子：AsyncSubAgent(name="helper", description="helps with stuff", graph_id="helper")——等于没说，主管只能瞎猜，然后派错人。

用会话线程 ID（thread ID）做追踪#

LangGraph 部署下，每个异步子智能体 run 都是标准的 LangGraph run，在 LangSmith 里完整可见。主管的 trace 里能看到 launch / check / update / cancel / list 这些工具调用，每个子智能体 run 是另一条独立 trace，两边靠 thread ID 串起来。

所以排障姿势是：用 thread ID（= task ID）把”主管的编排 trace”和”子智能体的执行 trace”对上——先看主管什么时候派的活，再看子智能体那边跑到哪一步。

主管启动后立刻轮询#

• 症状：主管刚 launch 完就在循环里调 check，把异步硬生生用成了阻塞。
• 原因：模型的本能是”我派了活就该盯着”，于是自己把非阻塞变成了忙等。
• 处理：middleware 会注入系统提示规则来阻止这种行为；如果还在轮询，就在主管的 system_prompt 里再加一条硬约束：

1
from deepagents import create_deep_agent
2

3
agent = create_deep_agent(
4
    model="google_genai:gemini-3.6-flash",
5
    system_prompt="""...your instructions...
6

7
    After launching an async subagent, ALWAYS return control to the user.
8
    Never call check_async_task immediately after launch.""",
9
    subagents=async_subagents,
10
)

官方这个问题的公开 trace：https://smith.langchain.com/public/181f8fc2-b3aa-4c4b-b23d-d4204db98849/r

主管报的是旧状态#

• 症状：主管直接引用对话历史里早先那次的状态，而不去重新 check。
• 原因：对话历史里的状态天然过期，模型却当成了当前值。
• 处理：middleware 提示里已写明”对话历史里的任务状态永远是旧的”；如果还犯，就在系统提示里明确要求”报状态前必须先调 check 或 list”。

任务 ID 查不到#

• 症状：check 或 cancel 失败，因为主管把 task ID 截断或改写格式了。
• 原因：模型倾向于”省略中间那段”或”美化一下”，而 task ID 必须逐字精确。
• 处理：middleware 提示要求始终使用完整 task ID；如果还截断，原文说这通常是模型相关的毛病——换个模型，或在系统提示里加”永远显示完整 task_id，绝不截断或缩写”。

子智能体只排队、不执行#

• 症状：启动一个子智能体后长时间挂着，或者很久才开始跑。
• 原因：工作进程池被占满了，新 run 没有槽位。
• 处理：用 --n-jobs-per-worker 把池子调大，参考工作进程池容量算法。

四个问题排一下优先级：先怀疑模型行为（前三个），再怀疑资源（第四个）。前三个的修法都在提示词层，第四个在启动参数层。