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` は、`scheduled-trigger` 通知が発火した理由を、`scheduled`、`manual`、`retry`、`catch_up`、`api` などの短い小文字のトークンで示します。Anthropic のサーバーは[ルーティン](/docs/ja/routines)の配信にこれを設定し、アプリケーションはスケジュール実行を宣言する際にこれを設定します。どちらも送信しなかった場合は存在しません。TypeScript Agent SDK v0.3.280 以降が必要です。2417`fireReason` は、`scheduled-trigger` 通知が発火した理由を、`scheduled`、`manual`、`retry`、`catch_up`、`api` などの短い小文字のトークンで示します。Anthropic のサーバーは[ルーティン](/docs/ja/routines)の配信にこれを設定し、アプリケーションはスケジュール実行を宣言する際にこれを設定します。どちらも送信しなかった場合は存在しません。TypeScript Agent SDK v0.3.280 以降が必要です。
2417 2418
2419Claude が[サブエージェントを再開する](/docs/ja/agent-sdk/subagents#resume-subagents)場合など、バックグラウンドタスクは同じ `task_id` のもとで複数回実行されることがあります。各実行には独自の [`run_id`](#sdktaskstartedmessage) があります。ある実行の通知がユーザーメッセージとしてセッションに届くと、そのメッセージの `task-notification` origin の `runId` に同じ値が入ります。通知はタスクの次の実行が開始された後に届くこともあり、その場合でも以前の実行の ID を持ちます。あるターンがどの実行に属するかを判別するには、`task_id` ではなく `runId` を比較してください。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>
3261 ツール入力型3264 ツール入力型
3262</h2>3265</h2>
3263 3266
32643267すべての組み込み Claude Code ツールの入力スキーマのドキュメント。これらの型は `@anthropic-ai/claude-agent-sdk/sdk-tools` からエクスポートされ、タイプセーフなツール相互作用に使用できます。組み込み Claude Code ツールの入力スキーマのドキュメントです。これらの型は `@anthropic-ai/claude-agent-sdk/sdk-tools` からエクスポートされ、タイプセーフなツール相互作用に使用できます。
3265 3268
3266<h3 id="toolinputschemas">3269<h3 id="toolinputschemas">
3267 `ToolInputSchemas`3270 `ToolInputSchemas`
4077 ツール出力タイプ4080 ツール出力タイプ
4078</h2>4081</h2>
4079 4082
40804083すべての組み込み Claude Code ツールの出力スキーマのドキュメント。これらのタイプは `@anthropic-ai/claude-agent-sdk/sdk-tools` からエクスポートされ、各ツールによって返される実際のレスポンスデータを表します。組み込み Claude Code ツールの出力スキーマのドキュメント。これらのタイプは `@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` はタスクの 1 回の実行を識別します。[Claude が再開するサブエージェント](/docs/ja/agent-sdk/subagents#resume-subagents) のように、タスクが同じ `task_id` で再度実行されると、新しい実行には新しい `run_id` が割り当てられます。フィールドには Agent SDK v0.3.292 以降が必要です。これを使用して、1 つのタスクの実行同士を区別してください。
5930
5931* **メッセージを実行と照合する**: 1 回の実行の `task_started`、[`task_progress`](#sdktaskprogressmessage)、[`task_updated`](#sdktaskupdatedmessage)、[`task_notification`](#sdktasknotificationmessage) メッセージは同じ `run_id` を持ちます。各 [`SDKBackgroundTasksChangedMessage`](#sdkbackgroundtaskschangedmessage) 内のその実行のエントリも同じ値を持ち、その実行の通知を配信するユーザーメッセージの origin にある [`runId`](#task-notification-subkinds) も同様です。
5932* **遅れて届いたメッセージを検出する**: 単純な文字列として比較すると、1 つのタスクの実行 ID は実行が開始された順にソートされるため、`run_id` が表示中の実行より前にソートされるメッセージは以前の実行からのものです。その比較以外では、値を不透明なものとして扱ってください。
5933* **`task_id` にフォールバックする**: 再開されたセッションが以前のプロセスが開始したタスクを閉じるために発行する `task_notification` など、メッセージが `run_id` を持たない場合は、`task_id` によって帰属を判断してください。
5934
5935例えば、識別フィールドのみに絞った以下の 3 つのメッセージは、Claude が 1 回再開したバックグラウンドサブエージェントからのものです。2 つの `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`ambient` は、セッションの作業の一部ではないタスク（Claude Code が独自の操作のために実行するタスクなど）の場合は `true` です。ライブアップデートウォッチャーもアンビエントで、ユーザーが要求したウォッチャーを含みます。アクティビティインジケーターからアンビエントタスクを除外してください。フィールドには Agent SDK v0.3.247 以降が必要です。5943`ambient` は、セッションの作業の一部ではないタスク（Claude Code が独自の操作のために実行するタスクなど）の場合は `true` です。ライブアップデートウォッチャーもアンビエントで、ユーザーが要求したウォッチャーを含みます。アクティビティインジケーターからアンビエントタスクを除外してください。フィールドには 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/ja/mcp#automatic-backgrounding-of-long-tool-calls) の場合、`summary` は MCP サーバーが最後に報告した進捗を持ち、そのオプションに依存しません。5968サブエージェントタスクの場合、`summary` フィールドはモデル生成の進捗概要を持ち、[`agentProgressSummaries`](#options) が有効な場合にのみ入力されます。[バックグラウンド化された MCP ツール呼び出し](/docs/ja/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ライブバックグラウンドタスクのセットが変わるたびに発行されます。タスクの開始、完了、キル、フォアグラウンドエージェントのバックグラウンド化、またはタスクの `description`、`ambient`、`parent_task_id` フィールドの変更などです。各エントリの `parent_task_id` フィールドについては、それとそのバージョン要件を定義している [`SDKTaskStartedMessage`](#sdktaskstartedmessage) を参照してください。ライブバックグラウンドタスクのセットが変わるたびに発行されます。タスクの開始、完了、キル、フォアグラウンドエージェントのバックグラウンド化、またはタスクの `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;