agent-sdk/typescript.md +28 −6
2386 kind: "task-notification";2386 kind: "task-notification";
2387 subkind?: "scheduled-trigger" | "peer-send-message";2387 subkind?: "scheduled-trigger" | "peer-send-message";
2388 fireReason?: string;2388 fireReason?: string;
2389 runId?: string;
2389 }2390 }
2390 | { kind: "coordinator" }2391 | { kind: "coordinator" }
2391 | { kind: "auto-continuation" }2392 | { kind: "auto-continuation" }
2415 2416
2416`fireReason` 以簡短的小寫 token 說明 `scheduled-trigger` 通知觸發的原因，例如 `scheduled`、`manual`、`retry`、`catch_up` 或 `api`。Anthropic 伺服器會在 [routine](/docs/zh-TW/routines) 的傳遞上設定它，您的應用程式則在宣告排程執行時設定它。當兩者都未傳送時，此欄位不存在。需要 TypeScript Agent SDK v0.3.280 或更新版本。2417`fireReason` 以簡短的小寫 token 說明 `scheduled-trigger` 通知觸發的原因，例如 `scheduled`、`manual`、`retry`、`catch_up` 或 `api`。Anthropic 伺服器會在 [routine](/docs/zh-TW/routines) 的傳遞上設定它，您的應用程式則在宣告排程執行時設定它。當兩者都未傳送時，此欄位不存在。需要 TypeScript Agent SDK v0.3.280 或更新版本。
2417 2418
2419一個背景任務可以在同一個 `task_id` 下執行多次，例如當 Claude [繼續執行 subagent](/docs/zh-TW/agent-sdk/subagents#resume-subagents) 時。每次執行都有其自己的 [`run_id`](#sdktaskstartedmessage)。當某次執行的通知以使用者訊息的形式送達您的工作階段時，該訊息 `task-notification` origin 上的 `runId` 會保有相同的值。通知可能在任務的下一次執行開始後才送達，但它仍帶有較早那次執行的 ID。若要判斷某個回合屬於哪次執行，請比較 `runId`，而非 `task_id`。需要 TypeScript Agent SDK v0.3.292 或更新版本。
2420
2418<h4 id="declare-a-scheduled-run">2421<h4 id="declare-a-scheduled-run">
2419 宣告排程執行2422 宣告排程執行
2420</h4>2423</h4>
3262 工具輸入類型3265 工具輸入類型
3263</h2>3266</h2>
3264 3267
32653268所有內建 Claude Code 工具的輸入 schema 文件。這些類型從 `@anthropic-ai/claude-agent-sdk/sdk-tools` 匯出，可用於類型安全的工具互動。內建 Claude Code 工具的輸入 schema 文件。這些類型從 `@anthropic-ai/claude-agent-sdk/sdk-tools` 匯出，可用於類型安全的工具互動。
3266 3269
3267<h3 id="toolinputschemas">3270<h3 id="toolinputschemas">
3268 `ToolInputSchemas`3271 `ToolInputSchemas`
4078 工具輸出類型4081 工具輸出類型
4079</h2>4082</h2>
4080 4083
40814084所有內建 Claude Code 工具的輸出 schema 文件。這些類型從 `@anthropic-ai/claude-agent-sdk/sdk-tools` 匯出，代表每個工具傳回的實際回應資料。內建 Claude Code 工具的輸出 schema 文件。這些類型從 `@anthropic-ai/claude-agent-sdk/sdk-tools` 匯出，代表每個工具傳回的實際回應資料。
4082 4085
4083<h3 id="tooloutputschemas">4086<h3 id="tooloutputschemas">
4084 `ToolOutputSchemas`4087 `ToolOutputSchemas`
5731 `SDKTaskNotificationMessage`5734 `SDKTaskNotificationMessage`
5732</h3>5735</h3>
5733 5736
57345737背景工作完成、失敗或停止時的通知。背景工作包括 `run_in_background` Bash 命令、[Monitor](#monitor) 監視和背景 subagent。如需 `ambient` 欄位，請參閱 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)，它定義了該欄位及其版本要求。背景工作完成、失敗或停止時的通知。背景工作包括 `run_in_background` Bash 命令、[Monitor](#monitor) 監視和背景 subagent。如需 `run_id` 和 `ambient` 欄位，請參閱 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)，它定義了這些欄位及其版本要求。
5735 5738
5736```typescript theme={null}5739```typescript theme={null}
5737type SDKTaskNotificationMessage = {5740type SDKTaskNotificationMessage = {
5738 type: "system";5741 type: "system";
5739 subtype: "task_notification";5742 subtype: "task_notification";
5740 task_id: string;5743 task_id: string;
5744 run_id?: string;
5741 tool_use_id?: string;5745 tool_use_id?: string;
5742 status: "completed" | "failed" | "stopped";5746 status: "completed" | "failed" | "stopped";
5743 reason?: "worker_restart";5747 reason?: "worker_restart";
5910 type: "system";5914 type: "system";
5911 subtype: "task_started";5915 subtype: "task_started";
5912 task_id: string;5916 task_id: string;
5917 run_id?: string;
5913 tool_use_id?: string;5918 tool_use_id?: string;
5914 description: string;5919 description: string;
5915 task_type?: string;5920 task_type?: string;
5922};5927};
5923```5928```
5924 5929
5930`run_id` 識別工作的一次執行。當工作以相同的 `task_id` 再次執行時，例如 [Claude 恢復的 subagent](/docs/zh-TW/agent-sdk/subagents#resume-subagents)，新的執行會取得新的 `run_id`。該欄位需要 Agent SDK v0.3.292 或更新版本。使用它來區分同一工作的各次執行：
5931
5932* **將訊息與執行進行比對**：同一次執行的 `task_started`、[`task_progress`](#sdktaskprogressmessage)、[`task_updated`](#sdktaskupdatedmessage) 和 [`task_notification`](#sdktasknotificationmessage) 訊息攜帶相同的 `run_id`。每個 [`SDKBackgroundTasksChangedMessage`](#sdkbackgroundtaskschangedmessage) 中該執行的項目也攜帶它，傳遞該執行通知的使用者訊息之 origin 上的 [`runId`](#task-notification-subkinds) 也是如此。
5933* **偵測延遲到達的訊息**：以純字串比較時，同一工作的執行 ID 會依各次執行開始的順序排序，因此 `run_id` 排在您正在顯示的執行之前的訊息來自較早的執行。除了該比較之外，請將此值視為不透明值。
5934* **退回使用 `task_id`**：當訊息未攜帶 `run_id` 時，例如已恢復的工作階段為關閉先前程序所啟動的工作而發出的 `task_notification`，請依 `task_id` 歸屬該訊息。
5935
5936例如，以下三則訊息（已刪減為其識別欄位）來自 Claude 恢復過一次的背景 subagent。兩則 `task_started` 訊息共用同一個 `task_id`，而結束第一次執行的通知攜帶第一次執行的 ID：
5937
5938```json theme={null}
5939{"subtype": "task_started", "task_id": "a5c2e8f41b09d7a36", "run_id": "0mubbs7i8-6f0c2d41"}
5940{"subtype": "task_notification", "task_id": "a5c2e8f41b09d7a36", "run_id": "0mubbs7i8-6f0c2d41", "status": "completed"}
5941{"subtype": "task_started", "task_id": "a5c2e8f41b09d7a36", "run_id": "0mubc18m1-b7719e05"}
5942```
5943
5925`ambient` 對不屬於工作階段工作的工作為 `true`，例如 Claude Code 為其自身運作而執行的工作。即時更新監視器也是環境工作，包括使用者要求的監視器。從活動指示器中排除環境工作。該欄位需要 Agent SDK v0.3.247 或更新版本。5944`ambient` 對不屬於工作階段工作的工作為 `true`，例如 Claude Code 為其自身運作而執行的工作。即時更新監視器也是環境工作，包括使用者要求的監視器。從活動指示器中排除環境工作。該欄位需要 Agent SDK v0.3.247 或更新版本。
5926 5945
5927`ambient` 也出現在 [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) 和 [`SDKBackgroundTasksChangedMessage`](#sdkbackgroundtaskschangedmessage) 項目上。5946`ambient` 也出現在 [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) 和 [`SDKBackgroundTasksChangedMessage`](#sdkbackgroundtaskschangedmessage) 項目上。
5945 `SDKTaskProgressMessage`5964 `SDKTaskProgressMessage`
5946</h3>5965</h3>
5947 5966
59485967在 subagent 或背景工作執行時定期發出。在 subagent 或背景工作執行時定期發出。如需 `run_id` 欄位，請參閱 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)，它定義了該欄位及其版本要求。
5949 5968
5950對於 subagent 工作，`summary` 欄位攜帶模型產生的進度摘要，僅在啟用 [`agentProgressSummaries`](#options) 時填入。對於 [背景化的 MCP 工具呼叫](/docs/zh-TW/mcp#automatic-backgrounding-of-long-tool-calls)，`summary` 攜帶 MCP 伺服器最新報告的進度，不依賴該選項。5969對於 subagent 工作，`summary` 欄位攜帶模型產生的進度摘要，僅在啟用 [`agentProgressSummaries`](#options) 時填入。對於 [背景化的 MCP 工具呼叫](/docs/zh-TW/mcp#automatic-backgrounding-of-long-tool-calls)，`summary` 攜帶 MCP 伺服器最新報告的進度，不依賴該選項。
5951 5970
5954 type: "system";5973 type: "system";
5955 subtype: "task_progress";5974 subtype: "task_progress";
5956 task_id: string;5975 task_id: string;
5976 run_id?: string;
5957 tool_use_id?: string;5977 tool_use_id?: string;
5958 description: string;5978 description: string;
5959 subagent_type?: string;5979 subagent_type?: string;
5973 `SDKTaskUpdatedMessage`5993 `SDKTaskUpdatedMessage`
5974</h3>5994</h3>
5975 5995
59765996在背景工作的狀態變更時發出，例如當它從 `running` 轉換為 `completed` 時。將 `patch` 合併到以 `task_id` 為鍵的本機工作對應表中。`end_time` 欄位是 Unix 紀元時間戳記（以毫秒為單位），可與 `Date.now()` 比較。在背景工作的狀態變更時發出，例如當它從 `running` 轉換為 `completed` 時。將 `patch` 合併到以 `task_id` 為鍵的本機工作對應表中。`end_time` 欄位是 Unix 紀元時間戳記（以毫秒為單位），可與 `Date.now()` 比較。如需 `run_id` 欄位，請參閱 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)，它定義了該欄位及其版本要求。
5977 5997
5978```typescript theme={null}5998```typescript theme={null}
5979type SDKTaskUpdatedMessage = {5999type SDKTaskUpdatedMessage = {
5980 type: "system";6000 type: "system";
5981 subtype: "task_updated";6001 subtype: "task_updated";
5982 task_id: string;6002 task_id: string;
6003 run_id?: string;
5983 patch: {6004 patch: {
5984 status?: "pending" | "running" | "completed" | "failed" | "killed";6005 status?: "pending" | "running" | "completed" | "failed" | "killed";
5985 description?: string;6006 description?: string;
5997 `SDKBackgroundTasksChangedMessage`6018 `SDKBackgroundTasksChangedMessage`
5998</h3>6019</h3>
5999 6020
60006021每當即時背景工作集變更時發出：工作啟動、完成或被終止；前景 agent 被背景化；或工作的 `description`、`ambient` 或 `parent_task_id` 欄位變更。如需每個項目上的 `parent_task_id` 欄位，請參閱 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)，它定義了該欄位及其版本要求。每當即時背景工作集變更時發出：工作啟動、完成或被終止；前景 agent 被背景化；或工作的 `description`、`ambient` 或 `parent_task_id` 欄位變更。如需每個項目上的 `run_id` 和 `parent_task_id` 欄位，請參閱 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)，它定義了這些欄位及其版本要求。
6001 6022
6002`tasks` 陣列是完整的即時集。用每個 payload 替換任何快取集，而不是配對 `task_started` 和 `task_notification` 事件，如此下一個成員資格變更會更正您遺漏的任何事件。6023`tasks` 陣列是完整的即時集。用每個 payload 替換任何快取集，而不是配對 `task_started` 和 `task_notification` 事件，如此下一個成員資格變更會更正您遺漏的任何事件。
6003 6024
6015 subtype: "background_tasks_changed";6036 subtype: "background_tasks_changed";
6016 tasks: {6037 tasks: {
6017 task_id: string;6038 task_id: string;
6039 run_id?: string;
6018 task_type: string;6040 task_type: string;
6019 subagent_type?: string;6041 subagent_type?: string;
6020 description: string;6042 description: string;