Claude Code官方文档Agent SDKTypeScriptAPI 参考

Claude Agent SDK TypeScript 完整 API 参考

TypeScript Agent SDK 的完整 API 参考，包括所有函数、类型和接口。

发布于 2025年5月1日 · 阅读约 31 分钟

Agent SDK 参考 - TypeScript

TypeScript Agent SDK 的完整 API 参考，包括所有函数、类型和接口。

安装

npm install @anthropic-ai/claude-agent-sdk

ℹ️ SDK 为您的平台捆绑了一个本地 Claude Code 二进制文件，作为可选依赖项。如果您的包管理器跳过可选依赖项，SDK 会抛出 Native CLI binary for <platform> not found；改为将 pathToClaudeCodeExecutable 设置为单独安装的 claude 二进制文件。

核心函数

`query()`

与 Claude Code 交互的主要函数。创建一个异步生成器，在消息到达时流式传输消息。

function query({
  prompt,
  options
}: {
  prompt: string | AsyncIterable<SDKUserMessage>;
  options?: Options;
}): Query;

参数：

prompt: 输入提示，可以是字符串或异步可迭代对象（用于流式模式）
options: 可选配置对象

返回值： Query 对象，扩展 AsyncGenerator<SDKMessage, void>

`startup()`

通过生成 CLI 子进程并在提示可用之前完成初始化握手来预热 CLI 子进程。

function startup(params?: {
  options?: Options;
  initializeTimeoutMs?: number;
}): Promise<WarmQuery>;

示例：

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

// 提前支付启动成本
const warm = await startup({ options: { maxTurns: 3 } });

// 稍后，当提示准备好时，这是立即的
for await (const message of warm.query("What files are here?")) {
  console.log(message);
}

`tool()`

为与 SDK MCP 服务器一起使用创建类型安全的 MCP 工具定义。

function tool<Schema extends AnyZodRawShape>(
  name: string,
  description: string,
  inputSchema: Schema,
  handler: (args: InferShape<Schema>, extra: unknown) => Promise<CallToolResult>,
  extras?: { annotations?: ToolAnnotations }
): SdkMcpToolDefinition<Schema>;

示例：

import { tool } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const searchTool = tool(
  "search",
  "Search the web",
  { query: z.string() },
  async ({ query }) => {
    return { content: [{ type: "text", text: `Results for: ${query}` }] };
  },
  { annotations: { readOnlyHint: true, openWorldHint: true } }
);

`createSdkMcpServer()`

创建在与应用程序相同的进程中运行的 MCP 服务器实例。

function createSdkMcpServer(options: {
  name: string;
  version?: string;
  tools?: Array<SdkMcpToolDefinition<any>>;
}): McpSdkServerConfigWithInstance;

会话管理函数

`listSessions()`

发现并列出具有轻量级元数据的过去会话。

function listSessions(options?: ListSessionsOptions): Promise<SDKSessionInfo[]>;

示例：

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

const sessions = await listSessions({ dir: "/path/to/project", limit: 10 });

for (const session of sessions) {
  console.log(`${session.summary} (${session.sessionId})`);
}

`getSessionMessages()`

从过去的会话记录中读取用户和助手消息。

function getSessionMessages(
  sessionId: string,
  options?: GetSessionMessagesOptions
): Promise<SessionMessage[]>;

示例：

import { listSessions, getSessionMessages } from "@anthropic-ai/claude-agent-sdk";

const [latest] = await listSessions({ dir: "/path/to/project", limit: 1 });

if (latest) {
  const messages = await getSessionMessages(latest.sessionId, {
    dir: "/path/to/project",
    limit: 20
  });

  for (const msg of messages) {
    console.log(`[${msg.type}] ${msg.uuid}`);
  }
}

`getSessionInfo()`

按 ID 读取单个会话的元数据。

function getSessionInfo(
  sessionId: string,
  options?: GetSessionInfoOptions
): Promise<SDKSessionInfo | undefined>;

`renameSession()`

通过附加自定义标题条目来重命名会话。

function renameSession(
  sessionId: string,
  title: string,
  options?: SessionMutationOptions
): Promise<void>;

`tagSession()`

标记会话。传递 null 以清除标签。

function tagSession(
  sessionId: string,
  tag: string | null,
  options?: SessionMutationOptions
): Promise<void>;

设置函数

`resolveSettings()`

为给定目录解析有效的 Claude Code 设置，无需生成 Claude CLI。

function resolveSettings(
  options?: ResolveSettingsOptions
): Promise<ResolvedSettings>;

示例：

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

const { effective, provenance } = await resolveSettings({
  cwd: "/path/to/project",
  settingSources: ["user", "project", "local"],
});

console.log(`Cleanup period: ${effective.cleanupPeriodDays} days`);
console.log(`Set by: ${provenance.cleanupPeriodDays?.source}`);

Options 类型

query() 函数的配置对象，包含以下主要属性：

属性	类型	默认值	描述
`abortController`	`AbortController`	`new AbortController()`	用于取消操作的控制器
`additionalDirectories`	`string[]`	`[]`	Claude 可以访问的其他目录
`agent`	`string`	`undefined`	主线程的代理名称
`agents`	`Record<string, AgentDefinition>`	`undefined`	以编程方式定义子代理
`allowDangerouslySkipPermissions`	`boolean`	`false`	启用绕过权限
`allowedTools`	`string[]`	`[]`	无需提示即可自动批准的工具
`betas`	`SdkBeta[]`	`[]`	启用测试功能
`canUseTool`	`CanUseTool`	`undefined`	工具使用的自定义权限函数
`continue`	`boolean`	`false`	继续最近的对话
`cwd`	`string`	`process.cwd()`	当前工作目录
`debug`	`boolean`	`false`	为 Claude Code 进程启用调试模式
`debugFile`	`string`	`undefined`	将调试日志写入特定文件路径
`disallowedTools`	`string[]`	`[]`	始终拒绝的工具
`effort`	`'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'`	`'high'`	控制 Claude 投入的努力程度
`enableFileCheckpointing`	`boolean`	`false`	启用文件更改跟踪以进行回滚
`env`	`Record<string, string \| undefined>`	`process.env`	环境变量
`executable`	`'bun' \| 'deno' \| 'node'`	自动检测	要使用的 JavaScript 运行时
`executableArgs`	`string[]`	`[]`	传递给可执行文件的参数
`extraArgs`	`Record<string, string \| null>`	`{}`	其他参数
`fallbackModel`	`string`	`undefined`	主模型失败时使用的模型
`forkSession`	`boolean`	`false`	使用 `resume` 恢复时，分叉到新会话 ID
`hooks`	`Partial<Record<HookEvent, HookCallbackMatcher[]>>`	`{}`	事件的 Hook 回调
`includePartialMessages`	`boolean`	`false`	包括部分消息事件
`maxBudgetUsd`	`number`	`undefined`	当客户端成本估计达到此 USD 值时停止查询
`maxTurns`	`number`	`undefined`	最大代理轮次
`mcpServers`	`Record<string, McpServerConfig>`	`{}`	MCP 服务器配置
`model`	`string`	CLI 的默认值	要使用的 Claude 模型
`outputFormat`	`{ type: 'json_schema', schema: JSONSchema }`	`undefined`	为代理结果定义输出格式
`pathToClaudeCodeExecutable`	`string`	从捆绑的本地二进制文件自动解析	Claude Code 可执行文件的路径
`permissionMode`	`PermissionMode`	`'default'`	会话的权限模式
`permissionPromptToolName`	`string`	`undefined`	权限提示的 MCP 工具名称
`persistSession`	`boolean`	`true`	禁用会话持久化到磁盘
`plugins`	`SdkPluginConfig[]`	`[]`	从本地路径加载自定义插件
`promptSuggestions`	`boolean`	`false`	启用提示建议
`resume`	`string`	`undefined`	要恢复的会话 ID
`resumeSessionAt`	`string`	`undefined`	在特定消息 UUID 处恢复会话
`sandbox`	`SandboxSettings`	`undefined`	以编程方式配置沙箱行为
`sessionId`	`string`	自动生成	为会话使用特定的 UUID
`sessionStore`	`SessionStore`	`undefined`	将会话记录镜像到外部后端
`settings`	`string \| Settings`	`undefined`	内联设置对象或设置文件的路径
`settingSources`	`SettingSource[]`	CLI 默认值	控制加载哪些文件系统设置
`skills`	`string[] \| 'all'`	`undefined`	会话可用的技能
`spawnClaudeCodeProcess`	`(options: SpawnOptions) => SpawnedProcess`	`undefined`	用于生成 Claude Code 进程的自定义函数
`stderr`	`(data: string) => void`	`undefined`	stderr 输出的回调
`strictMcpConfig`	`boolean`	`false`	强制执行严格的 MCP 验证
`systemPrompt`	`string \| object`	`undefined`	系统提示配置
`thinking`	`ThinkingConfig`	支持的模型为 `{ type: 'adaptive' }`	控制 Claude 的思考/推理行为
`toolConfig`	`ToolConfig`	`undefined`	内置工具行为的配置
`tools`	`string[] \| { type: 'preset'; preset: 'claude_code' }`	`undefined`	工具配置

处理缓慢或停滞的 API 响应

CLI 子进程读取多个环境变量，这些变量控制 API 超时和停滞检测：

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。
CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS：使用 run_in_background 启动的子代理的停滞监视程序。默认 600000。
CLAUDE_ENABLE_STREAM_WATCHDOG=1 与 CLAUDE_STREAM_IDLE_TIMEOUT_MS：当标头已到达但响应正文停止流式传输时中止请求。默认关闭。

Query 对象

由 query() 函数返回的接口：

interface Query extends AsyncGenerator<SDKMessage, void> {
  interrupt(): Promise<void>;
  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]?: Settings[K] | null }): Promise<void>;
  initializationResult(): Promise<SDKControlInitializeResponse>;
  supportedCommands(): Promise<SlashCommand[]>;
  supportedModels(): Promise<ModelInfo[]>;
  supportedAgents(): Promise<AgentInfo[]>;
  mcpServerStatus(): Promise<McpServerStatus[]>;
  accountInfo(): Promise<AccountInfo>;
  reconnectMcpServer(serverName: string): Promise<void>;
  toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;
  setMcpServers(servers: Record<string, McpServerConfig>): Promise<McpSetServersResult>;
  streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void>;
  stopTask(taskId: string): Promise<void>;
  close(): void;
}

`applyFlagSettings()`

在运行的会话上更改任何设置而无需重新启动查询：

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

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

// 稍后：清除覆盖并回退到较低优先级设置
await q.applyFlagSettings({ model: null });

WarmQuery

由 startup() 返回的句柄：

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

权限类型

`PermissionMode`

type PermissionMode =
  | "default" // 标准权限行为
  | "acceptEdits" // 自动接受文件编辑
  | "bypassPermissions" // 绕过所有权限检查
  | "plan" // 规划模式 - 仅读取工具
  | "dontAsk" // 不提示权限，如果未预先批准则拒绝
  | "auto"; // 使用模型分类器批准或拒绝每个工具调用

`CanUseTool`

用于控制工具使用的自定义权限函数类型：

type CanUseTool = (
  toolName: string,
  input: Record<string, unknown>,
  options: {
    signal: AbortSignal;
    suggestions?: PermissionUpdate[];
    blockedPath?: string;
    decisionReason?: string;
    toolUseID: string;
    agentID?: string;
  }
) => Promise<PermissionResult>;

`PermissionResult`

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

代理定义

`AgentDefinition`

以编程方式定义的子代理的配置：

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

消息类型

`SDKMessage`

查询返回的所有可能消息的联合类型：

type SDKMessage =
  | SDKAssistantMessage
  | SDKUserMessage
  | SDKUserMessageReplay
  | SDKResultMessage
  | SDKSystemMessage
  | SDKPartialAssistantMessage
  | SDKCompactBoundaryMessage
  | SDKStatusMessage
  | SDKLocalCommandOutputMessage
  | SDKHookStartedMessage
  | SDKHookProgressMessage
  | SDKHookResponseMessage
  | SDKPluginInstallMessage
  | SDKToolProgressMessage
  | SDKAuthStatusMessage
  | SDKTaskNotificationMessage
  | SDKTaskStartedMessage
  | SDKTaskProgressMessage
  | SDKTaskUpdatedMessage
  | SDKFilesPersistedEvent
  | SDKToolUseSummaryMessage
  | SDKRateLimitEvent
  | SDKPermissionDeniedMessage
  | SDKPromptSuggestionMessage;

`SDKAssistantMessage`

type SDKAssistantMessage = {
  type: "assistant";
  uuid: UUID;
  session_id: string;
  message: BetaMessage; // 来自 Anthropic SDK
  parent_tool_use_id: string | null;
  error?: SDKAssistantMessageError;
};

`SDKUserMessage`

type SDKUserMessage = {
  type: "user";
  uuid?: UUID;
  session_id: string;
  message: MessageParam; // 来自 Anthropic SDK
  parent_tool_use_id: string | null;
  isSynthetic?: boolean;
  shouldQuery?: boolean;
  tool_use_result?: unknown;
  origin?: SDKMessageOrigin;
};

`SDKResultMessage`

type SDKResultMessage =
  | {
      type: "result";
      subtype: "success";
      uuid: UUID;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      num_turns: number;
      result: string;
      stop_reason: string | null;
      total_cost_usd: number;
      usage: NonNullableUsage;
      modelUsage: { [modelName: string]: ModelUsage };
      permission_denials: SDKPermissionDenial[];
      structured_output?: unknown;
      deferred_tool_use?: { id: string; name: string; input: Record<string, unknown> };
      origin?: SDKMessageOrigin;
    }
  | {
      type: "result";
      subtype:
        | "error_max_turns"
        | "error_during_execution"
        | "error_max_budget_usd"
        | "error_max_structured_output_retries";
      uuid: UUID;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      num_turns: number;
      stop_reason: string | null;
      total_cost_usd: number;
      usage: NonNullableUsage;
      modelUsage: { [modelName: string]: ModelUsage };
      permission_denials: SDKPermissionDenial[];
      errors: string[];
      origin?: SDKMessageOrigin;
    };

`SDKMessageOrigin`

用户角色消息的来源：

type SDKMessageOrigin =
  | { kind: "human" }
  | { kind: "channel"; server: string }
  | { kind: "peer"; from: string; name?: string }
  | { kind: "task-notification" }
  | { kind: "coordinator" };

Hook 类型

`HookEvent`

可用的 hook 事件：

type HookEvent =
  | "PreToolUse"
  | "PostToolUse"
  | "PostToolUseFailure"
  | "PostToolBatch"
  | "Notification"
  | "UserPromptSubmit"
  | "SessionStart"
  | "SessionEnd"
  | "Stop"
  | "SubagentStart"
  | "SubagentStop"
  | "PreCompact"
  | "PermissionRequest"
  | "Setup"
  | "TeammateIdle"
  | "TaskCompleted"
  | "ConfigChange"
  | "WorktreeCreate"
  | "WorktreeRemove";

`HookCallback`

Hook 回调函数类型：

type HookCallback = (
  input: HookInput,
  toolUseID: string | undefined,
  options: { signal: AbortSignal }
) => Promise<HookJSONOutput>;

`HookCallbackMatcher`

带有可选匹配器的 Hook 配置：

interface HookCallbackMatcher {
  matcher?: string;
  hooks: HookCallback[];
  timeout?: number; // 此匹配器中所有 hooks 的超时时间（秒）
}

工具输入类型

`ToolInputSchemas`

所有工具输入类型的联合：

type ToolInputSchemas =
  | AgentInput
  | AskUserQuestionInput
  | BashInput
  | TaskOutputInput
  | EnterWorktreeInput
  | ExitPlanModeInput
  | FileEditInput
  | FileReadInput
  | FileWriteInput
  | GlobInput
  | GrepInput
  | ListMcpResourcesInput
  | McpInput
  | MonitorInput
  | NotebookEditInput
  | ReadMcpResourceInput
  | SubscribeMcpResourceInput
  | SubscribePollingInput
  | TaskStopInput
  | TodoWriteInput
  | UnsubscribeMcpResourceInput
  | UnsubscribePollingInput
  | WebFetchInput
  | WebSearchInput;

常用工具输入

`BashInput`

type BashInput = {
  command: string;
  timeout?: number;
  description?: string;
  run_in_background?: boolean;
  dangerouslyDisableSandbox?: boolean;
};

`FileReadInput`

type FileReadInput = {
  file_path: string;
  offset?: number;
  limit?: number;
  pages?: string;
};

`FileWriteInput`

type FileWriteInput = {
  file_path: string;
  content: string;
};

`FileEditInput`

type FileEditInput = {
  file_path: string;
  old_string: string;
  new_string: string;
  replace_all?: boolean;
};

`WebSearchInput`

type WebSearchInput = {
  query: string;
  allowed_domains?: string[];
  blocked_domains?: string[];
};

`AgentInput`

type AgentInput = {
  description: string;
  prompt: string;
  subagent_type: string;
  model?: "sonnet" | "opus" | "haiku";
  resume?: string;
  run_in_background?: boolean;
  max_turns?: number;
  name?: string;
  team_name?: string;
  mode?: "acceptEdits" | "bypassPermissions" | "default" | "dontAsk" | "plan";
  isolation?: "worktree";
};

其他类型

`ThinkingConfig`

控制 Claude 的思考/推理行为：

type ThinkingConfig =
  | { type: "adaptive" } // 模型确定何时以及多少推理（Opus 4.6+）
  | { type: "enabled"; budgetTokens?: number } // 固定思考令牌预算
  | { type: "disabled" }; // 无扩展思考

`ModelInfo`

有关可用模型的信息：

type ModelInfo = {
  value: string;
  displayName: string;
  description: string;
  supportsEffort?: boolean;
  supportedEffortLevels?: ("low" | "medium" | "high" | "xhigh" | "max")[];
  supportsAdaptiveThinking?: boolean;
  supportsFastMode?: boolean;
};

`AgentInfo`

有关可通过 Agent 工具调用的可用子代理的信息：

type AgentInfo = {
  name: string;
  description: string;
  model?: string;
};

`AccountInfo`

经过身份验证的用户的帐户信息：

type AccountInfo = {
  email?: string;
  organization?: string;
  subscriptionType?: string;
  tokenSource?: string;
  apiKeySource?: string;
};

`SandboxSettings`

沙箱行为的配置：

type SandboxSettings = {
  enabled?: boolean;
  autoAllowBashIfSandboxed?: boolean;
  excludedCommands?: string[];
  allowUnsandboxedCommands?: boolean;
  network?: SandboxNetworkConfig;
  filesystem?: SandboxFilesystemConfig;
  ignoreViolations?: Record<string, string[]>;
  enableWeakerNestedSandbox?: boolean;
  ripgrep?: { command: string; args?: string[] };
};

有关完整的 TypeScript SDK 类型和接口定义，请参阅 TypeScript SDK 源代码。

本文翻译自 Anthropic Claude Code 官方文档，最近一次同步：2025-05-01。