SDK 自定义代理

定义代理职责、工具与模型范围，预选代理并观察 subagent 生命周期。

This page has not been translated into English yet. The original Chinese version is shown below.

自定义代理是附着到会话的命名配置；runtime 将部分任务交给它运行时，它成为 subagent。每个代理可以有自己的 prompt、工具和 MCP 配置，执行上下文与父代理分开，事件仍回到父会话流。

定义职责和工具

const session = await client.createSession({
  customAgents: [
    {
      name: "researcher",
      description: "Explores code structure and explains existing behavior",
      prompt: "Analyze the assigned code and report findings with file locations.",
      tools: ["grep", "glob", "view"],
    },
    {
      name: "editor",
      description: "Makes targeted code changes",
      prompt: "Make the requested changes and verify their behavior.",
      tools: ["view", "edit", "bash"],
      infer: false,
    },
  ],
});

name 和 prompt 必填；description 应说明可区分的专业能力，帮助 runtime 匹配任务。上例 researcher 只列出读取工具；editor 的 infer: false 阻止自动选择，适合只由明确请求调用的代理。这里没有设置全局自动批准权限的处理器。

字段	用途
`name`	唯一标识
`displayName`	事件中适合显示的名称
`description`	用于匹配任务的能力说明
`prompt`	代理指令
`tools`	可用工具名称；省略或 null 可访问会话配置的全部工具
`mcpServers`	代理专用 MCP 配置
`infer`	是否允许自动选择，默认 true
`skills`	启动时预加载的技能名称
`model`、`reasoningEffort`	代理运行时的模型与推理强度覆盖

工具列表限定可见能力，不产生操作系统隔离。父会话已经排除的工具，也不能靠子代理再列一次恢复权限。

预选代理与任务委派

会话配置 agent: "researcher" 可在第一个 prompt 前选中同一 customAgents 数组中的代理，名称必须匹配。它相当于创建后调用 session.rpc.agent.select()，省去额外选择调用。

自动委派则由 runtime 将任务与代理的名称和描述匹配，在允许 infer 时选择代理，运行后将结果整合进父代理回答。预选整个会话的活动代理与按任务启动 subagent 是两个入口，不必假设每次配置了代理都会创建子任务。

模型和技能不总是继承

指定 model、reasoningEffort 可以覆盖父会话。省略推理强度时，SDK 不发送该代理的覆盖值，由 runtime 按自己的优先级解析。官方列出每次调用选项、已解析模型默认值或代理定义等优先来源；只有在这些来源未决定且子代理与父代理模型相同时，才会回退继承父代理强度。子代理使用不同模型时回退到该模型默认值，不能一概说继承父会话。

代理 skills 从会话 skillDirectories 按名称解析，并在启动时注入完整内容。省略就不预加载，子代理也不自动继承父代理技能。目录配置见 SDK Skills。

让主代理只负责协调

对于会产生大量结果的工具，可以先在会话 tools 注册其 handler，再通过 defaultAgent.excludedTools 对默认主代理隐藏，同时让特定自定义代理的 tools 包含它。

筛选项	范围	结果
会话 `availableTools`	所有代理	限定整个会话的工具集合
会话 `excludedTools`	所有代理	全局排除工具
`defaultAgent.excludedTools`	默认主代理	隐藏工具，但不删除 handler，也不阻止获准的子代理调用

先应用会话筛选，再应用默认代理筛选。把同一工具同时放进会话 excludedTools 和默认代理排除列表，结果仍是所有代理都不可用。此机制适合把重型分析结果留在专门代理上下文，不是绕过会话权限。

展示子任务进度

父会话可订阅以下生命周期事件：

事件	主要信息
`subagent.selected`	agentName、agentDisplayName、tools
`subagent.started`	toolCallId、名称、描述、可选 model
`subagent.completed`	toolCallId、名称，以及可选 model、durationMs、totalTokens、totalToolCalls
`subagent.failed`	同类关联信息和 error，部分统计可选
`subagent.deselected`	切回后的生命周期通知

按 toolCallId 关联启动、成功与失败，按事件信封 agentId 区分子代理来源；主代理及会话级事件省略 agentId。不要把子代理文本增量当主回答直接拼接。更完整的渲染字段见事件流，同时运行多个独立子任务见 Fleet。