> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zerone.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Subagent

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

# 委派任务

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

## 能力模型

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

```typescript theme={null}
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 来源与顶层选项取并集，顶层在前：

```text theme={null}
connectionTools = [...mcpServers 池,          ...capabilities.connectionTools]
customTools     = [...AgentOptions.customTools, ...capabilities.customTools]
```

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

## 解析顺序

```text theme={null}
内建 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`                          |

```typescript theme={null}
// 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'],
      },
    },
  },
})
```

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