Subagent

委派任务并显式隔离子 Agent 的能力。

​

委派任务

Subagent 通过 Task 或 MultiTask 接收委派。SDK 3.0 将每个 Agent 的能力显式隔离：子 Agent 不会自动继承父 Agent 的自定义 Tool、连接 Tool 或 Skill。

​

能力模型

每个 Agent 运行在 RuntimeEnvironment（Runtime-global，继承自 Session）之上，并携带自己的 AgentCapabilities（Agent-local，不继承、不回退）：

interface AgentCapabilities {
  connectionTools?: ToolDefinition[]  // 已物化的 MCP/连接 Tool（默认 []）
  customTools?: ToolDefinition[]      // 默认 []
  skills?: SkillDefinition[]          // Agent 自有 Skill 集合（派生时默认 []）
  allowedTools?: string[]             // 仅约束内建 Tool
  disallowedTools?: string[]          // 作用于合并后的完整 Tool 池
}

• 继承（Runtime-global）：Provider、模型、凭据、cwd、子进程环境变量、运行时服务（askUser / config / webSearch / webFetch / cron 以引用共享）以及内建 Tool 实现。
• 隔离（Agent-local）：prompt / appendPrompt / maxTurns 以及所有 capabilities 字段。不存在 child.X ?? parent.X 回退：未设置的能力解析为子 Agent 自己的空值，同级 subagent 之间也互不可见。

委派深度固定为 1：派生 subagent 时移除 Task 与 MultiTask。

​

根 Agent 合并规则

根 Agent 的 capabilities 来自每次请求的有效定义（query() 覆盖优先于构造函数配置）。Tool 来源与顶层选项取并集，顶层在前：

connectionTools = [...mcpServers 池,          ...capabilities.connectionTools]
customTools     = [...AgentOptions.customTools, ...capabilities.customTools]

同名能力条目覆盖其顶层同名项（后者优先去重）。capabilities.skills 替换注册表视图；未设置的能力字段回退到顶层行为——绝不反向。

​

解析顺序

内建 Tool + caps.customTools + caps.connectionTools
  → allow list（仅内建 Tool）→ deny list（完整合并池）
  → [派生] 移除 Task/MultiTask          ← 委派深度固定为 1
  → [派生·Explore] isReadOnly || Bash   ← 写 Tool 保持不可发现
  → 惰性拆分（FindTool 目录）

Explore 过滤器是作用于最终 Tool 池的动态安全策略，而非静态 deny list。MCP annotations.readOnlyHint 映射为 isReadOnly，因此只读 MCP Tool 可在 Explore subagent 中使用，并加入只读并发批次。

findTool 注册表按 Agent 隔离：每次派生获得全新目录（subagent 不会覆盖父 Agent 的延迟注册表），而父 Agent 的激活记录仍像以前一样跨请求保留。

​

迁移（2.x → 3.0）

2.x	3.0
AgentEnvironment	RuntimeEnvironment + AgentCapabilities
resolveAgent(env, def)	resolveAgent(runtime, capabilities, def, opts?)
def.allowedTools / def.disallowedTools	def.capabilities.allowedTools / .disallowedTools
父 Agent 的 customTools / mcpTools 流入 subagent	显式 entry.capabilities（见下）
subagent availableSkills（共享注册表过滤）	capabilities.skills: [...]（Agent 自有集合）
QueryEngineConfig.env	QueryEngineConfig.runtime

// 2.x：subagent 隐式继承父 Agent 的 Tool 池。
// 3.0：能力显式声明并隔离。
const agent = new Agent({
  subAgents: {
    researcher: {
      description: 'Research', prompt: '...',
      capabilities: {
        // 宿主物化的连接 Tool —— acquireMCPConnection 的
        // 引用计数池让多个条目复用同一连接。
        connectionTools: hubConnections.researcher,
        customTools: [searchTool],
        allowedTools: ['Read', 'Grep', 'Glob', 'Bash', 'Skill', 'FindTool'],
      },
    },
  },
})

委派前应明确配置子 Agent 的任务和可用能力，避免依赖父 Agent 的隐式配置。