子 Agent - Qoder

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

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

本文重点讲如何在 SDK 中使用内置子 Agent，以及如何按需自定义子 Agent。你可以顺序阅读，也可以按章节查具体配置项。完整类型定义见 Agents Reference。除非特别说明，本文里的“Agent”都指可以被主会话委派的子 Agent；options.agent 是把某个子 Agent 定义作为主会话角色运行的特殊用法。

内置子 Agent

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

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

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

qodercli agents list

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

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。

使用内置子 Agent

作为主会话角色运行

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

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。

作为子 Agent 委派

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

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()。

自定义子 Agent

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

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

自定义子 Agent 通常分三步：

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

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

使用 options.agents 自定义子 Agent

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

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 只允许读和搜索，所以它不能改文件，也不能执行命令。

`options.agents` 入参

options.agents 是子 Agent 名称到子 Agent 定义的映射。完整类型见 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` 成为主会话角色时生效

配置子 Agent 角色

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

`description`

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

description:
  'Runs project tests, analyzes failing output, and suggests fixes.'

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

`prompt`

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

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.`

配置子 Agent 模型和推理

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

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

可以按这个顺序判断：

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

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、Agents Reference - maxTurns 和 Agents Reference - effort。

控制子 Agent 工具

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

主会话侧的 `Agent` 工具

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

工具白名单：`tools`

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

tools: ['Read', 'Grep', 'Glob']

常用工具组合：

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

工具黑名单：`disallowedTools`

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

disallowedTools: ['Bash', 'Write']

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

与主会话工具配置的关系

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

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'],
      },
    },
  },
});

控制子 Agent 权限

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

权限模式：`permissionMode`

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。如果宿主需要逐次审批工具调用，可以使用会话级 canUseTool 回调；

为子 Agent 加载 skills

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

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。

配置子 Agent 的 mcpServers

mcpServers 用来给子 Agent 限定或增加 MCP server。它适合把业务工具只暴露给需要它的子 Agent，例如订单查询、工单检索、内部知识库搜索等。可以引用会话里已经配置好的 MCP server：

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：

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 和 Agents Reference - mcpServers。

调用子 Agent

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

自动调用

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

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

显式点名调用

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

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'],
      },
    },
  },
});

作为主会话角色运行

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

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。

子 Agent 上下文与结果

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

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

父会话传信息给子 Agent 的主要通道，是调用 Agent 工具时传入的任务 prompt。因此，如果子 Agent 需要特定文件路径、错误信息或业务背景，应该让主会话在委派时明确传过去。子 Agent 完成后，父会话收到的是它的最终返回，而不是它内部每一步工具调用的全部上下文。这也是使用子 Agent 隔离上下文的主要价值。如果宿主需要在父会话结束后检查某个子 Agent 的持久化 transcript，可以先用 listSubagents(sessionId) 获取 subagent ID，再用 getSubagentMessages(sessionId, agentId) 读取该 subagent 的 user / assistant 消息链。见 Session Control 和 Session Transcript APIs。

组合示例

多角色协作

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

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,
      },
    },
  },
});

启动后自动执行首轮任务

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

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 会被忽略。

常见踩坑

直接使用内置子 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。

继续阅读

Agents Reference：AgentDefinition、AgentInfo、options.agent、options.agents 的完整参考。
Tools：内置工具、自定义工具和工具权限。
权限控制：permissionMode、allowedTools、canUseTool。
Skills：会话级和子 Agent 级 skill 配置。

​内置子 Agent

​使用内置子 Agent

​作为主会话角色运行

​作为子 Agent 委派

​自定义子 Agent

​使用 options.agents 自定义子 Agent

​options.agents 入参

​配置子 Agent 角色

​description

​prompt

​配置子 Agent 模型和推理

​控制子 Agent 工具

​主会话侧的 Agent 工具

​工具白名单：tools

​工具黑名单：disallowedTools

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

​控制子 Agent 权限

​权限模式：permissionMode

​为子 Agent 加载 skills

​配置子 Agent 的 mcpServers

​调用子 Agent

​自动调用

​显式点名调用

​作为主会话角色运行

​子 Agent 上下文与结果

​组合示例

​多角色协作

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

​常见踩坑

​继续阅读

内置子 Agent

使用内置子 Agent

作为主会话角色运行

作为子 Agent 委派

自定义子 Agent

使用 options.agents 自定义子 Agent

`options.agents` 入参

配置子 Agent 角色

`description`

`prompt`

配置子 Agent 模型和推理

控制子 Agent 工具

主会话侧的 `Agent` 工具

工具白名单：`tools`

工具黑名单：`disallowedTools`

与主会话工具配置的关系

控制子 Agent 权限

权限模式：`permissionMode`

为子 Agent 加载 skills

配置子 Agent 的 mcpServers

调用子 Agent

自动调用

显式点名调用

作为主会话角色运行

子 Agent 上下文与结果

组合示例

多角色协作

启动后自动执行首轮任务

常见踩坑

继续阅读