agent-sdk/typescript.md +27 −5
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` 说明 `scheduled-trigger` 通知为什么触发，作为简短的小写标记，例如 `scheduled`、`manual`、`retry`、`catch_up` 或 `api`。Anthropic 服务器在 [Routine](/docs/zh-CN/routines) 的传递上设置它，您的应用程序在声明定时运行时设置它。当两者都未发送时不存在。需要 TypeScript Agent SDK v0.3.280 或更高版本。2417`fireReason` 说明 `scheduled-trigger` 通知为什么触发，作为简短的小写标记，例如 `scheduled`、`manual`、`retry`、`catch_up` 或 `api`。Anthropic 服务器在 [Routine](/docs/zh-CN/routines) 的传递上设置它，您的应用程序在声明定时运行时设置它。当两者都未发送时不存在。需要 TypeScript Agent SDK v0.3.280 或更高版本。
2417 2418
2419一个后台任务可以在同一个 `task_id` 下运行多次，例如当 Claude [恢复子代理](/docs/zh-CN/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>
4077 工具输出类型4080 工具输出类型
4078</h2>4081</h2>
4079 4082
40804083所有内置 Claude Code 工具的输出 schema 文档。这些类型从 `@anthropic-ai/claude-agent-sdk/sdk-tools` 导出，代表每个工具返回的实际响应数据。内置 Claude Code 工具的输出 schema 文档。这些类型从 `@anthropic-ai/claude-agent-sdk/sdk-tools` 导出，代表每个工具返回的实际响应数据。
4081 4084
4082<h3 id="tooloutputschemas">4085<h3 id="tooloutputschemas">
4083 `ToolOutputSchemas`4086 `ToolOutputSchemas`
5730 `SDKTaskNotificationMessage`5733 `SDKTaskNotificationMessage`
5731</h3>5734</h3>
5732 5735
57335736后台任务完成、失败或被停止时的通知。后台任务包括 `run_in_background` Bash 命令、[Monitor](#monitor) 监视以及后台子代理。有关 `ambient` 字段，请参阅 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)，其中定义了该字段及其版本要求。后台任务完成、失败或被停止时的通知。后台任务包括 `run_in_background` Bash 命令、[Monitor](#monitor) 监视以及后台子代理。有关 `run_id` 和 `ambient` 字段，请参阅 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)，其中定义了这些字段及其版本要求。
5734 5737
5735```typescript theme={null}5738```typescript theme={null}
5736type SDKTaskNotificationMessage = {5739type SDKTaskNotificationMessage = {
5737 type: "system";5740 type: "system";
5738 subtype: "task_notification";5741 subtype: "task_notification";
5739 task_id: string;5742 task_id: string;
5743 run_id?: string;
5740 tool_use_id?: string;5744 tool_use_id?: string;
5741 status: "completed" | "failed" | "stopped";5745 status: "completed" | "failed" | "stopped";
5742 reason?: "worker_restart";5746 reason?: "worker_restart";
5909 type: "system";5913 type: "system";
5910 subtype: "task_started";5914 subtype: "task_started";
5911 task_id: string;5915 task_id: string;
5916 run_id?: string;
5912 tool_use_id?: string;5917 tool_use_id?: string;
5913 description: string;5918 description: string;
5914 task_type?: string;5919 task_type?: string;
5921};5926};
5922```5927```
5923 5928
5929`run_id` 标识任务的一次运行。当任务以相同的 `task_id` 再次运行时（例如 [Claude 恢复的子代理](/docs/zh-CN/agent-sdk/subagents#resume-subagents)），新的运行会获得新的 `run_id`。该字段需要 Agent SDK v0.3.292 或更高版本。使用它来区分同一任务的各次运行：
5930
5931* **将消息与某次运行匹配**：同一次运行的 `task_started`、[`task_progress`](#sdktaskprogressmessage)、[`task_updated`](#sdktaskupdatedmessage) 和 [`task_notification`](#sdktasknotificationmessage) 消息携带相同的 `run_id`。每条 [`SDKBackgroundTasksChangedMessage`](#sdkbackgroundtaskschangedmessage) 中该运行的条目也携带它，传递该运行通知的用户消息的 origin 上的 [`runId`](#task-notification-subkinds) 也是如此。
5932* **检测迟到的消息**：按普通字符串比较时，同一任务的各个运行 ID 按运行开始的顺序排序，因此如果某条消息的 `run_id` 排在您正在显示的运行之前，则它来自更早的运行。除该比较外，请将该值视为不透明值。
5933* **回退到 `task_id`**：当消息不携带 `run_id` 时（例如恢复的会话为关闭先前进程启动的任务而发出的 `task_notification`），请按 `task_id` 确定其归属。
5934
5935例如，以下三条消息（已精简为其标识字段）来自一个被 Claude 恢复过一次的后台子代理。两条 `task_started` 消息共享同一个 `task_id`，结束第一次运行的通知携带第一次运行的 ID：
5936
5937```json theme={null}
5938{"subtype": "task_started", "task_id": "a5c2e8f41b09d7a36", "run_id": "0mubbs7i8-6f0c2d41"}
5939{"subtype": "task_notification", "task_id": "a5c2e8f41b09d7a36", "run_id": "0mubbs7i8-6f0c2d41", "status": "completed"}
5940{"subtype": "task_started", "task_id": "a5c2e8f41b09d7a36", "run_id": "0mubc18m1-b7719e05"}
5941```
5942
5924对于不属于会话工作的任务（例如 Claude Code 为其自身运行而执行的任务），`ambient` 为 `true`。实时更新监视器也属于 ambient，包括用户要求的监视器。请将 ambient 任务从活动指示器中排除。该字段需要 Agent SDK v0.3.247 或更高版本。5943对于不属于会话工作的任务（例如 Claude Code 为其自身运行而执行的任务），`ambient` 为 `true`。实时更新监视器也属于 ambient，包括用户要求的监视器。请将 ambient 任务从活动指示器中排除。该字段需要 Agent SDK v0.3.247 或更高版本。
5925 5944
5926`ambient` 也出现在 [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) 以及 [`SDKBackgroundTasksChangedMessage`](#sdkbackgroundtaskschangedmessage) 的条目上。5945`ambient` 也出现在 [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) 以及 [`SDKBackgroundTasksChangedMessage`](#sdkbackgroundtaskschangedmessage) 的条目上。
5944 `SDKTaskProgressMessage`5963 `SDKTaskProgressMessage`
5945</h3>5964</h3>
5946 5965
59475966在子代理或后台任务运行期间定期发出。在子代理或后台任务运行期间定期发出。有关 `run_id` 字段，请参阅 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)，其中定义了该字段及其版本要求。
5948 5967
5949对于子代理任务，`summary` 字段携带模型生成的进度摘要，仅在启用 [`agentProgressSummaries`](#options) 时填充。对于[已移到后台的 MCP 工具调用](/docs/zh-CN/mcp#automatic-backgrounding-of-long-tool-calls)，`summary` 携带 MCP 服务器最近报告的进度，不依赖于该选项。5968对于子代理任务，`summary` 字段携带模型生成的进度摘要，仅在启用 [`agentProgressSummaries`](#options) 时填充。对于[已移到后台的 MCP 工具调用](/docs/zh-CN/mcp#automatic-backgrounding-of-long-tool-calls)，`summary` 携带 MCP 服务器最近报告的进度，不依赖于该选项。
5950 5969
5953 type: "system";5972 type: "system";
5954 subtype: "task_progress";5973 subtype: "task_progress";
5955 task_id: string;5974 task_id: string;
5975 run_id?: string;
5956 tool_use_id?: string;5976 tool_use_id?: string;
5957 description: string;5977 description: string;
5958 subagent_type?: string;5978 subagent_type?: string;
5972 `SDKTaskUpdatedMessage`5992 `SDKTaskUpdatedMessage`
5973</h3>5993</h3>
5974 5994
59755995在后台任务状态发生变化时发出，例如从 `running` 转换为 `completed` 时。请将 `patch` 合并到以 `task_id` 为键的本地任务映射中。`end_time` 字段是以毫秒为单位的 Unix 纪元时间戳，可与 `Date.now()` 比较。在后台任务状态发生变化时发出，例如从 `running` 转换为 `completed` 时。请将 `patch` 合并到以 `task_id` 为键的本地任务映射中。`end_time` 字段是以毫秒为单位的 Unix 纪元时间戳，可与 `Date.now()` 比较。有关 `run_id` 字段，请参阅 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)，其中定义了该字段及其版本要求。
5976 5996
5977```typescript theme={null}5997```typescript theme={null}
5978type SDKTaskUpdatedMessage = {5998type SDKTaskUpdatedMessage = {
5979 type: "system";5999 type: "system";
5980 subtype: "task_updated";6000 subtype: "task_updated";
5981 task_id: string;6001 task_id: string;
6002 run_id?: string;
5982 patch: {6003 patch: {
5983 status?: "pending" | "running" | "completed" | "failed" | "killed";6004 status?: "pending" | "running" | "completed" | "failed" | "killed";
5984 description?: string;6005 description?: string;
5996 `SDKBackgroundTasksChangedMessage`6017 `SDKBackgroundTasksChangedMessage`
5997</h3>6018</h3>
5998 6019
59996020每当活动后台任务集合发生变化时发出：任务启动、完成、被终止、前台 Agent 被移到后台，或任务的 `description`、`ambient` 或 `parent_task_id` 字段发生变化。有关每个条目上的 `parent_task_id` 字段，请参阅 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)，其中定义了该字段及其版本要求。每当活动后台任务集合发生变化时发出：任务启动、完成、被终止、前台 Agent 被移到后台，或任务的 `description`、`ambient` 或 `parent_task_id` 字段发生变化。有关每个条目上的 `run_id` 和 `parent_task_id` 字段，请参阅 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)，其中定义了这些字段及其版本要求。
6000 6021
6001`tasks` 数组是完整的活动集合。请用每次的负载替换任何缓存的集合，而不是对 `task_started` 和 `task_notification` 事件进行配对，这样下一次成员变化就会纠正您错过的任何事件。6022`tasks` 数组是完整的活动集合。请用每次的负载替换任何缓存的集合，而不是对 `task_started` 和 `task_notification` 事件进行配对，这样下一次成员变化就会纠正您错过的任何事件。
6002 6023
6014 subtype: "background_tasks_changed";6035 subtype: "background_tasks_changed";
6015 tasks: {6036 tasks: {
6016 task_id: string;6037 task_id: string;
6038 run_id?: string;
6017 task_type: string;6039 task_type: string;
6018 subagent_type?: string;6040 subagent_type?: string;
6019 description: string;6041 description: string;