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

# 子 Agent（Subagents）

子 Agent 是主会话可以临时委派出去的专门角色。Qoder Agent SDK 支持两类子 Agent：

* **内置子 Agent**：由 qodercli 提供，例如通用搜索、代码探索、规划等。
* **自定义子 Agent**：由 SDK 使用者通过 `options.agents` 定义，适合业务审查、测试执行、安全分析等专门角色。

本文重点讲如何在 SDK 中使用内置子 Agent，以及如何按需自定义子 Agent。你可以顺序阅读，也可以按章节查具体配置项。完整类型定义见 [Agents Reference](/zh/cli/sdk/references)。

除非特别说明，本文里的“Agent”都指可以被主会话委派的子 Agent；`options.agent` 是把某个子 Agent 定义作为主会话角色运行的特殊用法。

<div id="内置子-agent" />

## 内置子 Agent

使用内置子 Agent 时，你不需要自己写子 Agent 定义，只需要知道它的名称，并在 SDK 中引用它。

当前 qodercli 常见内置子 Agent：

| 名称                | 用途                                  |
| ----------------- | ----------------------------------- |
| `general-purpose` | 通用子 Agent，适合搜索代码、研究复杂问题和执行多步骤任务     |
| `Explore`         | 只读代码探索子 Agent，适合快速查找文件、搜索关键字、理解代码结构 |
| `Plan`            | 只读规划子 Agent，适合设计实现方案、识别关键文件和分析架构取舍  |

内置子 Agent 列表会随 qodercli 版本和当前配置变化。交互式 CLI 中可以输入 `/agents` 查看当前发现的子 Agent；命令行也可以运行：

```bash theme={null}
qodercli agents list
```

SDK 会话初始化后，可以用 `q.supportedAgents()` 读取当前会话实际可用的子 Agent：

```typescript theme={null}
import { query } from '@qoder-ai/qoder-agent-sdk';

const q = query({ prompt: 'List available agents.' });
const agents = await q.supportedAgents();
```

`q.supportedAgents()` 返回的列表会包含 SDK 通过 `options.agents` 注册的子 Agent，也会包含当前 CLI 已发现、适用于 SDK 场景的内置、用户、项目和插件子 Agent。`general-purpose`、`Explore`、`Plan` 可以默认出现在 SDK 会话中；交互式 CLI 辅助型的 `qoder-guide` 和 `statusline-setup` 不支持在 SDK 会话中使用，也不会出现在 `q.supportedAgents()` 中。返回结构见 [AgentInfo](/zh/cli/sdk/references#agentinfo)。

***

<div id="使用内置子-agent" />

## 使用内置子 Agent

<div id="作为主会话角色运行" />

### 作为主会话角色运行

如果希望整个会话都按某个内置子 Agent 的角色运行，可以直接把内置子 Agent 名称传给 `options.agent`，不需要在 `options.agents` 里重复定义。

```typescript theme={null}
import { query } from '@qoder-ai/qoder-agent-sdk';

const q = query({
  prompt: 'Summarize this project architecture and identify the most important modules.',
  options: {
    agent: 'general-purpose',
  },
});
```

`options.agent` 可以引用 SDK 注册的子 Agent，也可以引用当前 CLI 已发现且适用于 SDK 场景的内置 / 用户 / 项目 / 插件子 Agent。

<div id="作为子-agent-委派" />

### 作为子 Agent 委派

子 Agent 委派通过内置 `Agent` 工具完成。主会话的可用工具集中必须包含 `Agent`，模型才有入口发起委派；在 SDK 里常见做法是预授权这条工具调用路径，然后在 prompt 里点名。

```typescript theme={null}
const q = query({
  prompt: 'Use the Explore agent to find where authentication is implemented.',
  options: {
    // Pre-authorize Agent tool calls. If options.tools restricts the tool set, include 'Agent' there too.
    allowedTools: ['Agent'],
  },
});
```

`allowedTools: ['Agent']` 表示放行 / 预授权这类工具调用；如果你同时使用 `options.tools` 收窄主会话可用工具白名单，也要把 `Agent` 放进 `tools`。不要把 `Agent` 放进 `disallowedTools`。

子 Agent 名称需要和当前发现结果一致，包括大小写。例如当前内置名称里有 `Explore`、`Plan`、`general-purpose`。不确定时先调用 `q.supportedAgents()`。

***

<div id="自定义子-agent" />

## 自定义子 Agent

当内置子 Agent 不够贴合你的业务或项目约束时，可以通过 `options.agents` 自定义子 Agent。例如：

* 只读代码审查子 Agent：只能读文件和搜索，不能改代码。
* 测试执行子 Agent：能运行测试命令并分析失败原因。
* 安全审查子 Agent：只关注认证、授权、注入、敏感信息泄露等风险。
* 业务支持子 Agent：只能调用指定 MCP 工具，例如订单查询、工单检索、内部知识库搜索。

自定义子 Agent 通常分三步：

1. 在 `options.agents` 中定义子 Agent 名称、用途描述和系统提示词。
2. 用 `tools` 或 `disallowedTools` 收口它能使用的工具。
3. 让主会话通过 `Agent` 工具委派给它，或用 `options.agent` 让它直接驱动主会话。

> **必须包含 `Agent` 工具**：自定义子智能体需要主会话通过内置 `Agent` 工具发起委派，因此 `allowedTools` 中必须包含 `Agent` 工具。

***

<div id="使用-optionsagents-自定义子-agent" />

## 使用 options.agents 自定义子 Agent

最小示例：注册一个只读代码审查子 Agent。

```typescript theme={null}
import { query } from '@qoder-ai/qoder-agent-sdk';

const q = query({
  prompt: 'Use the code-reviewer agent to review the authentication module.',
  options: {
    // Pre-authorize Agent tool calls. If options.tools restricts the tool set, include 'Agent' there too.
    allowedTools: ['Agent'],
    agents: {
      'code-reviewer': {
        description:
          'Reviews code for correctness, security issues, and maintainability problems.',
        prompt: `You are a code review specialist.
Review the requested code and report concrete findings.
Sort findings by severity and include file paths when possible.`,
        tools: ['Read', 'Grep', 'Glob'],
      },
    },
  },
});

for await (const message of q) {
  // Consume streamed messages according to your application needs.
}
```

这个例子里有三个关键点：

* `options.agents` 注册本次会话可用的自定义子 Agent。
* 子 Agent 委派通过 `Agent` 工具发生；这里必须用 `allowedTools: ['Agent']` 预授权这条调用路径。
* 子 Agent 自己的 `tools` 只允许读和搜索，所以它不能改文件，也不能执行命令。

<div id="optionsagents-入参" />

### `options.agents` 入参

`options.agents` 是子 Agent 名称到子 Agent 定义的映射。完整类型见 [AgentDefinition](/zh/cli/sdk/references#agentdefinition)。

| 字段                | 类型                     | 必填 | 怎么填                                    | 说明                                       |
| ----------------- | ---------------------- | -- | -------------------------------------- | ---------------------------------------- |
| `description`     | `string`               | 是  | 一句话说明什么时候使用这个子 Agent                   | 给模型看的路由说明，影响是否会调用它                       |
| `prompt`          | `string`               | 是  | 子 Agent 的角色、边界、输出要求                    | 该子 Agent 的系统提示词                          |
| `tools`           | `string[]`             | 否  | 如 `['Read', 'Grep', 'Glob']`           | 工具白名单，配置后只能使用列出的工具                       |
| `disallowedTools` | `string[]`             | 否  | 如 `['Bash', 'Write']`                  | 工具黑名单，适合只排除少数工具                          |
| `model`           | `string`               | 否  | 如 `'inherit'`、`'auto'`、`'performance'` | 子 Agent 的模型配置                            |
| `maxTurns`        | `number`               | 否  | 如 `8`                                  | 限制子 Agent 最多执行多少轮                        |
| `effort`          | `EffortLevel`          | 否  | 如 `'low'`、`'medium'`、`'high'`、`'max'`  | 控制推理努力级别                                 |
| `permissionMode`  | `PermissionMode`       | 否  | 如 `'default'`、`'acceptEdits'`、`'plan'` | 控制子 Agent 内部工具调用的权限模式                    |
| `skills`          | `string[]`             | 否  | 如 `['review']`                         | 预加载到子 Agent 上下文的 skill                   |
| `mcpServers`      | `AgentMcpServerSpec[]` | 否  | MCP server 名称或配置                       | 给子 Agent 限定或增加 MCP server                |
| `initialPrompt`   | `string`               | 否  | 首轮自动输入                                 | 仅当该子 Agent 通过 `options.agent` 成为主会话角色时生效 |

***

<div id="配置子-agent-角色" />

## 配置子 Agent 角色

`description` 和 `prompt` 是自定义子 Agent 最重要的两个字段。

<div id="description" />

### `description`

`description` 描述“什么时候应该使用这个子 Agent”。模型会根据它决定是否委派。

```typescript theme={null}
description:
  'Runs project tests, analyzes failing output, and suggests fixes.'
```

好的 `description` 应该具体说明任务边界。不要只写 `A helpful agent`、`Helper` 这类泛化描述。

<div id="prompt" />

### `prompt`

`prompt` 定义子 Agent 的角色、边界和输出方式。TypeScript 用户如果不传 `prompt`，类型检查会报错；JavaScript 用户也应该始终传入这个字段。

```typescript theme={null}
prompt: `You are a code review specialist.
Only review the requested code; do not edit files.
Return findings sorted by severity, with file paths and suggested fixes.`
```

如果 `prompt` 只是泛泛写成“你是一个有帮助的助手”，模型可能仍会调用这个子 Agent，但它的表现会接近普通助手：不知道该优先检查什么、哪些事不要做、结果该怎么返回。

建议 `prompt` 至少说明三件事：

| 要说明什么  | 示例                                                     |
| ------ | ------------------------------------------------------ |
| 负责什么任务 | `Review code for security and maintainability issues.` |
| 不该做什么  | `Do not edit files. Do not run commands.`              |
| 如何返回结果 | `Return findings sorted by severity with file paths.`  |

***

<div id="配置子-agent-模型和推理" />

## 配置子 Agent 模型和推理

先把 `description` 和 `prompt` 写清楚，再考虑 `model`、`effort` 和 `maxTurns`。前者决定子 Agent 会不会被正确调用、调用后是否知道边界；后者主要用于在角色已经清楚后调效果、速度和成本。

| 配置         | 控制什么              | 什么时候优先调整                                 |
| ---------- | ----------------- | ---------------------------------------- |
| `model`    | 选择子 Agent 使用的模型档位 | 这个子 Agent 长期承担某类固定任务，需要稳定控制能力和 Credit 成本 |
| `effort`   | 控制同一模型下愿意花多少推理预算  | 同一个子 Agent 偶尔遇到更复杂、更需要仔细推理的任务            |
| `maxTurns` | 限制最多执行多少轮         | 任务可能探索过深、跑太久，或你希望给成本设置硬上限                |

可以按这个顺序判断：

1. 默认先不配，或设置 `model: 'inherit'`，让子 Agent 跟随主会话模型。
2. 如果这个子 Agent 是高频、简单、可容忍粗略答案的任务，用 `model: 'efficient'` 或 `model: 'lite'` 降低成本。
3. 如果这个子 Agent 承担架构设计、复杂重构、跨模块审查等高风险任务，用 `model: 'performance'` 或 `model: 'ultimate'` 提高能力上限。
4. 如果模型档位不变，但希望它在当前任务上多想一会儿，再调高 `effort`。
5. 如果担心失控探索，配合 `maxTurns` 给执行轮次设上限。

常见组合：

| 场景             | 推荐配置                                               | 说明                  |
| -------------- | -------------------------------------------------- | ------------------- |
| 快速问答、格式转换、简单定位 | `model: 'efficient'`，`effort: 'low'`，`maxTurns: 3` | 便宜、快，适合低风险任务        |
| 只读代码探索、梳理模块关系  | `model: 'auto'` 或 `'inherit'`，`effort: 'medium'`   | 让路由或主会话模型决定能力档位     |
| 代码审查、安全审查、迁移方案 | `model: 'performance'`，`effort: 'high'`            | 更适合需要仔细权衡和发现问题的任务   |
| 复杂系统设计、高难度问题分析 | `model: 'ultimate'`，`effort: 'high'` 或 `'max'`     | 成本更高，只建议用于关键复杂任务    |
| 批量辅助子任务        | `model: 'efficient'`，`effort: 'low'`，较小 `maxTurns` | 适合多子 Agent 协作时控制总成本 |

示例：给不同子 Agent 配不同策略。

```typescript theme={null}
agents: {
  explorer: {
    description: 'Quickly searches code and summarizes relevant files.',
    prompt: 'Find relevant files and return a concise summary. Do not edit.',
    tools: ['Read', 'Grep', 'Glob'],
    model: 'efficient',
    effort: 'low',
    maxTurns: 5,
  },
  architect: {
    description: 'Designs complex implementation plans across modules.',
    prompt: 'Analyze tradeoffs carefully and return an implementation plan with risks.',
    tools: ['Read', 'Grep', 'Glob'],
    model: 'performance',
    effort: 'high',
    maxTurns: 10,
  },
}
```

字段完整可取值见 [Agents Reference - model](/zh/cli/sdk/references#model)、[Agents Reference - maxTurns](/zh/cli/sdk/references#maxturns) 和 [Agents Reference - effort](/zh/cli/sdk/references#effort)。

***

<div id="控制子-agent-工具" />

## 控制子 Agent 工具

自定义子 Agent 和主会话使用同一套工具名。内置工具名如 `Read`、`Grep`、`Glob`、`Bash`；自定义 MCP 工具名使用完整格式 `mcp__{serverName}__{toolName}`。这部分配置的是子 Agent 能看到和调用哪些工具。

<div id="主会话侧的-agent-工具" />

### 主会话侧的 `Agent` 工具

`options.agents` 只注册子 Agent，不会自动替模型调用它。模型要委派任务，主会话工具集中必须存在 `Agent`。默认工具集通常会注册它；如果你设置 `options.tools` 限定主会话可用工具，记得包含 `Agent`；如果设置 `disallowedTools: ['Agent']`，委派会被禁用。

<div id="工具白名单tools" />

### 工具白名单：`tools`

`tools` 是子 Agent 的工具白名单。配置后，这个子 Agent 只能使用列出的工具。

```typescript theme={null}
tools: ['Read', 'Grep', 'Glob']
```

常用工具组合：

| 场景     | 推荐工具                                    | 说明             |
| ------ | --------------------------------------- | -------------- |
| 只读分析   | `Read`, `Grep`, `Glob`                  | 能看代码，不能修改或执行命令 |
| 跑测试    | `Bash`, `Read`, `Grep`                  | 能执行测试命令并分析输出   |
| 写代码    | `Read`, `Edit`, `Write`, `Grep`, `Glob` | 能读写文件，但不能直接跑命令 |
| 调用业务工具 | `mcp__server__tool`                     | 只允许调用指定自定义工具   |

<div id="工具黑名单disallowedtools" />

### 工具黑名单：`disallowedTools`

`disallowedTools` 适合“允许大部分工具，只排除少数工具”的场景。

```typescript theme={null}
disallowedTools: ['Bash', 'Write']
```

通常不要同时设置 `tools` 和 `disallowedTools`，除非你明确知道最终工具集合。

<div id="与主会话工具配置的关系" />

### 与主会话工具配置的关系

子 Agent 的 `tools` / `disallowedTools` 只作用于自己，不继承主会话的工具白名单或黑名单裁剪。即使主会话侧只预授权 `Agent` 这条委派路径，子 Agent 仍可以使用自己配置的 `Read`、`Grep` 等工具。

```typescript theme={null}
query({
  prompt: 'Use the analyst agent to inspect the repository.',
  options: {
    // Pre-authorize the main session to call the Agent tool.
    allowedTools: ['Agent'],
    agents: {
      analyst: {
        description: 'Reads and summarizes code structure.',
        prompt: 'Inspect relevant files and return a concise summary. Do not edit files.',
        tools: ['Read', 'Grep', 'Glob'],
      },
    },
  },
});
```

***

<div id="控制子-agent-权限" />

## 控制子 Agent 权限

工具集合决定子 Agent “能调用哪些工具”，权限配置决定这些工具调用“如何审批或阻断”。可以在子 Agent 上单独配置 `permissionMode`，控制它内部工具执行的权限行为。

<div id="权限模式permissionmode" />

### 权限模式：`permissionMode`

```typescript theme={null}
agents: {
  planner: {
    description: 'Plans implementation work without making changes.',
    prompt: 'Read relevant files and return an implementation plan. Do not edit files.',
    tools: ['Read', 'Grep', 'Glob'],
    permissionMode: 'plan',
  },
}
```

`permissionMode` 的完整可选值和语义见 [Agents Reference - permissionMode](/zh/cli/sdk/references#permissionmode)。如果宿主需要逐次审批工具调用，可以使用会话级 `canUseTool` 回调；

***

<div id="为子-agent-加载-skills" />

## 为子 Agent 加载 skills

`skills` 用来给某个子 Agent 预加载专项技能。它适合把特定工作流、团队规范或工具使用方式绑定到一个子 Agent 上，而不是塞进每次调用的 prompt。

```typescript theme={null}
agents: {
  reviewer: {
    description: 'Reviews pull requests using the team review workflow.',
    prompt: 'Review the requested changes and return actionable findings.',
    tools: ['Read', 'Grep', 'Glob'],
    skills: ['review'],
  },
}
```

使用建议：

| 场景                  | 怎么配                                   |
| ------------------- | ------------------------------------- |
| 子 Agent 总是按某个专项流程工作 | 把对应 skill 写进该子 Agent 的 `skills`       |
| 只有主会话需要某个 skill     | 用会话级 `options.skills`，不要放进子 Agent     |
| 插件提供的 skill         | 使用插件限定名，例如 `sdk-test-plugin:sdk-echo` |

子 Agent 的 `skills` 只影响该子 Agent 的上下文，不等同于主会话的 `options.skills`。会话级 skill 行为见 [Skills](/zh/cli/sdk/skills)。

***

<div id="配置子-agent-的-mcpservers" />

## 配置子 Agent 的 mcpServers

`mcpServers` 用来给子 Agent 限定或增加 MCP server。它适合把业务工具只暴露给需要它的子 Agent，例如订单查询、工单检索、内部知识库搜索等。

可以引用会话里已经配置好的 MCP server：

```typescript theme={null}
const q = query({
  prompt: 'Use the support agent to check the latest order status.',
  options: {
    mcpServers: {
      orders: {
        type: 'stdio',
        command: 'node',
        args: ['servers/orders.js'],
      },
    },
    allowedTools: ['Agent'],
    agents: {
      support: {
        description: 'Answers customer support questions using order tools.',
        prompt: 'Use order tools when needed and return a concise answer.',
        mcpServers: ['orders'],
        tools: ['mcp__orders__get_order'],
      },
    },
  },
});
```

也可以给某个子 Agent 配专属 MCP server：

```typescript theme={null}
agents: {
  knowledge: {
    description: 'Searches the internal knowledge base.',
    prompt: 'Search the knowledge base and cite the relevant entries.',
    mcpServers: [
      {
        kb: {
          type: 'stdio',
          command: 'node',
          args: ['servers/kb.js'],
        },
      },
    ],
    tools: ['mcp__kb__search'],
  },
}
```

使用建议：

| 场景                         | 怎么配                                                                |
| -------------------------- | ------------------------------------------------------------------ |
| 多个子 Agent 共用同一个 MCP server | 在会话级 `options.mcpServers` 配置 server，再在子 Agent 的 `mcpServers` 中引用名称 |
| 只有某个子 Agent 需要业务工具         | 把 server 放到该子 Agent 的 `mcpServers`，并用 `tools` 限定可调用工具              |
| 只想调用某个 MCP 工具              | 同时配置 `tools: ['mcp__server__tool']`，避免暴露整个 server 的所有工具            |

MCP server 配置结构见 [MCP](/zh/cli/sdk/mcp) 和 [Agents Reference - mcpServers](/zh/cli/sdk/references#mcpservers)。

***

<div id="调用子-agent" />

## 调用子 Agent

子 Agent 有三种常见调用方式。

<div id="自动调用" />

### 自动调用

模型会根据任务和每个子 Agent 的 `description` 自动决定是否调用。写清楚 `description` 能提升命中准确性。

```typescript theme={null}
agents: {
  tester: {
    description: 'Runs tests and analyzes test failures.',
    prompt: 'Run relevant tests and explain any failures clearly.',
    tools: ['Bash', 'Read', 'Grep'],
  },
}
```

<div id="显式点名调用" />

### 显式点名调用

如果你希望模型使用某个子 Agent，可以在 prompt 里点名。

```typescript theme={null}
const q = query({
  prompt: 'Use the tester agent to run the unit tests and summarize failures.',
  options: {
    // Pre-authorize Agent tool calls. If options.tools restricts the tool set, include 'Agent' there too.
    allowedTools: ['Agent'],
    agents: {
      tester: {
        description: 'Runs tests and analyzes failures.',
        prompt: 'Run the requested tests and explain failures clearly.',
        tools: ['Bash', 'Read', 'Grep'],
      },
    },
  },
});
```

<div id="作为主会话角色运行" />

### 作为主会话角色运行

`options.agent` 让主会话直接以某个子 Agent 身份运行。

```typescript theme={null}
const q = query({
  prompt: 'Plan the refactor for the payment module.',
  options: {
    agents: {
      planner: {
        description: 'Plans implementation work before code changes.',
        prompt: 'Break the task into clear steps, risks, and validation checks.',
        tools: ['Read', 'Grep', 'Glob'],
        model: 'inherit',
      },
    },
    agent: 'planner',
  },
});
```

`options.agent` 可以引用 `options.agents` 里的自定义子 Agent，也可以引用当前 CLI 已发现的内置 / 用户 / 项目 / 插件子 Agent。

***

<div id="子-agent-上下文与结果" />

## 子 Agent 上下文与结果

子 Agent 在独立上下文中运行。它会收到自己的系统提示词和委派 prompt，但不会直接继承父会话完整历史。

| 子 Agent 能看到                  | 子 Agent 看不到     |
| ---------------------------- | --------------- |
| 自己的 `prompt`                 | 父会话的完整对话历史      |
| 主会话通过 `Agent` 工具传入的任务 prompt | 父会话的中间工具结果      |
| 自己可用的工具定义                    | 未传给它的父会话私有推理过程  |
| 按配置预加载的 skills               | 其他 Agent 的中间上下文 |

父会话传信息给子 Agent 的主要通道，是调用 Agent 工具时传入的任务 prompt。因此，如果子 Agent 需要特定文件路径、错误信息或业务背景，应该让主会话在委派时明确传过去。

子 Agent 完成后，父会话收到的是它的最终返回，而不是它内部每一步工具调用的全部上下文。这也是使用子 Agent 隔离上下文的主要价值。

***

<div id="组合示例" />

## 组合示例

<div id="多角色协作" />

### 多角色协作

注册多个角色不同的子 Agent，主会话根据任务需要决定是否调用、何时调用。

```typescript theme={null}
const q = query({
  prompt: 'Add input validation to the user registration endpoint.',
  options: {
    // Pre-authorize Agent tool calls. If options.tools restricts the tool set, include 'Agent' there too.
    allowedTools: ['Agent'],
    agents: {
      researcher: {
        description: 'Reads existing code to understand patterns and constraints.',
        prompt: 'Research relevant files and report implementation constraints. Do not edit.',
        tools: ['Read', 'Grep', 'Glob'],
        maxTurns: 8,
      },
      implementer: {
        description: 'Implements code changes following existing project conventions.',
        prompt: 'Implement the requested change with minimal, idiomatic edits.',
        tools: ['Read', 'Edit', 'Write', 'Grep', 'Glob'],
        maxTurns: 12,
      },
      tester: {
        description: 'Runs tests and explains failures.',
        prompt: 'Run relevant tests, summarize results, and identify failing cases.',
        tools: ['Bash', 'Read', 'Grep'],
        maxTurns: 6,
      },
    },
  },
});
```

<div id="启动后自动执行首轮任务" />

### 启动后自动执行首轮任务

`initialPrompt` 只在该子 Agent 通过 `options.agent` 成为主会话角色时生效：

```typescript theme={null}
const q = query({
  prompt: '',
  options: {
    agents: {
      auditor: {
        description: 'Audits code for security risks.',
        prompt: 'Scan code for security risks and produce a concise report.',
        initialPrompt: 'Start with the authentication and session management code.',
        tools: ['Read', 'Grep', 'Glob'],
        effort: 'high',
      },
    },
    agent: 'auditor',
  },
});
```

如果 `auditor` 是被主会话通过 `Agent` 工具当作子 Agent 调用，`initialPrompt` 会被忽略。

***

<div id="常见踩坑" />

## 常见踩坑

* 直接使用内置子 Agent 时，不要在 `options.agents` 里重复定义同名子 Agent；除非你明确想覆盖它。
* 调用子 Agent 依赖主会话的 `Agent` 工具。`allowedTools: ['Agent']` 是预授权；如果使用 `options.tools` 限定主会话可用工具，也要包含 `Agent`。
* 子 Agent 名称大小写要匹配当前发现结果，例如 `Explore` 和 `Plan` 是大写开头。
* `description` 负责告诉模型何时调用；`prompt` 负责告诉子 Agent 被调用后怎么做。
* 子 Agent 不能再生成自己的子 Agent。不要把 `Agent` 放进子 Agent 的 `tools`。
* `initialPrompt` 只对 `options.agent` 指定的主会话角色生效，作为子 Agent 被委派时会被忽略。
* 子 Agent 专属 MCP server 可通过 `mcpServers` 配置；MCP 连接方式见 [MCP](/zh/cli/sdk/mcp)。

***

<div id="继续阅读" />

## 继续阅读

* [Agents Reference](/zh/cli/sdk/references)：`AgentDefinition`、`AgentInfo`、`options.agent`、`options.agents` 的完整参考。
* [Tools](/zh/cli/sdk/tools)：内置工具、自定义工具和工具权限。
* [权限控制](/zh/cli/sdk/permissions)：`permissionMode`、`allowedTools`、`canUseTool`。
* [Skills](/zh/cli/sdk/skills)：会话级和子 Agent 级 skill 配置。