Appearance
子 Agent 委派
Subagent 的核心价值不是“让多个模型显得更聪明”，而是把详细工具轨迹隔离在独立上下文中，并让 主 Agent 只接收完成决策所需的结果。每个 subagent 都应有清晰职责、最小工具集和可验证输出。
同步委派流程
同步表示主 Agent 的当前调用会等待 subagent 完成。它适合几秒到几分钟内完成、主任务必须立即 使用结果的工作。
前端类比
可以把 subagent 类比为返回聚合结果的 Web Worker：主线程给出明确输入，worker 内部处理大量 细节，最后只回传结构化结果，避免主线程 state 被中间数据淹没。
Deep Agents 原生语义：SubAgentMiddleware 向主 Agent 提供 task 工具。每次调用为选定 subagent 建立独立 messages 上下文；subagent 完成后，middleware 把最终结果作为 ToolMessage 返回主 Agent，而不是合并全部中间轨迹。
定义专业 Subagent
description 决定主 Agent 何时委派，system_prompt/systemPrompt 决定 subagent 如何工作。 模型字段省略时继承主 Agent 模型。
python
import os
from deepagents import create_deep_agent
# search_policy 来自“工具与 MCP”页的确定性 fixture 工具
researcher = {
"name": "policy-researcher",
"description": "查找并比较客服政策；一次只处理一个明确主题",
"system_prompt": (
"只使用提供的政策工具。返回结论、原文依据和无法确认的事项；"
"不要向主 Agent 返回冗长推理过程。"
),
"tools": [search_policy],
}
agent = create_deep_agent(
model=os.environ["DEEPAGENTS_MODEL"],
subagents=[researcher],
)ts
import { createDeepAgent, type SubAgent } from 'deepagents'
// searchPolicy 来自“工具与 MCP”页的确定性 fixture 工具
const researcher: SubAgent = {
name: 'policy-researcher',
description: '查找并比较客服政策；一次只处理一个明确主题',
systemPrompt:
'只使用提供的政策工具。返回结论、原文依据和无法确认的事项；' +
'不要向主 Agent 返回冗长推理过程。',
tools: [searchPolicy],
}
const model = process.env.DEEPAGENTS_MODEL
if (!model) throw new Error('DEEPAGENTS_MODEL is required')
const agent = createDeepAgent({
model,
subagents: [researcher],
})Python 使用 system_prompt，TypeScript 使用 systemPrompt。类似差异还包括 interrupt_on 与 interruptOn、response_format 与 responseFormat。
配置继承与覆盖
| 配置 | 自定义 subagent 默认行为 | 设计建议 |
|---|---|---|
| model | 继承主 Agent | 只有成本或能力确有差异时覆盖 |
| tools | 未指定时继承；指定后整体覆盖 | 显式传最小工具集更易审查 |
| system prompt | 必须为自定义 subagent 定义 | 同时写职责、边界与输出格式 |
| middleware | 不继承自定义 middleware | 需要日志、限流时显式配置 |
| skills | 自定义 subagent 不自动继承 | 按职责提供独立 Skills |
| permissions | 可继承；subagent 值会覆盖 | 不要意外放宽父级规则 |
| response format | 可单独配置 | 需要稳定合并时优先结构化输出 |
Deep Agents 还默认提供 general-purpose subagent，用于没有专用类型但适合隔离上下文的多步骤 任务。它不是万能后备：涉及专门工具、输出 schema 或权限时，应定义命名 subagent。
写好委派任务
主 Agent 发给 subagent 的 prompt 应包含：
- 一个边界清晰的问题，而不是完整用户目标的复制。
- 可使用的数据和工具范围。
- 期望输出结构与最大长度。
- 必须提供的来源、证据或失败原因。
- 不应执行的写操作或外部副作用。
不好的委派是“研究一下并做好”。更好的委派是“比较退款与发票政策，返回两行表格；每行包含 主题、确认规则、fixture key；没有数据时标记未知”。
并行与上下文成本
主 Agent 可以发起多个独立 task，interpreter 也能批量动态分派。并发前需要限制：
- 最大 subagent 数与总模型预算。
- 每个 subagent 的 timeout、工具次数和返回长度。
- 是否共享 backend 路径，以及写冲突如何解决。
- 失败是否部分降级，还是整体终止。
Subagents 隔离上下文，但不会消除成本；每个 subagent 都有自己的模型调用和工具轨迹。
信任边界
主 Agent 不应无条件信任 subagent。远程数据、工具结果和 subagent 最终消息都可能包含 prompt injection 或错误事实。对关键结果应要求来源、使用结构化 schema、运行独立校验，并把写操作留在 受控主流程。