Agent SDK 參考 - TypeScript

安裝

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

函數

`query()`

與 Claude Code 互動的主要函數。建立一個非同步生成器，在訊息到達時進行串流傳輸。

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

參數

參數	類型	描述
`prompt`	`string \| AsyncIterable<SDKUserMessage>`	輸入提示，可以是字串或非同步可迭代物件（用於串流模式）
`options`	`Options`	選用的配置物件（請參閱下方的 Options 類型）

返回值

返回一個 Query 物件，擴展 AsyncGenerator<SDKMessage, void>，並具有其他方法。

`tool()`

建立一個類型安全的 MCP 工具定義，用於 SDK MCP 伺服器。

function tool<Schema extends ZodRawShape>(
  name: string,
  description: string,
  inputSchema: Schema,
  handler: (args: z.infer<ZodObject<Schema>>, extra: unknown) => Promise<CallToolResult>
): SdkMcpToolDefinition<Schema>

參數

參數	類型	描述
`name`	`string`	工具的名稱
`description`	`string`	工具功能的描述
`inputSchema`	`Schema extends ZodRawShape`	定義工具輸入參數的 Zod 架構
`handler`	`(args, extra) => Promise<CallToolResult>`	執行工具邏輯的非同步函數

`createSdkMcpServer()`

建立一個在與應用程式相同的程序中執行的 MCP 伺服器實例。

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

參數

參數	類型	描述
`options.name`	`string`	MCP 伺服器的名稱
`options.version`	`string`	選用的版本字串
`options.tools`	`Array<SdkMcpToolDefinition>`	使用 `tool()` 建立的工具定義陣列

類型

`Options`

query() 函數的配置物件。

屬性	類型	預設值	描述
`abortController`	`AbortController`	`new AbortController()`	用於取消操作的控制器
`additionalDirectories`	`string[]`	`[]`	Claude 可以存取的其他目錄
`agents`	`Record<string, [`AgentDefinition`](#agentdefinition)>`	`undefined`	以程式設計方式定義子代理
`allowedTools`	`string[]`	所有工具	允許的工具名稱清單
`canUseTool`	`CanUseTool`	`undefined`	工具使用的自訂權限函數
`continue`	`boolean`	`false`	繼續最近的對話
`cwd`	`string`	`process.cwd()`	目前的工作目錄
`disallowedTools`	`string[]`	`[]`	不允許的工具名稱清單
`env`	`Dict<string>`	`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[]>>`	`{}`	事件的鉤子回呼
`includePartialMessages`	`boolean`	`false`	包含部分訊息事件
`maxThinkingTokens`	`number`	`undefined`	思考過程的最大權杖數
`maxTurns`	`number`	`undefined`	最大對話輪數
`mcpServers`	`Record<string, [`McpServerConfig`](#mcpserverconfig)>`	`{}`	MCP 伺服器配置
`model`	`string`	CLI 的預設值	要使用的 Claude 模型
`pathToClaudeCodeExecutable`	`string`	自動偵測	Claude Code 可執行檔的路徑
`permissionMode`	`PermissionMode`	`'default'`	工作階段的權限模式
`permissionPromptToolName`	`string`	`undefined`	權限提示的 MCP 工具名稱
`plugins`	`SdkPluginConfig[]`	`[]`	從本機路徑載入自訂外掛程式。請參閱外掛程式以取得詳細資訊
`resume`	`string`	`undefined`	要繼續的工作階段 ID
`settingSources`	`SettingSource[]`	`[]`（無設定）	控制要載入哪些檔案系統設定。省略時，不會載入任何設定。注意：必須包含 `'project'` 以載入 CLAUDE.md 檔案
`stderr`	`(data: string) => void`	`undefined`	stderr 輸出的回呼
`strictMcpConfig`	`boolean`	`false`	強制執行嚴格的 MCP 驗證
`systemPrompt`	`string \| { type: 'preset'; preset: 'claude_code'; append?: string }`	`undefined`（空提示）	系統提示配置。傳遞字串以取得自訂提示，或傳遞 `{ type: 'preset', preset: 'claude_code' }` 以使用 Claude Code 的系統提示。使用預設物件形式時，新增 `append` 以使用其他指示擴展系統提示

`Query`

query() 函數返回的介面。

interface Query extends AsyncGenerator<SDKMessage, void> {
  interrupt(): Promise<void>;
  setPermissionMode(mode: PermissionMode): Promise<void>;
}

方法

方法	描述
`interrupt()`	中斷查詢（僅在串流輸入模式中可用）
`setPermissionMode()`	變更權限模式（僅在串流輸入模式中可用）

`AgentDefinition`

以程式設計方式定義的子代理的配置。

type AgentDefinition = {
  description: string;
  tools?: string[];
  prompt: string;
  model?: 'sonnet' | 'opus' | 'haiku' | 'inherit';
}

欄位	必需	描述
`description`	是	何時使用此代理的自然語言描述
`tools`	否	允許的工具名稱陣列。如果省略，繼承所有工具
`prompt`	是	代理的系統提示
`model`	否	此代理的模型覆蓋。如果省略，使用主要模型

`SettingSource`

控制 SDK 從哪些檔案系統配置來源載入設定。

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

值	描述	位置
`'user'`	全域使用者設定	`~/.claude/settings.json`
`'project'`	共用專案設定（版本控制）	`.claude/settings.json`
`'local'`	本機專案設定（gitignored）	`.claude/settings.local.json`

預設行為

當 settingSources 省略或未定義時，SDK 不會載入任何檔案系統設定。這為 SDK 應用程式提供隔離。

為什麼使用 settingSources？

載入所有檔案系統設定（舊版行為）：

// 像 SDK v0.0.x 一樣載入所有設定
const result = query({
  prompt: "分析此程式碼",
  options: {
    settingSources: ['user', 'project', 'local']  // 載入所有設定
  }
});

僅載入特定設定來源：

// 僅載入專案設定，忽略使用者和本機設定
const result = query({
  prompt: "執行 CI 檢查",
  options: {
    settingSources: ['project']  // 僅 .claude/settings.json
  }
});

測試和 CI 環境：

// 透過排除本機設定確保 CI 中的一致行為
const result = query({
  prompt: "執行測試",
  options: {
    settingSources: ['project'],  // 僅團隊共用設定
    permissionMode: 'bypassPermissions'
  }
});

僅限 SDK 的應用程式：

// 以程式設計方式定義所有內容（預設行為）
// 無檔案系統相依性 - settingSources 預設為 []
const result = query({
  prompt: "檢閱此 PR",
  options: {
    // settingSources: [] 是預設值，無需指定
    agents: { /* ... */ },
    mcpServers: { /* ... */ },
    allowedTools: ['Read', 'Grep', 'Glob']
  }
});

載入 CLAUDE.md 專案指示：

// 載入專案設定以包含 CLAUDE.md 檔案
const result = query({
  prompt: "按照專案慣例新增功能",
  options: {
    systemPrompt: {
      type: 'preset',
      preset: 'claude_code'  // 使用 CLAUDE.md 時必需
    },
    settingSources: ['project'],  // 從專案目錄載入 CLAUDE.md
    allowedTools: ['Read', 'Write', 'Edit']
  }
});

設定優先順序

載入多個來源時，設定會按此優先順序合併（最高到最低）：

本機設定（.claude/settings.local.json）
專案設定（.claude/settings.json）
使用者設定（~/.claude/settings.json）

程式設計選項（如 agents、allowedTools）始終覆蓋檔案系統設定。

`PermissionMode`

type PermissionMode =
  | 'default'           // 標準權限行為
  | 'acceptEdits'       // 自動接受檔案編輯
  | 'bypassPermissions' // 略過所有權限檢查
  | 'plan'              // 規劃模式 - 無執行

`CanUseTool`

用於控制工具使用的自訂權限函數類型。

type CanUseTool = (
  toolName: string,
  input: ToolInput,
  options: {
    signal: AbortSignal;
    suggestions?: PermissionUpdate[];
  }
) => Promise<PermissionResult>;

`PermissionResult`

權限檢查的結果。

type PermissionResult = 
  | {
      behavior: 'allow';
      updatedInput: ToolInput;
      updatedPermissions?: PermissionUpdate[];
    }
  | {
      behavior: 'deny';
      message: string;
      interrupt?: boolean;
    }

`McpServerConfig`

MCP 伺服器的配置。

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

`McpStdioServerConfig`

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

`McpSSEServerConfig`

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

`McpHttpServerConfig`

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

`McpSdkServerConfigWithInstance`

type McpSdkServerConfigWithInstance = {
  type: 'sdk';
  name: string;
  instance: McpServer;
}

`SdkPluginConfig`

SDK 中載入外掛程式的配置。

type SdkPluginConfig = {
  type: 'local';
  path: string;
}

欄位	類型	描述
`type`	`'local'`	必須為 `'local'`（目前僅支援本機外掛程式）
`path`	`string`	外掛程式目錄的絕對或相對路徑

範例：

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

如需建立和使用外掛程式的完整資訊，請參閱外掛程式。

訊息類型

`SDKMessage`

查詢返回的所有可能訊息的聯合類型。

type SDKMessage = 
  | SDKAssistantMessage
  | SDKUserMessage
  | SDKUserMessageReplay
  | SDKResultMessage
  | SDKSystemMessage
  | SDKPartialAssistantMessage
  | SDKCompactBoundaryMessage;

`SDKAssistantMessage`

助手回應訊息。

type SDKAssistantMessage = {
  type: 'assistant';
  uuid: UUID;
  session_id: string;
  message: APIAssistantMessage; // 來自 Anthropic SDK
  parent_tool_use_id: string | null;
}

`SDKUserMessage`

使用者輸入訊息。

type SDKUserMessage = {
  type: 'user';
  uuid?: UUID;
  session_id: string;
  message: APIUserMessage; // 來自 Anthropic SDK
  parent_tool_use_id: string | null;
}

`SDKUserMessageReplay`

具有必需 UUID 的重播使用者訊息。

type SDKUserMessageReplay = {
  type: 'user';
  uuid: UUID;
  session_id: string;
  message: APIUserMessage;
  parent_tool_use_id: string | null;
}

`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;
      total_cost_usd: number;
      usage: NonNullableUsage;
      permission_denials: SDKPermissionDenial[];
    }
  | {
      type: 'result';
      subtype: 'error_max_turns' | 'error_during_execution';
      uuid: UUID;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      num_turns: number;
      total_cost_usd: number;
      usage: NonNullableUsage;
      permission_denials: SDKPermissionDenial[];
    }

`SDKSystemMessage`

系統初始化訊息。

type SDKSystemMessage = {
  type: 'system';
  subtype: 'init';
  uuid: UUID;
  session_id: string;
  apiKeySource: ApiKeySource;
  cwd: string;
  tools: string[];
  mcp_servers: {
    name: string;
    status: string;
  }[];
  model: string;
  permissionMode: PermissionMode;
  slash_commands: string[];
  output_style: string;
}

`SDKPartialAssistantMessage`

串流部分訊息（僅當 includePartialMessages 為 true 時）。

type SDKPartialAssistantMessage = {
  type: 'stream_event';
  event: RawMessageStreamEvent; // 來自 Anthropic SDK
  parent_tool_use_id: string | null;
  uuid: UUID;
  session_id: string;
}

`SDKCompactBoundaryMessage`

指示對話壓縮邊界的訊息。

type SDKCompactBoundaryMessage = {
  type: 'system';
  subtype: 'compact_boundary';
  uuid: UUID;
  session_id: string;
  compact_metadata: {
    trigger: 'manual' | 'auto';
    pre_tokens: number;
  };
}

`SDKPermissionDenial`

有關被拒絕工具使用的資訊。

type SDKPermissionDenial = {
  tool_name: string;
  tool_use_id: string;
  tool_input: ToolInput;
}

鉤子類型

`HookEvent`

可用的鉤子事件。

type HookEvent = 
  | 'PreToolUse'
  | 'PostToolUse'
  | 'Notification'
  | 'UserPromptSubmit'
  | 'SessionStart'
  | 'SessionEnd'
  | 'Stop'
  | 'SubagentStop'
  | 'PreCompact';

`HookCallback`

鉤子回呼函數類型。

type HookCallback = (
  input: HookInput, // 所有鉤子輸入類型的聯合
  toolUseID: string | undefined,
  options: { signal: AbortSignal }
) => Promise<HookJSONOutput>;

`HookCallbackMatcher`

具有選用匹配器的鉤子配置。

interface HookCallbackMatcher {
  matcher?: string;
  hooks: HookCallback[];
}

`HookInput`

所有鉤子輸入類型的聯合類型。

type HookInput = 
  | PreToolUseHookInput
  | PostToolUseHookInput
  | NotificationHookInput
  | UserPromptSubmitHookInput
  | SessionStartHookInput
  | SessionEndHookInput
  | StopHookInput
  | SubagentStopHookInput
  | PreCompactHookInput;

`BaseHookInput`

所有鉤子輸入類型擴展的基本介面。

type BaseHookInput = {
  session_id: string;
  transcript_path: string;
  cwd: string;
  permission_mode?: string;
}

`PreToolUseHookInput`

type PreToolUseHookInput = BaseHookInput & {
  hook_event_name: 'PreToolUse';
  tool_name: string;
  tool_input: ToolInput;
}

`PostToolUseHookInput`

type PostToolUseHookInput = BaseHookInput & {
  hook_event_name: 'PostToolUse';
  tool_name: string;
  tool_input: ToolInput;
  tool_response: ToolOutput;
}

`NotificationHookInput`

type NotificationHookInput = BaseHookInput & {
  hook_event_name: 'Notification';
  message: string;
  title?: string;
}

`UserPromptSubmitHookInput`

type UserPromptSubmitHookInput = BaseHookInput & {
  hook_event_name: 'UserPromptSubmit';
  prompt: string;
}

`SessionStartHookInput`

type SessionStartHookInput = BaseHookInput & {
  hook_event_name: 'SessionStart';
  source: 'startup' | 'resume' | 'clear' | 'compact';
}

`SessionEndHookInput`

type SessionEndHookInput = BaseHookInput & {
  hook_event_name: 'SessionEnd';
  reason: 'clear' | 'logout' | 'prompt_input_exit' | 'other';
}

`StopHookInput`

type StopHookInput = BaseHookInput & {
  hook_event_name: 'Stop';
  stop_hook_active: boolean;
}

`SubagentStopHookInput`

type SubagentStopHookInput = BaseHookInput & {
  hook_event_name: 'SubagentStop';
  stop_hook_active: boolean;
}

`PreCompactHookInput`

type PreCompactHookInput = BaseHookInput & {
  hook_event_name: 'PreCompact';
  trigger: 'manual' | 'auto';
  custom_instructions: string | null;
}

`HookJSONOutput`

鉤子返回值。

type HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput;

`AsyncHookJSONOutput`

type AsyncHookJSONOutput = {
  async: true;
  asyncTimeout?: number;
}

`SyncHookJSONOutput`

type SyncHookJSONOutput = {
  continue?: boolean;
  suppressOutput?: boolean;
  stopReason?: string;
  decision?: 'approve' | 'block';
  systemMessage?: string;
  reason?: string;
  hookSpecificOutput?:
    | {
        hookEventName: 'PreToolUse';
        permissionDecision?: 'allow' | 'deny' | 'ask';
        permissionDecisionReason?: string;
      }
    | {
        hookEventName: 'UserPromptSubmit';
        additionalContext?: string;
      }
    | {
        hookEventName: 'SessionStart';
        additionalContext?: string;
      }
    | {
        hookEventName: 'PostToolUse';
        additionalContext?: string;
      };
}

工具輸入類型

所有內建 Claude Code 工具的輸入架構文件。這些類型從 @anthropic-ai/claude-agent-sdk 匯出，可用於類型安全的工具互動。

`ToolInput`

注意： 這是僅供參考的文件類型。它代表所有工具輸入類型的聯合。

type ToolInput = 
  | AgentInput
  | BashInput
  | BashOutputInput
  | FileEditInput
  | FileReadInput
  | FileWriteInput
  | GlobInput
  | GrepInput
  | KillShellInput
  | NotebookEditInput
  | WebFetchInput
  | WebSearchInput
  | TodoWriteInput
  | ExitPlanModeInput
  | ListMcpResourcesInput
  | ReadMcpResourceInput;

Task

工具名稱： Task

interface AgentInput {
  /**
   * 任務的簡短（3-5 個字）描述
   */
  description: string;
  /**
   * 代理要執行的任務
   */
  prompt: string;
  /**
   * 用於此任務的專用代理類型
   */
  subagent_type: string;
}

啟動新代理以自主處理複雜的多步驟任務。

Bash

工具名稱： Bash

interface BashInput {
  /**
   * 要執行的命令
   */
  command: string;
  /**
   * 選用的逾時時間（以毫秒為單位，最多 600000）
   */
  timeout?: number;
  /**
   * 此命令功能的清晰、簡潔描述（5-10 個字）
   */
  description?: string;
  /**
   * 設定為 true 以在背景執行此命令
   */
  run_in_background?: boolean;
}

在持久性 shell 工作階段中執行 bash 命令，支援選用的逾時和背景執行。

BashOutput

工具名稱： BashOutput

interface BashOutputInput {
  /**
   * 要從中擷取輸出的背景 shell 的 ID
   */
  bash_id: string;
  /**
   * 選用的正規表達式以篩選輸出行
   */
  filter?: string;
}

從執行中或已完成的背景 bash shell 擷取輸出。

Edit

工具名稱： Edit

interface FileEditInput {
  /**
   * 要修改的檔案的絕對路徑
   */
  file_path: string;
  /**
   * 要取代的文字
   */
  old_string: string;
  /**
   * 用來取代它的文字（必須與 old_string 不同）
   */
  new_string: string;
  /**
   * 取代 old_string 的所有出現次數（預設 false）
   */
  replace_all?: boolean;
}

在檔案中執行精確的字串取代。

Read

工具名稱： Read

interface FileReadInput {
  /**
   * 要讀取的檔案的絕對路徑
   */
  file_path: string;
  /**
   * 開始讀取的行號
   */
  offset?: number;
  /**
   * 要讀取的行數
   */
  limit?: number;
}

從本機檔案系統讀取檔案，包括文字、影像、PDF 和 Jupyter 筆記本。

Write

工具名稱： Write

interface FileWriteInput {
  /**
   * 要寫入的檔案的絕對路徑
   */
  file_path: string;
  /**
   * 要寫入檔案的內容
   */
  content: string;
}

將檔案寫入本機檔案系統，如果存在則覆蓋。

Glob

工具名稱： Glob

interface GlobInput {
  /**
   * 要與檔案比對的 glob 模式
   */
  pattern: string;
  /**
   * 要搜尋的目錄（預設為 cwd）
   */
  path?: string;
}

快速檔案模式比對，適用於任何程式碼庫大小。

Grep

工具名稱： Grep

interface GrepInput {
  /**
   * 要搜尋的正規表達式模式
   */
  pattern: string;
  /**
   * 要搜尋的檔案或目錄（預設為 cwd）
   */
  path?: string;
  /**
   * 用於篩選檔案的 glob 模式（例如 "*.js"）
   */
  glob?: string;
  /**
   * 要搜尋的檔案類型（例如 "js"、"py"、"rust"）
   */
  type?: string;
  /**
   * 輸出模式："content"、"files_with_matches" 或 "count"
   */
  output_mode?: 'content' | 'files_with_matches' | 'count';
  /**
   * 不區分大小寫搜尋
   */
  '-i'?: boolean;
  /**
   * 顯示行號（用於內容模式）
   */
  '-n'?: boolean;
  /**
   * 每個比對前要顯示的行數
   */
  '-B'?: number;
  /**
   * 每個比對後要顯示的行數
   */
  '-A'?: number;
  /**
   * 每個比對前後要顯示的行數
   */
  '-C'?: number;
  /**
   * 將輸出限制為前 N 行/項目
   */
  head_limit?: number;
  /**
   * 啟用多行模式
   */
  multiline?: boolean;
}

基於 ripgrep 的強大搜尋工具，支援正規表達式。

KillBash

工具名稱： KillBash

interface KillShellInput {
  /**
   * 要終止的背景 shell 的 ID
   */
  shell_id: string;
}

按 ID 終止執行中的背景 bash shell。

NotebookEdit

工具名稱： NotebookEdit

interface NotebookEditInput {
  /**
   * Jupyter 筆記本檔案的絕對路徑
   */
  notebook_path: string;
  /**
   * 要編輯的儲存格的 ID
   */
  cell_id?: string;
  /**
   * 儲存格的新來源
   */
  new_source: string;
  /**
   * 儲存格的類型（程式碼或 markdown）
   */
  cell_type?: 'code' | 'markdown';
  /**
   * 編輯的類型（取代、插入、刪除）
   */
  edit_mode?: 'replace' | 'insert' | 'delete';
}

編輯 Jupyter 筆記本檔案中的儲存格。

WebFetch

工具名稱： WebFetch

interface WebFetchInput {
  /**
   * 要從中擷取內容的 URL
   */
  url: string;
  /**
   * 要在擷取的內容上執行的提示
   */
  prompt: string;
}

從 URL 擷取內容並使用 AI 模型進行處理。

WebSearch

工具名稱： WebSearch

interface WebSearchInput {
  /**
   * 要使用的搜尋查詢
   */
  query: string;
  /**
   * 僅包含來自這些網域的結果
   */
  allowed_domains?: string[];
  /**
   * 永遠不要包含來自這些網域的結果
   */
  blocked_domains?: string[];
}

搜尋網路並返回格式化的結果。

TodoWrite

工具名稱： TodoWrite

interface TodoWriteInput {
  /**
   * 更新的待辦事項清單
   */
  todos: Array<{
    /**
     * 任務描述
     */
    content: string;
    /**
     * 任務狀態
     */
    status: 'pending' | 'in_progress' | 'completed';
    /**
     * 任務描述的主動形式
     */
    activeForm: string;
  }>;
}

建立和管理結構化任務清單以追蹤進度。

ExitPlanMode

工具名稱： ExitPlanMode

interface ExitPlanModeInput {
  /**
   * 使用者批准要執行的計畫
   */
  plan: string;
}

退出規劃模式並提示使用者批准計畫。

ListMcpResources

工具名稱： ListMcpResources

interface ListMcpResourcesInput {
  /**
   * 選用的伺服器名稱以篩選資源
   */
  server?: string;
}

列出來自已連線伺服器的可用 MCP 資源。

ReadMcpResource

工具名稱： ReadMcpResource

interface ReadMcpResourceInput {
  /**
   * MCP 伺服器名稱
   */
  server: string;
  /**
   * 要讀取的資源 URI
   */
  uri: string;
}

從伺服器讀取特定的 MCP 資源。

工具輸出類型

所有內建 Claude Code 工具的輸出架構文件。這些類型代表每個工具返回的實際回應資料。

`ToolOutput`

注意： 這是僅供參考的文件類型。它代表所有工具輸出類型的聯合。

type ToolOutput = 
  | TaskOutput
  | BashOutput
  | BashOutputToolOutput
  | EditOutput
  | ReadOutput
  | WriteOutput
  | GlobOutput
  | GrepOutput
  | KillBashOutput
  | NotebookEditOutput
  | WebFetchOutput
  | WebSearchOutput
  | TodoWriteOutput
  | ExitPlanModeOutput
  | ListMcpResourcesOutput
  | ReadMcpResourceOutput;

Task

工具名稱： Task

interface TaskOutput {
  /**
   * 來自子代理的最終結果訊息
   */
  result: string;
  /**
   * 權杖使用統計資料
   */
  usage?: {
    input_tokens: number;
    output_tokens: number;
    cache_creation_input_tokens?: number;
    cache_read_input_tokens?: number;
  };
  /**
   * 美元總成本
   */
  total_cost_usd?: number;
  /**
   * 執行持續時間（以毫秒為單位）
   */
  duration_ms?: number;
}

在子代理完成委派任務後返回最終結果。

Bash

工具名稱： Bash

interface BashOutput {
  /**
   * 合併的 stdout 和 stderr 輸出
   */
  output: string;
  /**
   * 命令的結束代碼
   */
  exitCode: number;
  /**
   * 命令是否因逾時而被終止
   */
  killed?: boolean;
  /**
   * 背景程序的 Shell ID
   */
  shellId?: string;
}

返回命令輸出和結束狀態。背景命令立即返回 shellId。

BashOutput

工具名稱： BashOutput

interface BashOutputToolOutput {
  /**
   * 自上次檢查以來的新輸出
   */
  output: string;
  /**
   * 目前的 shell 狀態
   */
  status: 'running' | 'completed' | 'failed';
  /**
   * 結束代碼（完成時）
   */
  exitCode?: number;
}

從背景 shell 返回增量輸出。

Edit

工具名稱： Edit

interface EditOutput {
  /**
   * 確認訊息
   */
  message: string;
  /**
   * 進行的取代次數
   */
  replacements: number;
  /**
   * 已編輯的檔案路徑
   */
  file_path: string;
}

返回成功編輯的確認和取代計數。

Read

工具名稱： Read

type ReadOutput = 
  | TextFileOutput
  | ImageFileOutput
  | PDFFileOutput
  | NotebookFileOutput;

interface TextFileOutput {
  /**
   * 包含行號的檔案內容
   */
  content: string;
  /**
   * 檔案中的總行數
   */
  total_lines: number;
  /**
   * 實際返回的行數
   */
  lines_returned: number;
}

interface ImageFileOutput {
  /**
   * Base64 編碼的影像資料
   */
  image: string;
  /**
   * 影像 MIME 類型
   */
  mime_type: string;
  /**
   * 檔案大小（以位元組為單位）
   */
  file_size: number;
}

interface PDFFileOutput {
  /**
   * 頁面內容陣列
   */
  pages: Array<{
    page_number: number;
    text?: string;
    images?: Array<{
      image: string;
      mime_type: string;
    }>;
  }>;
  /**
   * 總頁數
   */
  total_pages: number;
}

interface NotebookFileOutput {
  /**
   * Jupyter 筆記本儲存格
   */
  cells: Array<{
    cell_type: 'code' | 'markdown';
    source: string;
    outputs?: any[];
    execution_count?: number;
  }>;
  /**
   * 筆記本中繼資料
   */
  metadata?: Record<string, any>;
}

以適合檔案類型的格式返回檔案內容。

Write

工具名稱： Write

interface WriteOutput {
  /**
   * 成功訊息
   */
  message: string;
  /**
   * 寫入的位元組數
   */
  bytes_written: number;
  /**
   * 已寫入的檔案路徑
   */
  file_path: string;
}

成功寫入檔案後返回確認。

Glob

工具名稱： Glob

interface GlobOutput {
  /**
   * 比對的檔案路徑陣列
   */
  matches: string[];
  /**
   * 找到的比對數
   */
  count: number;
  /**
   * 使用的搜尋目錄
   */
  search_path: string;
}

返回與 glob 模式相符的檔案路徑，按修改時間排序。

Grep

工具名稱： Grep

type GrepOutput = 
  | GrepContentOutput
  | GrepFilesOutput
  | GrepCountOutput;

interface GrepContentOutput {
  /**
   * 具有內容的比對行
   */
  matches: Array<{
    file: string;
    line_number?: number;
    line: string;
    before_context?: string[];
    after_context?: string[];
  }>;
  /**
   * 比對總數
   */
  total_matches: number;
}

interface GrepFilesOutput {
  /**
   * 包含比對的檔案
   */
  files: string[];
  /**
   * 包含比對的檔案數
   */
  count: number;
}

interface GrepCountOutput {
  /**
   * 每個檔案的比對計數
   */
  counts: Array<{
    file: string;
    count: number;
  }>;
  /**
   * 所有檔案中的總比對數
   */
  total: number;
}

以 output_mode 指定的格式返回搜尋結果。

KillBash

工具名稱： KillBash

interface KillBashOutput {
  /**
   * 成功訊息
   */
  message: string;
  /**
   * 已終止的 shell 的 ID
   */
  shell_id: string;
}

終止背景 shell 後返回確認。

NotebookEdit

工具名稱： NotebookEdit

interface NotebookEditOutput {
  /**
   * 成功訊息
   */
  message: string;
  /**
   * 執行的編輯類型
   */
  edit_type: 'replaced' | 'inserted' | 'deleted';
  /**
   * 受影響的儲存格 ID
   */
  cell_id?: string;
  /**
   * 編輯後筆記本中的總儲存格數
   */
  total_cells: number;
}

修改 Jupyter 筆記本後返回確認。

WebFetch

工具名稱： WebFetch

interface WebFetchOutput {
  /**
   * AI 模型對提示的回應
   */
  response: string;
  /**
   * 已擷取的 URL
   */
  url: string;
  /**
   * 重新導向後的最終 URL
   */
  final_url?: string;
  /**
   * HTTP 狀態代碼
   */
  status_code?: number;
}

返回 AI 對擷取的網路內容的分析。

WebSearch

工具名稱： WebSearch

interface WebSearchOutput {
  /**
   * 搜尋結果
   */
  results: Array<{
    title: string;
    url: string;
    snippet: string;
    /**
     * 可用的其他中繼資料
     */
    metadata?: Record<string, any>;
  }>;
  /**
   * 結果總數
   */
  total_results: number;
  /**
   * 搜尋的查詢
   */
  query: string;
}

返回來自網路的格式化搜尋結果。

TodoWrite

工具名稱： TodoWrite

interface TodoWriteOutput {
  /**
   * 成功訊息
   */
  message: string;
  /**
   * 目前的待辦事項統計資料
   */
  stats: {
    total: number;
    pending: number;
    in_progress: number;
    completed: number;
  };
}

返回確認和目前的任務統計資料。

ExitPlanMode

工具名稱： ExitPlanMode

interface ExitPlanModeOutput {
  /**
   * 確認訊息
   */
  message: string;
  /**
   * 使用者是否批准計畫
   */
  approved?: boolean;
}

退出規劃模式後返回確認。

ListMcpResources

工具名稱： ListMcpResources

interface ListMcpResourcesOutput {
  /**
   * 可用資源
   */
  resources: Array<{
    uri: string;
    name: string;
    description?: string;
    mimeType?: string;
    server: string;
  }>;
  /**
   * 資源總數
   */
  total: number;
}

返回可用 MCP 資源的清單。

ReadMcpResource

工具名稱： ReadMcpResource

interface ReadMcpResourceOutput {
  /**
   * 資源內容
   */
  contents: Array<{
    uri: string;
    mimeType?: string;
    text?: string;
    blob?: string;
  }>;
  /**
   * 提供資源的伺服器
   */
  server: string;
}

返回所要求 MCP 資源的內容。

權限類型

`PermissionUpdate`

更新權限的操作。

type PermissionUpdate = 
  | {
      type: 'addRules';
      rules: PermissionRuleValue[];
      behavior: PermissionBehavior;
      destination: PermissionUpdateDestination;
    }
  | {
      type: 'replaceRules';
      rules: PermissionRuleValue[];
      behavior: PermissionBehavior;
      destination: PermissionUpdateDestination;
    }
  | {
      type: 'removeRules';
      rules: PermissionRuleValue[];
      behavior: PermissionBehavior;
      destination: PermissionUpdateDestination;
    }
  | {
      type: 'setMode';
      mode: PermissionMode;
      destination: PermissionUpdateDestination;
    }
  | {
      type: 'addDirectories';
      directories: string[];
      destination: PermissionUpdateDestination;
    }
  | {
      type: 'removeDirectories';
      directories: string[];
      destination: PermissionUpdateDestination;
    }

`PermissionBehavior`

type PermissionBehavior = 'allow' | 'deny' | 'ask';

`PermissionUpdateDestination`

type PermissionUpdateDestination = 
  | 'userSettings'     // 全域使用者設定
  | 'projectSettings'  // 每個目錄的專案設定
  | 'localSettings'    // Gitignored 本機設定
  | 'session'          // 僅限目前工作階段

`PermissionRuleValue`

type PermissionRuleValue = {
  toolName: string;
  ruleContent?: string;
}

其他類型

`ApiKeySource`

type ApiKeySource = 'user' | 'project' | 'org' | 'temporary';

`ConfigScope`

type ConfigScope = 'local' | 'user' | 'project';

`NonNullableUsage`

Usage 的版本，所有可為 null 的欄位都變成不可為 null。

type NonNullableUsage = {
  [K in keyof Usage]: NonNullable<Usage[K]>;
}

`Usage`

權杖使用統計資料（來自 @anthropic-ai/sdk）。

type Usage = {
  input_tokens: number | null;
  output_tokens: number | null;
  cache_creation_input_tokens?: number | null;
  cache_read_input_tokens?: number | null;
}

`CallToolResult`

MCP 工具結果類型（來自 @modelcontextprotocol/sdk/types.js）。

type CallToolResult = {
  content: Array<{
    type: 'text' | 'image' | 'resource';
    // 其他欄位因類型而異
  }>;
  isError?: boolean;
}

`AbortError`

中止操作的自訂錯誤類別。

class AbortError extends Error {}

另請參閱

SDK 概述 - 一般 SDK 概念
Python SDK 參考 - Python SDK 文件
CLI 參考 - 命令列介面
常見工作流程 - 逐步指南

第一步

模型與定價

使用 Claude 建構

功能

工具

代理技能

Agent SDK

API 中的 MCP

Claude 在第三方平台上

提示工程

測試與評估

加強防護措施

管理和監控

​安裝

​函數

​query()

​參數

​返回值

​tool()

​參數

​createSdkMcpServer()

​參數

​類型

​Options

​Query

​方法

​AgentDefinition

​SettingSource

​預設行為

​為什麼使用 settingSources？

​設定優先順序

​PermissionMode

​CanUseTool

​PermissionResult

​McpServerConfig

​McpStdioServerConfig

​McpSSEServerConfig

​McpHttpServerConfig

​McpSdkServerConfigWithInstance

​SdkPluginConfig

​訊息類型

​SDKMessage

​SDKAssistantMessage

​SDKUserMessage

​SDKUserMessageReplay

​SDKResultMessage

​SDKSystemMessage

​SDKPartialAssistantMessage

​SDKCompactBoundaryMessage

​SDKPermissionDenial

​鉤子類型

​HookEvent

​HookCallback

​HookCallbackMatcher

​HookInput

​BaseHookInput

​PreToolUseHookInput

​PostToolUseHookInput

​NotificationHookInput

​UserPromptSubmitHookInput

​SessionStartHookInput

​SessionEndHookInput

​StopHookInput

​SubagentStopHookInput

​PreCompactHookInput

​HookJSONOutput

​AsyncHookJSONOutput

​SyncHookJSONOutput

​工具輸入類型

​ToolInput

​Task

​Bash

​BashOutput

​Edit

​Read

​Write

​Glob

​Grep

​KillBash

​NotebookEdit

安裝

函數

`query()`

參數

返回值

`tool()`

參數

`createSdkMcpServer()`

參數

類型

`Options`

`Query`

方法

`AgentDefinition`

`SettingSource`

預設行為

為什麼使用 settingSources？

設定優先順序

`PermissionMode`

`CanUseTool`

`PermissionResult`

`McpServerConfig`

`McpStdioServerConfig`

`McpSSEServerConfig`

`McpHttpServerConfig`

`McpSdkServerConfigWithInstance`

`SdkPluginConfig`

訊息類型

`SDKMessage`

`SDKAssistantMessage`

`SDKUserMessage`

`SDKUserMessageReplay`

`SDKResultMessage`

`SDKSystemMessage`

`SDKPartialAssistantMessage`

`SDKCompactBoundaryMessage`

`SDKPermissionDenial`

鉤子類型

`HookEvent`

`HookCallback`

`HookCallbackMatcher`

`HookInput`

`BaseHookInput`

`PreToolUseHookInput`

`PostToolUseHookInput`

`NotificationHookInput`

`UserPromptSubmitHookInput`

`SessionStartHookInput`

`SessionEndHookInput`

`StopHookInput`

`SubagentStopHookInput`

`PreCompactHookInput`

`HookJSONOutput`

`AsyncHookJSONOutput`

`SyncHookJSONOutput`

工具輸入類型

`ToolInput`

Task

Bash

BashOutput

Edit

Read

Write

Glob

Grep

KillBash

NotebookEdit

WebFetch

WebSearch

TodoWrite

ExitPlanMode

ListMcpResources

ReadMcpResource

工具輸出類型

`ToolOutput`

Task

Bash

BashOutput

Edit

Read