你有没有想过,为什么很多 Agent 一碰到复杂任务就开始"精神分裂"?
前一阵我让某个 Agent 帮我做一个项目调研:先搜资料、再分析数据、最后写报告。结果它搜着搜着就开始分析,分析到一半又回头去搜,最后写出来的报告东一榔头西一棒槌,像个注意力涣散的实习生。
问题就在这里:一个 Agent 同时干太多事,上下文里堆满了各种信息,搜索关键词、网页内容、分析思路、报告草稿,全混在一起。模型很容易"串台",把搜索时的一个无关信息当成分析结论,或者把草稿里的猜测当成事实。
DeepAgents 的解决方案很直观:既然一个人干会乱,那就多找几个人,每人专职干一件事。
这就是子代理系统的核心思想。
为什么需要分身
子代理不是炫技,它解决的是很现实的工程问题。
上下文隔离是最直接的原因。主代理的上下文窗口是有限的,如果所有子任务都在主线程里做,很快就会爆炸。子代理有独立的上下文,干完活只把结果返回,不会污染主代理的上下文。
专业化是另一个好处。你可以为特定任务配置专门的子代理。比如一个专门做代码审查的,一个专门写文档的,一个专门做测试的。每个子代理有自己的系统提示、工具集和工作方式。
并行化是隐藏的收益。多个独立的子任务可以同时派给不同的子代理执行,总体时间大大缩短。
但子代理也有代价:创建和调度有开销,通信有成本,状态管理更复杂。所以 DeepAgents 的思路一直很克制,是"按需 spawn",不是"先摆一排角色再说"。
三种分身术
DeepAgents 支持三种子代理类型,对应不同的使用场景。
SubAgent:声明式子代理
这是最常用的类型。你声明一个配置,DeepAgents 负责创建和管理。
from deepagents import create_deep_agentresearch_agent = { "name": "researcher", "description": "Deep research on any topic using web search", "system_prompt": """You are a research specialist.Use web search to gather comprehensive information.Always cite your sources.Return a structured summary of findings.""", "tools": [web_search], "model": "openai:gpt-4o"}agent = create_deep_agent( subagents=[research_agent])
这几个字段里,真正影响效果的其实就这么几项:
- •
name—— 主代理调用时用的标识 - •
description—— 告诉主代理这个子代理是干什么的 - •
system_prompt—— 子代理的系统提示 - •
tools—— 子代理能用的工具(如果不指定,继承主代理的) - •
model—— 子代理用的模型(可以跟主代理不同)
description 特别重要。主代理就是靠它来判断这个子代理值不值得调用。如果描述不清楚,主代理可能该用的时候不用,不该用的时候反而乱派活。
CompiledSubAgent:预编译子代理
有时候你已经有一个现成的 Agent,想把它挂到主代理下面当子代理用。
from langgraph import StateGraphfrom deepagents import CompiledSubAgent# 你已经有一个用 LangGraph 写的复杂 Agentmy_existing_agent = StateGraph(...).compile()subagent = CompiledSubAgent( name="custom-analyzer", description="Specialized code analyzer", runnable=my_existing_agent)agent = create_deep_agent( subagents=[subagent])
CompiledSubAgent 的唯一要求是:返回的 state 里必须有 messages 键,因为结果要从 messages 里提取。
这种类型适合复用已有的 Agent 实现,或者做一些 DeepAgents 默认不支持的高级定制。
AsyncSubAgent:异步子代理
前两种都是同步的:主代理调用子代理,然后等它返回。但有时候子任务执行时间很长,你不想在那干等着。
AsyncSubAgent 支持后台执行、非阻塞调用。
from deepagents import AsyncSubAgentasync_subagent = AsyncSubAgent( name="long-running-task", description="Tasks that take a long time", graph_id="my-deployment-id", # LangSmith 部署 ID url="https://my-agent-server.com", headers={"Authorization": "Bearer token"})agent = create_deep_agent( subagents=[async_subagent])
异步子代理会暴露额外的工具:
- •
launch_async_task—— 启动任务 - •
check_async_task—— 查询状态 - •
update_async_task—— 更新参数 - •
cancel_async_task—— 取消任务 - •
list_async_tasks—— 列出所有任务
主代理可以启动任务后继续做其他事,过一会儿再查结果。
目前 AsyncSubAgent 主要支持通过 LangSmith 部署的远程 Agent。这种模式很适合把重负载任务卸载到专门的服务器上执行。
task 工具的设计艺术
子代理系统的核心是那个 task 工具。它看起来只是一个委派入口,但 DeepAgents 在这个工具的提示词上下了很大功夫。
subagents.py 里的 TASK_TOOL_DESCRIPTION 有整整两百多行,是我见过的最详细的工具描述之一。让我带你看看里面都写了什么。
使用场景指导
提示词首先告诉主代理什么时候该用子代理:
Launch an ephemeral subagent to handle complex, multi-step independent tasks with isolated context windows.When to use the task tool:- When a task is complex and multi-step, and can be fully delegated in isolation- When a task is independent of other tasks and can run in parallel- When a task requires focused reasoning or heavy token/context usage that would bloat the orchestrator thread- When sandboxing improves reliability- When you only care about the output of the subagent, and not the intermediate steps
然后又告诉什么时候不该用:
When NOT to use the task tool:- If you need to see the intermediate reasoning or steps after the subagent has completed- If the task is trivial (a few tool calls or simple lookup)- If delegating does not reduce token usage, complexity, or context switching- If splitting would add latency without benefit
这种明确的边界指导特别重要。我见过很多 Agent 框架,要么过度使用子代理,简单任务也层层委派;要么完全不用,所有事都自己硬扛。DeepAgents 的提示词,本质上是在教模型判断什么情况下委派才划算。
并行化鼓励
提示词里有句加粗的话:
Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
它在主动鼓励主代理并行思考。如果用户问"比较 A、B、C 三个产品",主代理应该同时 spawn 三个子代理分别研究,而不是一个一个来。
这其实是个很高级的提示工程技巧。不是告诉模型"你可以并行",而是明确告诉它"你应该并行,因为这样性能更好"。
生命周期说明
提示词详细描述了子代理的生命周期:
Subagent lifecycle:1. Spawn → Provide clear role, instructions, and e…