TypeScript SDK 参考：选项与类型

本页是 TypeScript Agent SDK 参考的第二部分：query() 的配置对象 Options、返回的 Query 对象，以及与之配套的类型。函数签名见「TypeScript SDK 参考：安装与函数」。

Options

query() 函数的配置对象。

处理慢或停滞的 API 响应

CLI 子进程读取若干控制 API 超时和停滞检测的环境变量，通过 env 选项传入：

import { query } from "@anthropic-ai/claude-agent-sdk";

const result = query({
  prompt: "Analyze this code",
  options: {
    env: {
      ...process.env,
      API_TIMEOUT_MS: "120000",
      CLAUDE_CODE_MAX_RETRIES: "2",
      CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS: "120000",
    },
  },
});

• API_TIMEOUT_MS：Anthropic 客户端上每个请求的超时毫秒数，默认 600000，适用于主循环和所有子智能体。
• CLAUDE_CODE_MAX_RETRIES：API 最大重试次数，默认 10，上限 15。每次重试有自己的 API_TIMEOUT_MS 窗口，所以最坏的挂钟时间约为 API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1) 加退避。对需要熬过更长故障的无人值守运行，设 CLAUDE_CODE_RETRY_WATCHDOG=1：它对暂时性容量错误无限重试，并且在 Claude Code v2.1.199 及以上把其他暂时性错误的默认值提高到 300 并取消此变量的上限。
• CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS：子智能体的停滞看门狗。流看门狗开着时，默认值是 CLAUDE_STREAM_IDLE_TIMEOUT_MS 加 5 分钟，除非你调高那个变量，否则就是 600000；流看门狗关闭时默认是 600000（v2.1.257 之前默认总是 600000）。计时器在每个流事件上重置；停滞时，Claude Code 中止该子智能体并向父级报告停滞；对后台子智能体，还会把任务标记为失败并附上任何部分结果。
• CLAUDE_ENABLE_STREAM_WATCHDOG 与 CLAUDE_STREAM_IDLE_TIMEOUT_MS：流看门狗在响应头已到达但响应体停止流式传输时中止请求。该看门狗对所有提供商默认开启，设 CLAUDE_ENABLE_STREAM_WATCHDOG=0 禁用；CLAUDE_STREAM_IDLE_TIMEOUT_MS 默认 300000 并被钳到该最小值。看门狗等待 ANTHROPIC_BASE_URL 后面的网关用 keep-alive ping 保持打开的响应期间，设了 includePartialMessages 的宿主会持续收到 ping 流事件，所以把这些帧当作存活信号读取，而不要因静默超时会话（v2.1.257 之前，这些帧在最后一个真实流事件的 5 分钟后停止）。

Query 对象

query() 函数返回的接口。

interface Query extends AsyncGenerator<SDKMessage, void> {
  interrupt(): Promise<SDKControlInterruptResponse | undefined>;
  rewindFiles(
    userMessageId: string,
    options?: { dryRun?: boolean }
  ): Promise<RewindFilesResult>;
  setPermissionMode(mode: PermissionMode): Promise<void>;
  setModel(model?: string): Promise<void>;
  setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>;
  applyFlagSettings(settings: {
    [K in keyof Settings]?: K extends 'effortLevel'
      ? 'low' | 'medium' | 'high' | 'xhigh' | 'max' | null
      : Settings[K] | null;
  }): Promise<void>;
  updateSettings(
    source: 'localSettings' | 'userSettings',
    settings: Record<string, unknown>,
  ): Promise<void>;
  initializationResult(): Promise<SDKControlInitializeResponse>;
  reinitialize(): Promise<SDKControlInitializeResponse>;
  supportedCommands(): Promise<SlashCommand[]>;
  supportedModels(): Promise<ModelInfo[]>;
  supportedAgents(): Promise<AgentInfo[]>;
  mcpServerStatus(): Promise<McpServerStatus[]>;
  getContextUsage(opts?: {
    detail?: 'summary' | 'full';
  }): Promise<SDKControlGetContextUsageResponse>;
  readFile(
    path: string,
    options?: { maxBytes?: number; encoding?: 'utf-8' | 'base64' }
  ): Promise<SDKControlReadFileResponse | null>;
  reloadPlugins(options?: {
    holdOnCacheImpact?: boolean;
  }): Promise<SDKControlReloadPluginsResponse>;
  reloadSkills(): Promise<SDKControlReloadSkillsResponse>;
  reloadOutputStyles(): Promise<SDKControlReloadOutputStylesResponse>;
  accountInfo(): Promise<AccountInfo>;
  reconnectMcpServer(serverName: string): Promise<void>;
  toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;
  setMcpServers(servers: Record<string, McpServerConfig>): Promise<McpSetServersResult>;
  readMcpResource(serverName: string, uri: string): Promise<SDKControlMcpReadResourceResponse>;
  streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void>;
  stopTask(taskId: string): Promise<void>;
  close(): void;
}

applyFlagSettings()

在运行中的会话上更改设置而不必重启查询。当没有专用 setter 的设置需要在会话中途更改时使用，例如在智能体读取了不受信任的输入之后收紧 permissions。setModel() 和 setPermissionMode() 是这两个键的专用 setter；applyFlagSettings() 是接受设置键任意子集的通用形式，在这里传 model 与 setModel() 行为相同。只有一部分键在会话中途生效：

• 在下一个轮次生效：effortLevel、ultracode、permissions、hooks、skillOverrides、fastMode、agent。切换 agent 也会在下一个轮次应用该智能体的模型覆盖和 hooks；它的系统提示在下一个轮次应用，或在复用已记录系统提示的会话里，在会话被压缩后应用。
• 在当前轮次期间生效：model。Claude 正在处理轮次时切换 model，已在生成的响应用旧模型结束，轮次的其余部分（从 Claude Code 下一次调用模型开始）使用新模型；子智能体保持自己的模型（v2.1.212 之前，轮次中途的切换要等到下一个轮次）。
• 会话中途无效：系统提示选项。它们在启动时只解析一次，所以即使调用成功，运行中的会话也保持原值；要更改它们，要启动新会话。

effortLevel 接受努力级别名，也接受 "ultracode"，表示请求 xhigh 努力并开启 ultracode。applyFlagSettings() 声明的 effortLevel 不含该值，所以在 TypeScript 里要传 { ultracode: true, effortLevel: "xhigh" } 得到同样的结果，或单独传 ultracode 键以在会话当前努力级别上开启 ultracode。ultracode 值需要 Claude Code v2.1.203 及以上，并且只被 applyFlagSettings() 接受，设置文件里的 effortLevel 键不接受（v2.1.284 之前，单独的 ultracode 键也会把级别设为 xhigh）。这些值被写入标志设置层，合并在 query() 的内联 settings 选项于启动时设置的内容之上，这正是文档中所说的"编程选项"这一层。连续调用对顶层键做浅合并：第二次带 { permissions: {...} } 的调用会替换上一次调用的整个 permissions 对象，而不是深度合并进去。

要清除用 applyFlagSettings() 设置的键，对该键传 null。多数键随后先回退到 query() 的 settings 选项在启动时设置的值，再回退到较低优先级来源；清除后的 model 重置为 Claude Code 的默认模型，即使设置文件设了 model；传 undefined 无效，因为 JSON 序列化会丢掉它。除 model 外有三个键是重置会话状态而不是回退：effortLevel: null 让会话回到模型的默认努力级别，而不是 query() 的 effort 选项或设置文件里的 effortLevel；agent: null 从下一个轮次起让主线程不带智能体运行，而不是还原 query() 的 agent 选项或设置文件里的 agent（如果被清除的智能体曾应用自己的模型，会话回到它在启动时解析出的模型）；ultracode: null 像 false 一样关闭 ultracode，而不是还原设置文件里的 ultracode 值，会话保持当前努力级别，所以要在同一次调用里传 effortLevel 来更改它。仅在流式输入模式下可用，与 setModel() 和 setPermissionMode() 的限制相同。下面的例子在会话中途切换当前模型，之后清除覆盖，使模型重置为 Claude Code 的默认模型：

import { query } from "@anthropic-ai/claude-agent-sdk";

const q = query({ prompt: messageStream });

// 为会话的其余部分覆盖模型
await q.applyFlagSettings({ model: "claude-opus-4-6" });

// 之后：清除覆盖；模型重置为 Claude Code 的默认值
await q.applyFlagSettings({ model: null });

applyFlagSettings() 只存在于 TypeScript，Python SDK 没有等价方法。

updateSettings()

把一个允许列表内的键写入磁盘上的设置文件，使该值在之后加载该来源的会话里持续。每个来源接受一个键，值为字符串：

• "localSettings"：接受 outputStyle 并合并进项目的本地设置文件 .claude/settings.local.json，新样式在会话的下一个请求上生效。
• "userSettings"：接受 effortLevel，并把它保存为会话当前模型的默认努力级别，写在用户设置文件的 modelSettings 下。传 max 不写入任何东西，因为 max 只限会话。运行中的会话两种情况下都保持当前努力级别，所以还想更改它时要调用 applyFlagSettings()。该来源需要 TypeScript SDK v0.3.277 及以上（捆绑 Claude Code v2.1.277）。

请求携带任何其他键、会话运行在远程传输上、或会话的 settingSources 排除了你点名的来源时，调用会被拒绝；不支持删除键。

WarmQuery

startup() 返回的句柄。子进程已经派生并初始化，所以对该句柄调用 query() 把提示直接写入已就绪的进程，没有启动延迟。

interface WarmQuery extends AsyncDisposable {
  query(prompt: string | AsyncIterable<SDKUserMessage>): Query;
  close(): void;
}

WarmQuery 实现了 AsyncDisposable，所以可以配合 await using 自动清理。

SpareProcess

Alpha。 prewarm() 返回的句柄：一个已启动但尚未绑定会话、可被认领一次的 Claude Code 进程（需要 TypeScript Agent SDK v0.3.282 及以上）。

interface SpareProcess extends AsyncDisposable {
  claim(params: {
    prompt: string | AsyncIterable<SDKUserMessage>;
    options: ClaimOptions;
  }): Query;
  readonly claimed: Promise<{ cwd: string; sessionId: string; parkedMs?: number; sdkMcpSettled: boolean }>;
  readonly exited: Promise<void>;
  close(): void;
}

options.cwd 必需。认领还可以设置 additionalDirectories、model、permissionMode、maxThinkingTokens、settings 里的标志设置覆盖层、appendSystemPrompt、title、agents，以及 env 里的每会话令牌。Claude Code 可能拒绝认领，例如对不存在的文件夹，或其项目设置设了 env、agent 或 model 的文件夹。当 claimed 以 option_not_applied 开头的消息拒绝时，会话在没有你要求的 model 或 maxThinkingTokens 的情况下运行；其他任何拒绝之后，你的提示都没有运行，所以改用 query() 开始会话。

SDKControlInitializeResponse

initializationResult() 的返回类型，包含会话初始化数据。

type SDKControlInitializeResponse = {
  commands: SlashCommand[];
  agents: AgentInfo[];
  output_style: string;
  available_output_styles: string[];
  models: ModelInfo[];
  account: AccountInfo;
  fast_mode_state?: "off" | "cooldown" | "on";
  fast_mode_disabled_reason?: FastModeDisabledReason;
  hooks_applied?: boolean;
};

hooks_applied 报告 Claude Code 是否注册了 initialize 请求携带的 hooks（SDK 在会话开始时发送一次该请求，每次 reinitialize() 调用时再发送一次；该字段需要 Agent SDK v0.3.238 及以上）。请求没带 hooks 时 Claude Code 省略该字段；请求带了 hooks 时，值取决于该请求是不是会话的第一次 initialize，以及对重复的那次，取决于它如何到达会话：true——Claude Code 注册了 hooks（会话的第一次 initialize 返回此值；经 CLI 的 stdin 发送的重复 initialize 也返回 true，此时新请求里的 hooks 替换先前注册的）；false——Claude Code 忽略了 hooks（发给远程会话的重复 initialize 返回此值，所以加入会话的第二个客户端无法替换第一个客户端注册的 hooks）。Agent SDK v0.3.238 之前，响应从不带该字段，Claude Code 在每次重复的 initialize 上都忽略 hooks。

响应总是报告 fast_mode_state，并且在有东西阻止快速模式时，fast_mode_disabled_reason 会随之携带原因代码，让你能解释被阻止的状态而不是重新推导可用性；这两个行为需要 Claude Code v2.1.219 及以上（之前，快速模式不可用时响应省略 fast_mode_state 且从不带原因）。成功的 initialize 的控制响应包装还携带 pending_permission_requests 数组，该字段在响应包装本身上，不在上面的 SDKControlInitializeResponse 载荷里；每个条目是完整的 control_request 消息，形状与会话在运行期间为权限请求流式发出的相同，即 { type: "control_request", request_id, request }。该数组列出这个 Claude Code 进程已发出但尚未解决的权限请求；SDK 替你读取它并把每个条目分派给你的 canUseTool 回调，与 reinitialize() 在传输中断之后触发的重新投递相同；要按重复的请求 ID 幂等处理，因为条目可能重复回调在连接断开前已收到的请求。成功的 initialize 响应里该数组总是存在，进程没有未解决的权限请求时为空（需要 Claude Code v2.1.268 及以上；更早的版本可能省略该字段，所以如果你自己解析线协议，要把缺失的字段视为较旧的 CLI，而不是什么都没有待处理的证据）。

SDKControlInterruptResponse

中断回执：在 SDKSystemMessage.capabilities 里声明了 interrupt_receipt_v1 能力的 CLI 上，interrupt() 以它解析（需要 Claude Code v2.1.205 及以上；更早的 CLI 以空的成功载荷应答中断，所以 interrupt() 解析为 undefined）。

type SDKControlInterruptResponse = {
  still_queued: string[];
  cancelled?: string[];
};

still_queued 列出中断到达时待处理的用户消息的 UUID：仍在队列里的消息，加上 Claude Code 已从队列里取出用于下一个轮次的任何消息。会话的第一个轮次开始之后，除非你先取消它们，Claude Code 在中断之后处理所列消息，并可能把几条合并成一个轮次；如果在第一个轮次开始前中断，Claude Code 在该轮次一开始就中止它，该轮次里所列的消息得不到响应。用回执决定是否重发任何东西：你没取消的所列消息不论是否得到响应都会进入对话，所以重发它会把它两次投递给 Claude。解读这个列表要注意：只有带 UUID 入队的消息才会出现，空数组不表示没有别的东西会运行；只列出主线程消息，发给子智能体的消息不在范围内；列表可能包含你的客户端从未发送的 UUID（如计划任务触发器），要忽略你不认识的 UUID 而不是把它当作错误。

直接驱动 CLI 控制协议（而不是通过 interrupt()）的客户端，可以在 interrupt 控制请求上设 cancel_queued: true。Claude Code v2.1.219 及以上用 SDKSystemMessage.capabilities 里的 interrupt_cancel_queued_v1 能力声明支持，更早的 CLI 忽略该字段并让排队的消息照常运行。这样的中断还会取消本会列在 still_queued 下的每条消息：回执改为把它们列在 cancelled 下，still_queued 为空，它们都不会运行；cancelled 列表与 still_queued 有相同的注意事项；interrupt() 方法从不发送 cancel_queued，所以它解析出的回执不带 cancelled。回执是中断被处理那一刻的快照，在干净的中断上它先于被中断轮次的 SDKResultMessage 到达：要读回执，而不是在那个结果之后检查队列，因为循环会立即开始下一个排队的轮次，所以结果之后你检查的队列已经变了。

SDKControlGetContextUsageResponse

getContextUsage() 的返回类型。默认 detail 下，它是 Claude Code 在交互式会话里为 /context 命令渲染的同一个载荷，所以除了 token 计数，它还携带 color 和 gridRows 这类 Claude Code 用来绘制 /context 用量网格的显示字段。该方法可选的 detail 参数选择 Claude Code 怎么统计每个类别（需要 Agent SDK v0.3.257 及以上）：'full'（默认）——Claude Code 用 token 计数 API 请求统计每个类别，这些请求不出现在消息流里，所以读取消息流的成本跟踪看不到它们（在 Anthropic API 上 token 计数不计费）；'summary'——传 { detail: 'summary' } 从最后一个响应的用量和本地估算得到答案，不发出 token 计数请求，各类别的数字是近似的。把 /context 作为提示发送而不是调用该方法时，Claude Code 把 SDKContextUsage 载荷附加到交付结果的助手消息的 context_usage 字段上（该字段需要 Agent SDK v0.3.232 及以上）。

type SDKControlGetContextUsageResponse = {
  categories: {
    name: string;
    tokens: number;
    color: string;
    isDeferred?: boolean;
    kind: "used" | "free" | "buffer" | "deferred";
  }[];
  totalTokens: number;
  maxTokens: number;
  rawMaxTokens: number;
  percentage: number;
  gridRows: {
    color: string;
    isFilled: boolean;
    categoryName: string;
    tokens: number;
    percentage: number;
    squareFullness: number;
  }[][];
  model: string;
  memoryFiles: {
    path: string;
    type: string;
    tokens: number;
  }[];
  mcpTools: {
    name: string;
    serverName: string;
    tokens: number;
    isLoaded?: boolean;
  }[];
  deferredBuiltinTools?: {
    name: string;
    tokens: number;
    isLoaded: boolean;
  }[];
  systemTools?: {
    name: string;
    tokens: number;
  }[];
  systemPromptSections?: {
    name: string;
    tokens: number;
  }[];
  agents: {
    agentType: string;
    source: string;
    tokens: number;
  }[];
  slashCommands?: {
    totalCommands: number;
    includedCommands: number;
    tokens: number;
  };
  skills?: {
    totalSkills: number;
    includedSkills: number;
    tokens: number;
    skillFrontmatter: {
      name: string;
      source: string;
      tokens: number;
    }[];
  };
  autoCompactThreshold?: number;
  isAutoCompactEnabled: boolean;
  messageBreakdown?: {
    toolCallTokens: number;
    toolResultTokens: number;
    attachmentTokens: number;
    assistantMessageTokens: number;
    userMessageTokens: number;
    redirectedContextTokens: number;
    unattributedTokens: number;
    toolCallsByType: {
      name: string;
      callTokens: number;
      resultTokens: number;
    }[];
    attachmentsByType: {
      name: string;
      tokens: number;
    }[];
  };
  apiUsage: {
    input_tokens: number;
    output_tokens: number;
    cache_creation_input_tokens: number;
    cache_read_input_tokens: number;
  } | null;
};

从集合字段读取 token 归属：categories 持有每个类别的总数，每个条目的 kind 用与 SDKContextUsageCategory 相同的值给该行分类，要按它而不是显示用的 name 分类（该字段需要 Agent SDK v0.3.268 及以上）；mcpTools 和 agents 把 token 归属到单个 MCP 工具和子智能体；memoryFiles 列出每个已加载的记忆文件及其成本；skills.skillFrontmatter 把 skill 列表的 token 归属到每个包含的 skill，每个 skill 的计数衡量的是 Claude Code 实际发送的该 skill 的列表条目，它可能比 skill 的完整 frontmatter 短，比较 skills.totalSkills 与 skills.includedSkills 就能知道是否每个发现的 skill 都进入了列表。totalTokens 是会话当前的上下文用量，maxTokens 是衡量该用量的窗口，也就是模型的上下文窗口，或适用时更低的自动压缩窗口；rawMaxTokens 与 maxTokens 取同一个值，percentage 是 totalTokens 占该窗口的四舍五入百分比；apiUsage 持有最近一次 API 响应的用量，不是会话的累计总数。Claude Code 把可选的 deferredBuiltinTools、systemTools 和 systemPromptSections 诊断字段留空，所以尽管类型声明了它们，也要预期它们不存在。

SDKControlReadFileResponse

readFile() 的返回类型。

type SDKControlReadFileResponse = {
  contents: string;
  absPath: string;
  truncated?: boolean;
  encoding?: 'base64';
};

contents 持有文件文本，或在你请求 encoding: 'base64' 时持有 base64 数据（此时响应的 encoding 字段设为 'base64'）；absPath 是解析后的绝对路径；文件比 maxBytes 上限长且内容在该限制处被截断时设 truncated。readFile() 能读什么：它服务的文件集合比 Read 工具窄：会话工作目录（如 cwd 和 additionalDirectories）之一里的常规文件，以及会话的一些 Claude Code 自己的文件（如工具结果）。Read 的拒绝和询问规则仍会阻止匹配的路径，宽泛的 Read 允许规则也不会把文件系统的其余部分对 readFile() 开放；其他任何东西，调用都以 null 解析。

SDKControlReloadPluginsResponse

reloadPlugins() 的返回类型。

type SDKControlReloadPluginsResponse = {
  commands: SlashCommand[];
  agents: AgentInfo[];
  plugins: {
    name: string;
    path: string;
    source?: string;
    version?: string;
  }[];
  mcpServers: McpServerStatus[];
  error_count: number;
  held?: boolean;
  cache_impact?: {
    mcp_servers_added: string[];
    mcp_servers_removed: string[];
    lsp_tool_change: ("adds" | "may-add" | "removes" | "may-remove") | null;
  };
};

集合字段描述调用之后的会话：commands、agents 和 mcpServers 是会话的命令、子智能体和 MCP 服务器状态，形状与 supportedCommands()、supportedAgents()、mcpServerStatus() 返回的相同（supportedAgents() 继续返回初始化时捕获的列表，所以要读这里的 agents 来得到重新加载后的集合）；plugins 是每个已加载插件及其 name 和安装 path，version 重复插件清单声明的内容，由插件作者控制，所以在信任之前要验证它，清单没声明时省略；error_count 是加载插件的错误数。给 reloadPlugins() 传 { holdOnCacheImpact: true } 可以挂起会使对话的提示缓存失效的重新加载而不是应用它，Claude Code 会运行交互式 /reload-plugins 命令在警告缓存成本之前做的检查（该选项需要 Agent SDK v0.3.268 及以上；你用 pathToClaudeCodeExecutable 指向的、早于 v2.1.268 的 Claude Code 可执行文件会忽略该选项并应用重新加载）。传了该选项时，读 held 了解发生了什么：true——重新加载没有应用，集合字段描述的是会话仍然的样子，cache_impact 说明应用它会改变什么，要仍然应用就不带该选项再次调用 reloadPlugins()；false——检查没有发现缓存影响，重新加载已应用；缺失——你没传该选项，或 Claude Code 可执行文件早于 v2.1.268 并应用了重新加载。cache_impact 仅与 held: true 同时出现：mcp_servers_added 和 mcp_servers_removed 点名该重新加载会注册或丢弃的插件 MCP 服务器，以带范围的 plugin:<plugin>:<server> 名字给出，这些名字由插件作者决定，所以显示之前要验证；lsp_tool_change 说明应用它是否会添加或移除 LSP 工具，两者都不会时为 null，带 may- 的形式表示检查没能完全看到待处理的插件集合。

SDKControlReloadSkillsResponse 与 SDKControlReloadOutputStylesResponse

type SDKControlReloadSkillsResponse = {
  skills: SlashCommand[];
};

type SDKControlReloadOutputStylesResponse = {
  available_output_styles: string[];
};

reloadSkills() 的返回里，skills 列出重新加载后可用的 skills，形状与 supportedCommands() 返回的 SlashCommand 相同；reloadOutputStyles() 的返回里，available_output_styles 列出重新加载后可用的内置和自定义输出样式名。

SDKControlMcpReadResourceResponse

readMcpResource() 的返回类型，携带 MCP 服务器 resources/read 的结果（需要 TypeScript Agent SDK v0.3.280 及以上）。

type SDKControlMcpReadResourceResponse = {
  contents: {
    uri: string;
    mimeType?: string;
    text?: string;
    blob?: string;
    _meta?: Record<string, unknown>;
  }[];
};

给 readMcpResource() 传 mcpServerStatus() 报告的服务器名和一个 ui:// URI（如某个工具在其 _meta 里声明的 ui.resourceUri）。对任何其他 URI 方案、对你的应用自己托管的 SDK MCP 服务器、以及对未连接的服务器，调用都会被拒绝；当 init 消息的 capabilities 包含 mcp_read_resource_v1 时可用。每个 contents 条目是服务器发来的一个内容项，去掉了 com.anthropic/ 前缀下的任何 _meta 键（该前缀为 Claude Code 保留）；blob 对二进制项持有 base64 数据，_meta 是该项自己的 _meta，MCP Apps 服务器把资源的 ui.csp 和 ui.permissions 放在那里。这些内容是不受信任的第三方 HTML，所以要在沙盒里渲染。

AgentDefinition

以编程方式定义的子智能体的配置。

type AgentDefinition = {
  description: string;
  tools?: string[];
  disallowedTools?: string[];
  prompt: string;
  model?: string;
  mcpServers?: AgentMcpServerSpec[];
  skills?: string[];
  initialPrompt?: string;
  maxTurns?: number;
  background?: boolean;
  omitClaudeMd?: boolean;
  memory?: "user" | "project" | "local";
  effort?: "low" | "medium" | "high" | "xhigh" | "max" | number;
  permissionMode?: PermissionMode;
  criticalSystemReminder_EXPERIMENTAL?: string;
};

AgentMcpServerSpec

指定子智能体可用的 MCP 服务器：可以是服务器名（字符串，引用父级 mcpServers 配置里的服务器），或把服务器名映射到配置的内联服务器配置记录。

type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;

其中 McpServerConfigForProcessTransport 是 McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig。

SettingSource

控制 SDK 从哪些基于文件系统的配置来源加载设置。

type SettingSource = "user" | "project" | "local";

默认行为：省略或为 undefined 的 settingSources 让 query() 加载与 Claude Code CLI 相同的文件系统设置：用户、项目和本地。无论该选项如何都会被读取的输入以及如何禁用它们，见「settingSources 不控制什么」。

禁用文件系统设置：

import { query } from "@anthropic-ai/claude-agent-sdk";

// 不从磁盘加载用户、项目或本地设置
const result = query({
  prompt: "Analyze this code",
  options: { settingSources: [] }
});

只加载特定的设置来源：

import { query } from "@anthropic-ai/claude-agent-sdk";

// 只加载项目设置，忽略用户和本地设置
const result = query({
  prompt: "Run CI checks",
  options: {
    settingSources: ["project"] // 只有 .claude/settings.json
  }
});

要加载 CLAUDE.md 项目说明，要在 settingSources 里包含 "project"（CLAUDE.md 加载如何与系统提示选项交互，见「修改系统提示」）。

设置优先级：加载多个来源时，设置按下面的优先级合并（从高到低）：本地设置（.claude/settings.local.json）、项目设置（.claude/settings.json）、用户设置（~/.claude/settings.json）。agents、allowedTools 和 settings 这类编程选项覆盖用户、项目和本地文件系统设置；托管策略设置优先于编程选项。

PermissionMode

type PermissionMode =
  | "default" // 标准权限行为
  | "acceptEdits" // 自动接受文件编辑
  | "bypassPermissions" // 绕过权限检查；显式的 ask 规则仍会提示
  | "plan" // 规划模式——只探索不编辑
  | "dontAsk" // 不提示权限，未预批准就拒绝
  | "auto"; // 由模型分类器审查 shell 命令和网络请求等动作

CanUseTool

控制工具使用的自定义权限函数类型。该函数是 SDK 对交互式权限提示的替代：只在权限评估流程解析为提示时才调用。已经被 allowedTools 条目、设置允许规则或权限模式（如 acceptEdits 或 bypassPermissions）批准的工具调用从不调用它；要把关每个工具调用，用 PreToolUse hook。允许规则不会预批准没有任何模式自动批准的动作；哪些会到达回调以及在 dontAsk 和 auto 模式下发生什么，见「权限如何评估」。

type CanUseTool = (
  toolName: string,
  input: Record<string, unknown>,
  options: {
    signal: AbortSignal;
    suggestions?: PermissionUpdate[];
    blockedPath?: string;
    mcpServer?: { name: string; source: string };
    decisionReason?: string;
    defaultToNo?: boolean;
    suppressAlwaysAllowRule?: boolean;
    toolUseID: string;
    agentID?: string;
    requestId: string;
  }
) => Promise<PermissionResult | null>;

回调通常通过返回 PermissionResult 来解决请求，SDK 把它经传输写回为 control_response。只有当你的应用已经经自己的通道为该请求发送了 control_response（回传 requestId）时才返回 null，SDK 此时跳过向其传输写响应；其他任何情况下返回 null 都会让工具调用被无限期阻塞，因为永远不会发送 control_response，而权限提示不会超时。requestId 选项和 null 返回值需要 Claude Code v2.1.199 及以上。

PermissionResult

权限检查的结果。

type PermissionResult =
  | {
      behavior: "allow";
      updatedInput?: Record<string, unknown>;
      updatedPermissions?: PermissionUpdate[];
      toolUseID?: string;
    }
  | {
      behavior: "deny";
      message: string;
      interrupt?: boolean;
      toolUseID?: string;
    };

ToolConfig

内置工具行为的配置。

type ToolConfig = {
  askUserQuestion?: {
    previewFormat?: "markdown" | "html";
  };
};

askUserQuestion.previewFormat（'markdown' | 'html'）选择加入 AskUserQuestion 选项上的 preview 字段并设置其内容格式；未设置时 Claude 不发出预览。

McpServerConfig

MCP 服务器的配置。

type McpServerConfig =
  | McpStdioServerConfig
  | McpSSEServerConfig
  | McpHttpServerConfig
  | McpSdkServerConfigWithInstance;

type McpStdioServerConfig = {
  type?: "stdio";
  command: string;
  args?: string[];
  env?: Record<string, string>;
};

type McpSSEServerConfig = {
  type: "sse";
  url: string;
  headers?: Record<string, string>;
};

type McpHttpServerConfig = {
  type: "http";
  url: string;
  headers?: Record<string, string>;
};

type McpSdkServerConfigWithInstance = {
  type: "sdk";
  name: string;
  timeout?: number;
  instance: McpServer;
};

type McpClaudeAIProxyServerConfig = {
  type: "claudeai-proxy";
  url: string;
  id: string;
};

SdkPluginConfig

在 SDK 里加载插件的配置。

type SdkPluginConfig = {
  type: "local";
  path: string;
  skipMcpDiscovery?: boolean;
};

plugins: [
  { type: "local", path: "./my-plugin" },
  { type: "local", path: "/absolute/path/to/plugin" }
];

创建和使用插件的完整信息见「插件」。