Appearance
异步子 Agent
Preview 能力：Async subagents 自 Python
deepagents 0.5.0、TypeScriptdeepagents 1.9.0起提供，API 仍在演进。它依赖 Agent Protocol server，不能只靠一个本地 SDK 对象获得完整后台 任务能力。
同步 subagent 会阻塞主调用直到完成。AsyncSubAgent 把任务发送到同部署或远程 Agent Protocol 服务，在独立 thread 中持续运行；主 Agent 可以继续和用户交互，稍后再检查或更新任务。
什么时候需要异步
- 研究、构建或数据处理可能运行数分钟以上。
- 用户希望先收到任务 ID 和当前状态。
- 主 Agent 需要同时管理多个后台任务。
- 子任务需要在多次 update 之间保留自己的 state。
如果主 Agent 启动任务后立刻轮询到完成，异步只会变成更复杂的阻塞调用。短任务优先使用同步 subagent。
前端类比
它更像有持久 job id 的后台队列，而不是 await Promise.all。浏览器请求可以结束，任务仍在服务端 运行；后续请求通过 task id 查询或追加指令。
Deep Agents 原生语义：AsyncSubAgent 描述的是 Agent Protocol server 上的 graph/assistant。 AsyncSubAgentMiddleware 向 supervisor 注入 start、check、update、cancel 与 list 工具，并把远程 thread 状态投影回主 Agent 上下文。
配置 AsyncSubAgent
同部署时省略 url，由 Agent Server 使用 ASGI transport；远程部署设置 url，并由应用安全管理 认证 headers。
python
import os
from deepagents import AsyncSubAgent, create_deep_agent
researcher = AsyncSubAgent(
name="researcher",
description="执行长时间资料核验并返回带来源的报告",
graph_id="researcher",
)
agent = create_deep_agent(
model=os.environ["DEEPAGENTS_MODEL"],
subagents=[researcher],
)ts
import { createDeepAgent, type AsyncSubAgent } from 'deepagents'
const researcher: AsyncSubAgent = {
name: 'researcher',
description: '执行长时间资料核验并返回带来源的报告',
graphId: 'researcher',
}
const model = process.env.DEEPAGENTS_MODEL
if (!model) throw new Error('DEEPAGENTS_MODEL is required')
const agent = createDeepAgent({
model,
subagents: [researcher],
})代码还需要在 Agent Protocol 服务中注册 graph_id/graphId 对应的图。没有服务端图配置时， 这段 supervisor 配置无法独立运行。
生命周期工具
| 工具 | 作用 | 主 Agent 应如何使用 |
|---|---|---|
start_async_task | 启动后台任务并返回 task id | 保存完整 task id，向用户报告已启动 |
check_async_task | 获取实时状态和完成结果 | 需要状态时重新调用，不复述旧消息 |
update_async_task | 向运行任务追加指令 | 说明变更和仍然有效的约束 |
cancel_async_task | 请求取消任务 | 取消后继续检查最终状态与资源回收 |
list_async_tasks | 列出 supervisor 跟踪的任务 | 用于恢复视图，不替代服务端授权 |
历史消息中的任务状态总是可能过期。System prompt 应要求模型在回答“现在完成了吗”之前调用 check_async_task，不要根据之前的 ToolMessage 猜测。
独立 thread 与更新
每个 async subagent 在自己的 thread 中运行，因此 update 可以基于已有 state 继续，而不必重放 全部任务。Supervisor 只持有 task id 和状态摘要；远程 thread 的 checkpoint、store 和生命周期由 Agent Protocol 部署负责。
这也意味着：
- 主 Agent checkpointer 不会替代远程 graph 的持久化。
- 远程任务可能因 worker pool 已满而排队。
- 取消请求需要服务端协作，不能假设进程已经立刻停止。
- Task id 必须作为不透明标识保存，不应由模型截断或改写。
安全与信任
远程 subagent 的状态、错误和最终结果会进入 supervisor 上下文。应把它们视为不可信输入：
- 只连接受控 Agent Protocol endpoint，并验证 TLS 与服务身份。
- Headers 由服务端配置或凭据代理提供，不写进 prompt。
- 在服务端再次校验用户、tenant、graph 与 thread 权限。
- 对远程结果使用 schema、来源和业务验证。
- 为 start/update/cancel 建立审计日志和速率限制。
Python 与 TypeScript 差异
| 概念 | Python | TypeScript |
|---|---|---|
| 类型 | AsyncSubAgent | AsyncSubAgent type |
| Graph 字段 | graph_id | graphId |
| 远程地址 | url | url |
| 初始版本门槛 | >=0.5.0 | >=1.9.0 |
两者的生命周期概念相同，但具体类型与 middleware 实现应按当前版本文档核验。