# SSE ストリーミングガイド

AGENTIC STAR Chat API の SSE ストリーミングレスポンスの詳細。接続ライフサイクル、レスポンスオブジェクト、エージェント拡張フィールド、エラーハンドリングを解説します。

## 概要

AGENTIC STAR Chat API はレスポンスを SSE（Server-Sent Events）ストリーミングで配信します。各チャンクは OpenAI 互換の ChatCompletionChunk 形式で、エージェント固有の拡張フィールド（タスク情報、対話リクエスト等）が含まれます。

> **ポイント**
>
> - Content-Type は `text/event-stream; charset=utf-8`
> - 各イベントは `data:` プレフィックス付きの JSON 行
> - ストリーム終了は `data: [DONE]` で通知
> - エージェントの長時間タスクでは、再接続・キャンセルのエンドポイントが利用可能

[ユーザー API リファレンス（Chat）に戻る](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference.md#chat)

## 接続ライフサイクル

POST /v1/chat/completions へのリクエスト後、SSE 接続が確立され、以下の順序でイベントが配信されます。

### SSE イベントフロー

```text
: connected                          ← SSE接続確立コメント

data: {"createdAt":"...","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"role":"assistant","messageInfo":{...}}}]}
                                     ↑ ロールチャンク（1回）

data: {"createdAt":"...","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"content":"売上"}}]}
data: {"createdAt":"...","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"content":"データ"}}]}
data: {"createdAt":"...","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"content":"を..."}}]}
                                     ↑ コンテンツチャンク（複数回）

data: {"createdAt":"...","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"content":"...","tasks":[{"messageId":"...","conversationId":"...","actionType":"command_execution","title":"コマンド実行","status":"completed","timestamp":1773499412706}]}}]}
                                     ↑ タスク実行情報を含むチャンク（複数回）

: heartbeat                          ← コネクション維持コメント（約15秒間隔、アイドル時のみ任意のタイミングで挿入）

data: {"createdAt":"...","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"content":"..."},"finishReason":"stop"}]}
                                     ↑ 最終チャンク（finishReason付き）

data: [DONE]                         ← ストリーム終了
```

### 各フェーズの詳細

| フェーズ           | 説明                                                                                                                                                                            |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| : `connected`  | SSE コメント行。接続が確立されたことを示します。                                                                                                                                                    |
| ロールチャンク        | 最初の data イベント。delta に `role: "assistant"` と `messageInfo`（conversationId, messageId）が含まれます。                                                                                   |
| コンテンツチャンク      | テキストコンテンツの差分。delta.content に追記テキストが含まれます。テキストの形式はリクエストの `outputFormat` で制御でき、省略時はプレーンテキスト（`"markdown"` 指定で Markdown 記法を保持）。エージェントのタスク実行情報（delta.tasks）が含まれることもあります。複数回配信されます。 |
| : `heartbeat`  | SSE コメント行。長時間アイドル時のコネクション維持用（プロキシのアイドルタイムアウト対策）。約15秒間隔で挿入されます。`data:` で始まらないため通常のクライアントは自動的に無視します。                                                                            |
| 最終チャンク         | finishReason が設定されたチャンク。status（実行状態）や deliverables（成果物）が含まれることがあります。                                                                                                          |
| data: `[DONE]` | ストリーム終了シグナル。この後 SSE 接続が閉じられます。                                                                                                                                                |

> **テキストはプレーンテキストに変換されます**
>
> リクエストで `outputFormat: "markdown"` を指定しない限り、配信されるテキストは Markdown 記法を落としたプレーンテキストに変換されます。対象は `delta.content` と、`delta.interaction.content` です。リンクは「文字 (URL)」（文字が URL と同じなら URL だけ）、画像は代替テキストだけになります。Markdown のまま受け取りたい場合は `outputFormat: "markdown"` を指定してください。

### レスポンスヘッダー

| ヘッダー                | 説明                               |
| ------------------- | -------------------------------- |
| `Content-Type`      | text/event-stream; charset=utf-8 |
| `X-Conversation-Id` | 会話ID。新規会話の場合はサーバーが生成したIDが返されます。  |
| `X-Message-Id`      | アシスタントの応答メッセージID。                |

## レスポンスオブジェクト

SSE の各 `data:` 行は以下のオブジェクト階層で構成されます。

```text
ChatCompletionChunk
  └─ choices[]
       └─ Choice
            ├─ delta          … Delta オブジェクト（差分データ）
            ├─ finishReason   … 完了理由
            ├─ status         … エージェント実行状態
            └─ deliverables   … 成果物ファイル
```

### ChatCompletionChunk

各 SSE イベントのトップレベルオブジェクトです。

| パラメータ       | 型        | 説明                       |
| ----------- | -------- | ------------------------ |
| `createdAt` | `string` | チャンクの生成日時（ISO 8601形式）    |
| `model`     | `string` | モデル名。`"AGENTIC STAR"`    |
| `choices`   | `array`  | Choiceオブジェクトの配列（要素数は常に1） |

### Choice

choices 配列の各要素です。AGENTIC STAR では常に 1 要素のみ含まれます。

| パラメータ          | 型                | 説明                                                           |
| -------------- | ---------------- | ------------------------------------------------------------ |
| `index`        | `number`         | 常に `0`                                                       |
| `delta`        | `object`         | 差分データ（下記 Delta オブジェクト）                                       |
| `finishReason` | `string \| null` | `"stop"`（正常完了）、`"error"`（エラー）、または `null`（ストリーミング中）           |
| `status`       | `object`         | `{ processing: boolean, unfinished: boolean }` — エージェントの実行状態 |
| `deliverables` | `array`          | エージェントが生成した成果物ファイルの配列                                        |
| `cancelled`    | `boolean`        | キャンセルが受理されたチャンクにのみ `true` で付きます。通常のチャンクにはフィールド自体が現れません       |

### Delta

各チャンクの差分データです。チャンクの種類によって含まれるフィールドが異なります。

| パラメータ         | 型        | 出現   | 説明                                                                                |
| ------------- | -------- | ---- | --------------------------------------------------------------------------------- |
| `role`        | `string` | 最初のみ | 最初のチャンクでのみ送信。`"assistant"` 固定。                                                    |
| `messageInfo` | `object` | 最初のみ | `{ conversationId, messageId }` — メッセージ識別情報                                       |
| `content`     | `string` | 複数回  | テキストコンテンツの差分                                                                      |
| `tasks`       | `array`  | 複数回  | エージェントのタスク実行情報（Task オブジェクトの配列）                                                    |
| `interaction` | `object` | 条件付き | ユーザー対話リクエスト（選択肢提示等）                                                               |
| `uiResource`  | `object` | 条件付き | 表示専用の UI リソース。届く場所の対応は [delta.uiResource](#delta-uiresource) を参照                  |
| `draft`       | `object` | 条件付き | チャットで作った下書き（Playbook・Skill・プロジェクト・Agent の直し・定期実行）。[delta.draft](#delta-draft) を参照 |

## エージェント拡張フィールド

AGENTIC STAR は OpenAI 互換フォーマットに、エージェント固有の拡張フィールドを追加しています。

| フィールド                 | レベル    | 説明             |
| --------------------- | ------ | -------------- |
| `delta.tasks`         | Delta  | エージェントのタスク実行情報 |
| `delta.uiResource`    | Delta  | 表示専用の UI リソース  |
| `delta.draft`         | Delta  | チャットで作った下書き    |
| `delta.interaction`   | Delta  | ユーザー対話リクエスト    |
| `choice.status`       | Choice | エージェントの実行状態    |
| `choice.deliverables` | Choice | 成果物ファイル一覧      |

### delta.tasks

エージェントのタスク実行情報。ツール実行・ファイル作成・検索などのアクション発生時に SSE チャンクの `delta.tasks` 配列として配信されます。タスク状態が更新されるたびに送信され、1 チャンクに含まれる Task は通常 1 件です。`delta.tasks` は `delta.content` と同一チャンクに共存します。

Task オブジェクトの詳細は「[Task データモデル](#task-data-model)」を参照してください。

以下は配信例です。`actionType` と `metadata` の値は、接続先エージェントの実装によって異なります。

<!-- -->

<!-- -->

```json
{
  "createdAt": "2026-03-14T15:00:53.059Z",
  "model": "AGENTIC STAR",
  "choices": [{
    "index": 0,
    "finishReason": null,
    "delta": {
      "content": "Processing local_assistant",
      "tasks": [{
        "messageId": "5b47837a-...",
        "conversationId": "09071b95-...",
        "callId": "0cf24f34-...",
        "actionType": "tool_start",
        "title": "local assistant",
        "description": "Processing local_assistant",
        "status": "in_progress",
        "metadata": { "tool_name": "local_assistant", "call_id": "0cf24f34-...", "status": "starting" },
        "timestamp": 1773499412706,
        "createdAt": "2026-03-14T14:43:32.708Z",
        "updatedAt": "2026-03-14T14:43:32.708Z"
      }]
    },
    "status": { "processing": true, "unfinished": true }
  }]
}
```

### delta.uiResource

エージェントが実行中に生成した UI リソースです。グラフ・地図・カード一覧など、テキストでは表現しきれない出力がある場合に送信されます。ユーザーの回答は求めません（回答を求める UI は [`delta.interaction`](#deltainteraction) で配信されます）。

UI リソースには、HTML を描画する `type: "html"` と、構造化データを渡す `type: "data"` の 2 種類があります。`type: "html"` の場合、`delta.uiResource` に含まれるのは**メタ情報だけで、HTML 本体は含まれません**。HTML は [UI リソース取得エンドポイント](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference.md#get-ui-resource)から文字列として取得し、**描画は利用者のアプリケーション側で行います**。描画時の注意は [描画時の注意](#rendering-notes) を参照してください。

> **どこに届くかは「生成元」と「種類」で決まります**
>
> | 生成元          | 種類                 | 届く場所                           | 利用者の対応                                                                        |
> | ------------ | ------------------ | ------------------------------ | ----------------------------------------------------------------------------- |
> | AGENTIC STAR | 表示用（グラフ・地図・カード一覧）  | `delta.uiResource`             | 描画するだけ。回答は不要                                                                  |
> | AGENTIC STAR | 入力用（選択肢カード・質問フォーム） | `delta.interaction.uiResource` | [delta.interaction](#deltainteraction) を参照                                    |
> | 外部 MCP サーバー  | 表示用・入力用を問わず        | `delta.uiResource`             | `interaction` には入りません。**HTML 自体に入力欄が含まれることがあります**（[描画時の注意](#rendering-notes)） |
>
> `delta.uiResource` と `delta.interaction.uiResource` は**同じ構造**ですが、**同じチャンクに両方が入ることはありません**。

> **UI を扱わない場合**
>
> UI リソースは補助的な出力です。代替テキストは `altText` に入り、**同じチャンクの `delta.content` と同一の文字列**です。描画しないクライアントは `delta.uiResource` を無視して `delta.content` を読むだけで済みます。

実行中に生成された UI がすべて配信されるとは限りません。**HTML を提供できない場合、`delta.uiResource` は付かず、代替テキストだけが `delta.content` に流れます。**

#### 共通フィールド

`type` は描画方法を、`origin` は信頼性を表します。`altText` は UI を描画しない場合に使うテキストです。

| パラメータ     | 型        | 説明                                                                                                              |
| --------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `type`    | `string` | `"html"`（HTML ドキュメント。本体は含まれず、取得エンドポイントで取得します）または `"data"`（構造化データ。`data` フィールドにインラインで含まれ、取得は不要です）。未知の値は無視してください  |
| `origin`  | `string` | `"first-party"`（AGENTIC STAR が生成したコンテンツ）または `"external"`（管理者が接続を許可した外部の MCP サーバーが生成したコンテンツ）。扱いの違いは下表を参照してください   |
| `altText` | `string` | 代替テキスト。**隣接する `delta.content` と同一文字列**です。応答テキストの組み立てや文字数の計算では、どちらか一方だけを使ってください。**内容は `origin` によって変わります**（下表参照） |

#### `origin` による違い

**同じ形のオブジェクトでも、`origin` によって値の出どころと扱いが変わります。** 取り扱いを決める前にこの表を確認してください。

| 観点                   | "first-party"                                               | "external"                                                           |
| -------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------- |
| 生成者                  | AGENTIC STAR                                                | 管理者が接続を許可した外部の MCP サーバー                                              |
| 内容の検査                | 自社が生成したコンテンツです                                              | **AGENTIC STAR は内容を検査していません**                                        |
| 表示ヒント（`meta`）        | AGENTIC STAR が設定した値です                                       | 提供元（外部 MCP サーバー）の申告値です                                               |
| 機能情報（`capabilities`） | AGENTIC STAR が設定しています                                       | 提供元の申告値です                                                            |
| 代替テキスト（`altText`）    | UI の内容を説明します                                                | 固定文言で、UI の内容を説明しません                                                  |
| 入力の扱い                | 入力を求める場合は `delta.interaction` で配信されます。UI から回答は送れず、テキストで送ります | 表示用と入力用を区別しません。**HTML に入力欄が含まれることがあり、入力内容は提供元が指定した宛先へ送信される可能性があります** |

形式（`ui://` で始まること・必須フィールドの有無・MIME タイプ・サイズ上限）は、どちらも検証されます。

`origin: "external"` の `altText` は固定文言 `An external MCP server returned a UI resource. Its content is not described here.` です。**このターンの応答テキスト（`delta.content`）自体もこの文言になり、実質的な回答は含まれません。** 利用者にはその旨を伝え、この文言を回答として提示しないでください。

#### `type: "html"` のフィールド

| パラメータ          | 型         | 説明                                                                                                             |
| -------------- | --------- | -------------------------------------------------------------------------------------------------------------- |
| `tool_call_id` | `string`  | UI リソースの識別子。**HTML の取得キー**として使います                                                                              |
| `uri`          | `string`  | UI リソースの識別子（`ui://` スキーム）。取得用の URL ではありません                                                                     |
| `tool_name`    | `string`  | UI を生成したツール名                                                                                                   |
| `server_name`  | `string`  | UI を提供したサーバー名。**信頼性の判定には使わず、`origin` を使ってください**                                                                |
| `mime_type`    | `string`  | 通常は `"text/html;profile=mcp-app"`                                                                              |
| `meta`         | `object?` | 表示ヒント（`preferredHeight` / `connectDomains` 等）。**値の出どころは `origin` で変わります**（[origin による違い](#ui-resource-origin)） |
| `capabilities` | `object?` | 機能情報（`visibility` / `interaction_mode` 等）。**値の出どころは `origin` で変わります**（同上）                                      |
| `size`         | `number?` | HTML のバイトサイズ。取得前に大きさを判断するために使えます。省略される場合があります                                                                  |

`size` は履歴・検索と A2A の待つ送信とタスクの取得（0.3 の `message/send` / `tasks/get`、1.0 の `SendMessage` / `GetTask` / `ListTasks`）では付きません。SSE・MCP と A2A のストリームでも**付かないことがあります**。

```json
"delta": {
  "content": "売上推移のグラフを作成しました。",
  "uiResource": {
    "type": "html",
    "origin": "first-party",
    "altText": "売上推移のグラフを作成しました。",
    "uri": "ui://widget/chart",
    "server_name": "agentic-star-widgets",
    "tool_name": "widget_chart",
    "tool_call_id": "chart-7f3a2b1c9e4d5a6b7c8d9e0f1a2b3c4d",
    "mime_type": "text/html;profile=mcp-app",
    "size": 8421
  }
}
```

#### `type: "data"` のフィールド

| パラメータ          | 型         | 説明                                                        |
| -------------- | --------- | --------------------------------------------------------- |
| `origin`       | `string`  | `type: "data"` では常に `"first-party"` です                    |
| `kind`         | `string`  | データの種類（例: `"map"`）。**未知の `kind` は無視し、`altText` を使ってください** |
| `data`         | `object`  | `kind` ごとのペイロード。インラインで含まれます                               |
| `generated_at` | `string?` | 生成日時                                                      |

```json
"delta": {
  "content": "近くのカフェを3件見つけました。",
  "uiResource": {
    "type": "data",
    "origin": "first-party",
    "altText": "近くのカフェを3件見つけました。",
    "kind": "map",
    "data": {
      "places": [
        { "place_id": "ChIJ...", "name": "カフェ A", "distance_text": "徒歩5分" }
      ],
      "center_place_id": "ChIJ..."
    }
  }
}
```

`kind: "map"` の `places[]` には `place_id` と表示用テキスト（名称・補足・価格帯・距離・評価）が含まれます。**座標や住所は含まれません。** 地図として描画するには利用者側の Google Maps 連携が必要です。連携がない場合も `https://www.google.com/maps/place/?q=place_id:<place_id>` へのリンクは生成できます。`place_id` を外部サービスへ送信するかどうかは利用者の判断です。

`data` 直下には `places[]` のほか、地図の中心に使う `center_place_id` と、見出し用の `title` が入ります。いずれも省略される場合があります。

#### 描画時の注意

> **注意**
>
> **`origin` を問わず**: 取得した HTML は、隔離した iframe 等でサンドボックス化して描画することを推奨します。`sandbox` 属性を付けない、または `allow-same-origin` を許可した iframe で描画すると、HTML 内のスクリプトが自サイトのオリジンの権限で実行されます。AGENTIC STAR が生成する UI にもスクリプトは含まれます。
>
> **`origin: "external"` の場合**は加えて、コンテンツを **AGENTIC STAR が検査していません**（検証しているのは形式のみです）。**HTML に入力欄が含まれることがあり**、入力内容は提供元が指定した宛先へ送信される可能性があります。送信先での扱いは AGENTIC STAR の管理外です。**`meta.connectDomains` は提供元の申告値であり、AGENTIC STAR が許可した通信先ではありません。**

### delta.draft

チャットで Playbook・Skill・プロジェクト・Agent の直し・定期実行の下書きを頼むと、下書きのカードの UI（`delta.uiResource`）と同じチャンクに `delta.draft` が付きます。`draft` は、作る・変えるのに要る値を持つ下書きのデータです（送り方は種類ごとに下の表のとおり。定期実行は外部 API では作れません）。**この時点では何も作られません。**

応答テキスト（`delta.content`）は、画面で保存するよう利用者に案内します。この会話は利用者の画面のチャットにも出て、カードから保存できます。**アプリが `draft` から作るときは、先に利用者に確かめ、画面での保存と重ねないでください**（両方で保存すると 2 つできます）。カードが出ても `draft` が付かないことがあります。そのときは画面で保存するよう案内してください。

#### 共通フィールド

| フィールド        | 型        | 説明                                                                                                                                                                         |
| ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kind`       | `string` | "playbook"・"skill"・"project"・"agentUpdate"・"schedule" のいずれか。未知の値は無視してください                                                                                                  |
| `toolCallId` | `string` | 対応する UI 部品の tool\_call\_id と同じ値（SSE は同じチャンクの delta.uiResource、履歴・検索は同じタスクの metadata.uiResource、MCP は uiResources\[] のうち同じ tool\_call\_id の物、A2A は同じ ui-resource- artifact） |

#### 種類ごとの中身と作り方

| kind          | 中身                                                                                                                                                   | 作り方                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `playbook`    | `playbook`（`name`・`description`・`category`・`tags`・`steps[]`〈`title`・`description`・`guidance`・`success`〉）、`updateOf`（直す Playbook の名前。新しく作るときは `null`） | `updateOf` が `null` なら、`playbook` を [Playbook の作成](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference.md#create-playbook) に送ります。名前があれば、`GET /v1/playbooks?active_only=false` を全部のページ読んで、前後の空白を除いた名前が `updateOf`（同じく前後の空白を除く）と一致する Playbook を探し、ちょうど 1 つのときだけ、その Playbook を [Playbook の取得](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference.md#get-playbook)（`GET /v1/playbooks/{playbookId}`。一覧には `digest` がありません）で読み、その `digest` を `baseDigest` にして [Playbook の変更](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference.md#update-playbook) に送ります。0 件・2 件以上のときは変えずに、利用者に確かめてください                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `skill`       | `skillMd`（SKILL.md の全文）、`name`・`description`（SKILL.md の frontmatter と同じ値）、`updateOf`                                                                 | `updateOf` が `null` なら、`skillMd` を `SKILL.md` として [Skill の作成](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference.md#create-skill) の `files` に送ります。名前があれば、`GET /v1/skills?active_only=false` を全部のページ読んで、前後の空白を除いた名前が `updateOf`（同じく前後の空白を除く）と完全に一致する Skill を探し、ちょうど 1 つのときだけ、ファイルの一覧の取得の `digest` を `baseDigest` にして [Skill のファイルの置き換え](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference.md#replace-skill-files) に送ります。0 件・2 件以上のときは変えずに、新しく作るか、利用者に確かめてください                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `project`     | `definition`（プロジェクトの定義。取り込みの形）                                                                                                                       | `{ "definition": … }` を [プロジェクトの取り込み](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference-projects.md#import-project) に送ります。取り込みと同じく一時停止で作られます                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `agentUpdate` | `agentName`、`projectName`（無いときは `null`）、`spec`（`goal`・`guardrail`。変えない項目は鍵がありません）                                                                    | [Agent の一覧](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference.md#list-agents)（自分の Agent だけを返します。`q` に前後の空白を除いた `agentName`。それが 100 文字を超えるときは `q` を付けない）を全部のページ読み、前後の空白を除いた名前が、前後の空白を除いた `agentName` と完全に一致する Agent を集めます。`projectName` があれば（前後の空白を除いて空なら、無いのと同じ）先に、[プロジェクトの一覧](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference-projects.md#list-projects)（参加しているプロジェクト。全部のページ）で前後の空白を除いた名前が、前後の空白を除いた `projectName` と一致するプロジェクトを探し、その [配置の一覧](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference-projects.md#list-placements) の `agentId` に絞ります（一致するプロジェクトが 2 つ以上なら、その全部の配置を合わせます）。**ちょうど 1 つのときだけ**、その Agent を [Agent の取得](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference.md#get-agent)（`GET /v1/agents/{agentId}`。一覧には `digest` がありません）で読み、その `digest` を `baseDigest` にして `{ spec, baseDigest }` を [Agent の変更](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference.md#update-agent) に送ります。0 件なら変えずに利用者に伝え、2 件以上なら利用者に選んでもらってください。Agent の変更は、その Agent を置いたすべてのプロジェクトに効きます |
| `schedule`    | `name`・`goal`・`cron`（5 つの欄の cron 式。利用者の地域の時刻で、時刻帯は含みません）                                                                                             | 外部 API で作る口はありません。利用者が画面の定期実行で、下書きから作ります                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

Playbook の下書きの例（`delta`）:

```json
"delta": {
  "content": "週次の売上の確認の Playbook の下書きを作りました。",
  "uiResource": {
    "type": "html",
    "origin": "first-party",
    "altText": "週次の売上の確認の Playbook の下書きを作りました。",
    "uri": "ui://widget/playbook_draft",
    "server_name": "agentic-star-widgets",
    "tool_name": "propose_playbook",
    "tool_call_id": "playbook_draft-0123456789abcdef",
    "mime_type": "text/html;profile=mcp-app"
  },
  "draft": {
    "kind": "playbook",
    "toolCallId": "playbook_draft-0123456789abcdef",
    "playbook": {
      "name": "週次の売上の確認",
      "description": "毎週月曜に先週の売上をまとめて報告する",
      "category": "運用",
      "tags": [
        "売上",
        "週次"
      ],
      "steps": [
        {
          "title": "集める",
          "description": "先週の売上の表を読む",
          "guidance": [
            "前の週と比べる"
          ],
          "success": "店舗ごとの合計がそろっている"
        }
      ]
    },
    "updateOf": null
  }
}
```

### delta.interaction

エージェントがユーザーに対話を要求する場合に送信されます。選択肢の提示（choice）、確認ダイアログ（confirmation）、設問への回答要求（question）の3種類があります。

| パラメータ             | 型          | 必須 | 説明                                                                                                                                                                                                                                  |
| ----------------- | ---------- | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `interactionType` | `string`   | ✓  | `"choice"` \| `"confirmation"` \| `"question"`                                                                                                                                                                                      |
| `interactionId`   | `string`   |    | Agent の質問の ID。答えるときに、次のリクエストの interactionReply で送ります。付かない場合があります（画面の部品で尋ねる質問など）                                                                                                                                                     |
| `content`         | `string`   |    | 対話メッセージの本文                                                                                                                                                                                                                          |
| `options`         | `string[]` |    | 選択肢の配列。`choice` では提示する選択肢、`confirmation` では承認・拒否のラベル（通常は2要素）。**要素数は決め打ちせず、渡された配列をそのまま提示してください。** 省略される場合があります。                                                                                                                      |
| `uiResource`      | `object`   |    | この対話の UI リソース（選択肢カード、または質問フォーム。[delta.uiResource](#delta-uiresource) と同じ構造）。**`content` のテキストでは表せないもの（説明文・画像・フォームの体裁）を含み、利用側が UI を組み立てる材料になります。**`options` とは排他です。この UI から回答は送れないため、`content` を読んで次の `chat/completions` にテキストで送ります。 |

| 型              | 説明                    | 含まれるフィールド                                                                                  |
| -------------- | --------------------- | ------------------------------------------------------------------------------------------ |
| `choice`       | 選択肢を提示し、ユーザーに1つを選択させる | `content`。加えて `options` または `uiResource`（どちらも付かない場合があります）                                  |
| `confirmation` | ユーザーに確認（承認/拒否）を求める    | `content`。`options` は付く場合があります                                                             |
| `question`     | 1つ以上の設問への回答を求める       | `content`（設問と選択肢を含む平文）。加えて `uiResource`（フォームの UI。付かない場合があります）。選択肢のある設問でも `options` には載りません |

> **回答は次のリクエストで送ります**
>
> **`interaction` の `uiResource` は、設問を利用者に提示するための材料です。** 選択肢の並び・説明文・レイアウトなど、`content` の平文では表せない情報が入っています。そのまま描画しても、内容を読み取って自前の入力 UI を組み立てても構いません。**ただしこの UI 自体に回答を送る経路はありません**（`capabilities.interaction_mode` は `"closed"` になります）。なお**履歴・検索 API で過去の会話を読む場合は `"block"` が入ることがあります**。API 経由で開始していない会話が含まれるためで、判別には `capabilities.interaction_mode` を使ってください。
>
> 回答は、**次の `POST /v1/chat/completions` に同じ `conversationId` を指定してテキストで送信**します。SSE ストリーム内で回答を返す経路はありません。`interactionId` が付いた質問に答えるときは、`interactionReply: { interactionId, optionIndex? }` を付けて送ります（選択肢から選んだ答えなら、`optionIndex` に選んだ選択肢の番号。最初が 0）。付けると、その質問への答えとして記録され、月の利用の枠の上限に達していても答えられます。`interactionReply` を付けないときは、`agentMode: false` を付けないでください（付けると、質問をした Agent に回答が届きません）。
>
> `content` は対話メッセージの本文です。選択肢は `content` のテキストに含まれる場合と、`options` に入る場合があります。**UI を描画しない場合は `content` を提示し、`options` があれば選択肢として併せて示したうえで、利用者の回答をテキストで送ってください。**
>
> なお `interaction` に付く `uiResource` は **`origin: "first-party"` に限られます**（`origin: "external"` の UI は `delta.uiResource` で配信され、`interaction` には入りません）。

choice の例:

```json
"interaction": {
  "interactionType": "choice",
  "content": "どの形式で出力しますか？",
  "options": ["PDF形式", "Markdown形式", "HTML形式"]
}
```

confirmation の例:

```json
"interaction": {
  "interactionType": "confirmation",
  "content": "このファイルを削除します。『削除する』で実行、『キャンセル』で中止します。",
  "options": ["削除する", "キャンセル"]
}
```

question の例:

```json
"interaction": {
  "interactionType": "question",
  "content": "好みについての3つの質問\n以下の質問に回答を返信してください:\n1. 休日に一番楽しみたいことは何ですか？\n   「家でゆっくり過ごす」「外出して新しい場所を巡る」「趣味や学びに集中する」",
  "uiResource": {
    "type": "html",
    "origin": "first-party",
    "altText": "好みについての3つの質問\n以下の質問に回答を返信してください:\n1. 休日に一番楽しみたいことは何ですか？\n   「家でゆっくり過ごす」「外出して新しい場所を巡る」「趣味や学びに集中する」",
    "uri": "ui://widget/form",
    "server_name": "agentic-star-widgets",
    "tool_name": "widget_form",
    "tool_call_id": "form-45435d5ede3b43ec9a4a82e280db1e98",
    "mime_type": "text/html;profile=mcp-app",
    "size": 3562
  }
}
```

### choice.status

最終チャンクの Choice レベルに含まれるフィールドです。エージェントの実行状態を示します。

| パラメータ        | 型         | 説明                                                                                |
| ------------ | --------- | --------------------------------------------------------------------------------- |
| `processing` | `boolean` | エージェントがバックグラウンドで処理を継続中かどうか。通常は `unfinished` と同じ値で遷移する。`true` の場合、再接続で後続イベントを受信可能。 |
| `unfinished` | `boolean` | タスクが未完了かどうか。通常は `processing` と同じ値で遷移する。両方 `false` で正常完了、両方 `true` で処理継続中を示す。      |

```json
"status": { "processing": false, "unfinished": false }
```

### choice.deliverables

最終チャンクの Choice レベルに含まれるフィールドです。エージェントが生成した成果物ファイルの一覧です。

| パラメータ       | 型         | 説明                                                                                                      |
| ----------- | --------- | ------------------------------------------------------------------------------------------------------- |
| `filename`  | `string`  | ファイル名                                                                                                   |
| `filepath`  | `string`  | ファイルパス（ダウンロード用の相対パス）                                                                                    |
| `source`    | `string`  | `"agent"`（エージェント生成）または `"user"`（ユーザーアップロード）。                                                            |
| `isPrimary` | `boolean` | 主要成果物かどうか                                                                                               |
| `createdAt` | `string`  | 作成日時（ISO 8601形式）。分からないときは空文字                                                                            |
| `mimeType`  | `string`  | MIME タイプ（例: `"application/pdf"`、`"image/png"`、`"text/markdown"`）。判定できない場合は `"application/octet-stream"` |
| `size`      | `number?` | ファイルサイズ（バイト）。0 以下の場合は省略                                                                                 |

```json
"deliverables": [{
  "filename": "report.pdf",
  "filepath": "/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.pdf",
  "source": "agent",
  "isPrimary": true,
  "createdAt": "2026-03-14T10:30:05.000Z",
  "mimeType": "application/pdf",
  "size": 4201846
}]
```

## Task データモデル

`delta.tasks` 配列には、エージェントが実行したアクションを表す **Task オブジェクト** が並びます。Task は「全ての Task に共通するフィールド」と「`actionType` によって構造が切り替わる可変部」で構成されます。

> **どこまでが基盤の仕様で、どこからがエージェント実装か**
>
> SSE の接続ライフサイクル、`ChatCompletionChunk` / `Choice` / `Delta` の構造、`choice.status`、`choice.deliverables`、そして下記「共通フィールド」に挙げる Task のフィールド名と既定値までが、基盤が保証する範囲です。
>
> 一方、`actionType` の値、`metadata` のキーと構造、`title` / `description` / `content` の文言は、**応答を生成するエージェントの実装が決めます**。基盤はこれらを検証も変換もせず、そのまま配信します。

### 共通フィールド

全ての Task に共通して現れるフィールドです。

| フィールド            | 型                | 説明                                                                                                                                                                                                                                                        |
| ---------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `messageId`      | `string`         | Task が属するメッセージの ID                                                                                                                                                                                                                                        |
| `conversationId` | `string`         | Task が属する会話の ID                                                                                                                                                                                                                                           |
| `actionType`     | `string`         | 可変部の構造を決める discriminator（[actionType の詳細](#action-type)）                                                                                                                                                                                                  |
| `status`         | `string`         | Task の状態。値は `in_progress` / `completed` / `failed` / `error` / `pending` のいずれか（Task 全体のライフサイクル。`error` は主に `command_execution` 失敗時に出現。`pending` はサンドボックス準備通知などのインフラ通知や、履歴 API で初期状態が残存している場合に観測されます）。ツール固有の詳細ステータスは `metadata.status` に格納され、本フィールドとは別の値です |
| `callId`         | `string \| null` | `tool_start` と `tool_result` のみ値を持ち、他の actionType では `null`。同じ値で start と result のペアが紐付きます                                                                                                                                                                 |
| `title`          | `string`         | タスク種別や対象の短い見出し（表示用）                                                                                                                                                                                                                                       |
| `description`    | `string`         | 実行中メッセージや補足説明（表示用）                                                                                                                                                                                                                                        |
| `content`        | `string`         | タスクの出力本文（表示用、長文になり得る）                                                                                                                                                                                                                                     |
| `metadata`       | `object`         | `actionType` によって構造が変わる（[actionType の詳細](#action-type)参照）                                                                                                                                                                                                 |
| `files`          | `TaskFile[]`     | 関連ファイル。主に `file_operation` で使用（TaskFile の構造は [こちら](#taskfile)）                                                                                                                                                                                            |
| `timestamp`      | `number`         | Task のタイムスタンプ（Unix ミリ秒）                                                                                                                                                                                                                                   |
| `createdAt`      | `string`         | 作成日時（ISO 8601）                                                                                                                                                                                                                                            |
| `updatedAt`      | `string`         | 更新日時（ISO 8601）                                                                                                                                                                                                                                            |

> **表示用テキストをプログラム分岐に使わない**
>
> `title` / `description` / `content` は人間可読なテキストです。**プログラム側の分岐条件には使用しない**でください。分岐には `actionType` / `status` / `metadata.sub_event_type` を使います。
>
> | フィールド         | 典型的な用途                      |
> | ------------- | --------------------------- |
> | `title`       | タスク種別・対象の短い見出し（例: ツール名や対象名） |
> | `description` | 実行中メッセージや補足説明               |
> | `content`     | ツール出力の本文                    |

> **未知のフィールドは安全に無視**
>
> 実装は将来 `actionType` / `metadata` / 共通フィールドに新規キーを追加する可能性があります。クライアント実装では、本ドキュメントに記載されていないフィールドは安全に無視するようにしてください。

#### TaskFile 構造

`files: TaskFile[]` の各要素の構造です。

| フィールド      | 型         | 説明                                                                                         |
| ---------- | --------- | ------------------------------------------------------------------------------------------ |
| `filename` | `string`  | ファイル名                                                                                      |
| `size`     | `number`  | ファイルサイズ（バイト）                                                                               |
| `filepath` | `string`  | ダウンロード URL または作業ディレクトリ内のファイルパス                                                             |
| `mimeType` | `string?` | MIME タイプ（例: `"application/pdf"`、`"image/png"`、`"text/markdown"`）。filename から判定できない場合は省略される |

### 全体像

```text
Task = [ 共通フィールド ] + [ actionType で切り替わる可変部 ]

actionType (6 種) ─┬─ ツールライフサイクル系  tool_start, tool_result *
                   ├─ 特殊な結果系           search_result, command_execution, mcp_tool
                   └─ ファイル通知系         file_operation

  * tool_result のみ、metadata.sub_event_type (9 種) で 2 層目の分岐あり
```

代表例として、Bash コマンドの完了通知 (`tool_result` / `sub_event_type: bash_executed`) の Task は次のとおりです。

```json
{
  "messageId": "5b47837a-...",
  "conversationId": "09071b95-...",
  "actionType": "tool_result",
  "callId": "0cf24f34-bbd9-4833-88c4-d7f520ce3aae",
  "status": "completed",
  "title": "success",
  "description": "{'result': 'ok'}",
  "metadata": {
    "tool_name": "bash",
    "call_id": "0cf24f34-bbd9-4833-88c4-d7f520ce3aae",
    "sub_event_type": "bash_executed",
    "command": "python3 script.py",
    "exit_code": 0,
    "stdout": "{'result': 'ok'}\n",
    "status": "success",
    "duration_ms": 24
  },
  "files": [],
  "timestamp": 1773499362744,
  "createdAt": "2026-03-14T14:42:42.747Z",
  "updatedAt": "2026-03-14T14:42:42.747Z"
}
```

以降は「actionType 分岐マップ → グループごとの詳細 → ストリーム例」の順で説明します。

> **サンドボックス準備通知について**
>
> 会話開始時に、`actionType: "tool_start"` → `"tool_result"` のペア（`tool_name: "agent_executor"`, `title: "Sandbox"`）が配信されます。これは AI エージェントが実行するツールではなく、**実行環境（サンドボックス）の準備開始・完了を伝えるインフラ通知**です。`metadata` には `tool_name` と `call_id` のみが含まれます。
>
> 表示する場合は `title` / `description` をそのまま使えます。特別な処理が不要な場合は `tool_name === "agent_executor"` で除外しても構いません。

### actionType 分岐マップ

`actionType` は Task の可変部がどう変化するかを決める discriminator です。6 値が 3 グループに分類されます。

- **ツールライフサイクル系**: エージェントが使用したツールの開始 / 完了を通知
- **特殊な結果系**: Web 検索・シェルコマンド・MCP ツールなど、独自の metadata 構造を持つ
- **ファイル通知系**: エージェントが生成したファイルの通知

| actionType          | グループ        | callId | 説明             |
| ------------------- | ----------- | ------ | -------------- |
| `tool_start`        | ツールライフサイクル系 | ✓      | ツール実行の開始通知     |
| `tool_result`       | ツールライフサイクル系 | ✓      | ツール実行の完了結果     |
| `search_result`     | 特殊な結果系      | —      | Web 検索の完了結果    |
| `command_execution` | 特殊な結果系      | —      | シェルコマンド実行の完了結果 |
| `mcp_tool`          | 特殊な結果系      | —      | MCP ツール実行の結果   |
| `file_operation`    | ファイル通知系     | —      | ファイル作成の完了通知    |

**callId によるペアリング**: `tool_start` と `tool_result` は同じ `callId` / `metadata.call_id` で紐付きます。他の actionType では `callId` は `null` です。実際のペアリング例は [§ SSE ストリーム例](#stream-example) を参照してください。

---

次からはグループごとに `metadata` の構造と挙動を説明します。

### グループ① ツールライフサイクル系

エージェントが使用したツールの開始 (`tool_start`) と完了 (`tool_result`) を通知します。

#### tool\_start

ツール実行の開始通知。`callId` で対応する `tool_result` と紐付きます。

> **発生条件**
>
> `tool_start` は、`tool_name` が `generate_video` または `local_assistant` の場合**のみ**発火します。それ以外のツールでは完了時の `tool_result` のみが配信されます。
>
> - ツール完了の検知には `tool_result` を使用してください
> - `tool_start` は上記 2 ツール限定の補助的な通知として扱ってください
> - 将来的に対応ツールが追加される可能性があるため、未知の `tool_name` は安全に無視する実装を推奨します

**metadata 共通フィールド**

| フィールド       | 型        | 説明                                         |
| ----------- | -------- | ------------------------------------------ |
| `tool_name` | `string` | `"generate_video"` または `"local_assistant"` |
| `call_id`   | `string` | ツール呼び出し ID（`callId` と同じ値）                  |
| `status`    | `string` | `"starting"` 固定                            |

#### tool\_result

ツール実行の完了結果。`metadata.sub_event_type` でツール種別を細分化します。

**metadata 共通フィールド**

| フィールド            | 型        | 説明                                                                                                                                                                                                          |
| ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tool_name`      | `string` | ツール名                                                                                                                                                                                                        |
| `call_id`        | `string` | ツール呼び出し ID                                                                                                                                                                                                  |
| `sub_event_type` | `string` | ツール種別（[下記 9 種](#sub-event-type)）                                                                                                                                                                            |
| `status`         | `string` | ツール固有の実行結果ステータス。**[Task.status](#common-fields)（Task 全体のライフサイクル）とは別フィールド**で、`metadata` 内に入るツール独自の値（例: `"success"`, `"created"`, `"read"`, `"edited"`, `"searched"`, `"fetched"`, `"completed"` — ツールにより異なる） |

> **未知の sub\_event\_type / 追加フィールドは無視する**
>
> 外部 SSE ストリームで観測される `sub_event_type` は現時点で 9 種類です。将来追加される可能性があるため、**未知の `sub_event_type` は安全に無視** し、必要なフィールドのみを参照する実装を推奨します。
>
> 各 `sub_event_type` の `metadata` には、実行コンテキストに応じた**追加フィールドが含まれる場合があります**（例: サブエージェント実行時の `agent`、スライド生成時の `slide_event`、SDD 開発時の `sdd_event` 等）。また同じ `sub_event_type` でも経路により `tool_name` の値が異なることがあります（例: `file_read` で `"read"` / `"file_read"`）。未知のフィールドも同様に安全に無視する実装を推奨します。
>
> **`sub_event_type` 欄を持たない `tool_result` もあります**。`tool_name: "batch"` などの汎用バッチ処理や、ツール呼び出し直後のごく短い中間通知では `metadata.sub_event_type` 自体が省略されることがあります。`sub_event_type` が無い / 未知の場合は `tool_name` や `title` / `description` を表示用途に利用し、プログラム分岐では該当 Task をスキップすることを推奨します。

##### sub\_event\_type 一覧

SaaS / マーケットプレイス共通で、以下の 9 種が外部 SSE ストリームに送信されます。一覧に無い値が届いたときは、未知の値として安全に無視する実装を推奨します。

| sub\_event\_type  | 説明                                                                                  | 主な metadata フィールド                                                                      |
| ----------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `local_assistant` | ローカルアシスタント実行完了                                                                      | `message`, `result`, `files_created`, `files_modified`, `execution_time`, `turns_used` |
| `bash_executed`   | Bash コマンド実行                                                                         | `command`, `exit_code`, `stdout`, `stderr`, `duration_ms`, `working_dir`               |
| `file_edited`     | ファイル編集 (write / edit / multiedit / apply\_patch / notebook\_edit / render\_diagram) | `file_path`, `lines_written`, `replacements_made`, `diff`, `total_edits`               |
| `file_read`       | ファイル読み取り                                                                            | `file_path`, `lines_read`, `total_lines`, `is_binary`, `truncated`                     |
| `file_searched`   | ファイル検索 (grep / glob / ls)                                                           | `pattern`, `path`, `matches`, `files`, `file_count`, `tree`                            |
| `web_fetched`     | Web コンテンツ取得 / ファイル転送                                                                | `url`, `content_type`, `status_code`, `from_cache`, `duration_ms`                      |
| `task_launched`   | サブタスク起動                                                                             | `agent_type`, `task_description`, `success`, `duration_ms`                             |
| `video_generated` | 動画生成完了                                                                              | `job_id`, `preview_urls`, `final_url`, `used_prompt`, `model`                          |
| `image_generated` | 画像生成完了                                                                              | `image_url`, `original_prompt`, `revised_prompt`, `model`                              |

> **検索・コマンド・MCP・ファイル作成は別 actionType**
>
> - Web 検索 / シェルコマンド / MCP ツールは、**`tool_result` ではなく独立した `actionType`**（`search_result` / `command_execution` / `mcp_tool`）として配信されます
> - ファイル作成通知は `actionType: "file_operation"` として配信されます
> - 上記 4 つは `metadata.sub_event_type` には現れません

##### sub\_event\_type ごとの詳細

9 種を同じテンプレート（**metadata フィールド** + **JSON 例**）で列挙します。それぞれ `<details>` で折りたたんでいますので、必要なものをクリックで展開してください。

`bash_executed` — Bash コマンド実行

| フィールド         | 型        | 説明                                                             |
| ------------- | -------- | -------------------------------------------------------------- |
| `tool_name`   | `string` | `"bash"`                                                       |
| `command`     | `string` | 実行されたコマンド                                                      |
| `exit_code`   | `number` | 終了コード                                                          |
| `stdout`      | `string` | 標準出力                                                           |
| `stderr`      | `string` | 標準エラー出力                                                        |
| `status`      | `string` | `"success"`（exit\_code=0）または `"error"`                         |
| `duration_ms` | `number` | 実行時間（ミリ秒）                                                      |
| `working_dir` | `string` | 実行ディレクトリ                                                       |
| `title`       | `string` | ツール用の短縮ラベル（`"Execute: "` + コマンド先頭 30 字）。Task レベルの `title` とは別物 |

```json
"metadata": {
  "tool_name": "bash",
  "call_id": "call_0jqMfLE5lIuoJHglhuItZ4cZ",
  "command": "mkdir -p /home/ubuntu/scratchpad",
  "exit_code": 0,
  "stdout": "",
  "stderr": "",
  "status": "success",
  "duration_ms": 2,
  "working_dir": "/opt/.autonomous_agent/.sandbox-runtime",
  "title": "Execute: mkdir -p /home/ubuntu/scratchp...",
  "sub_event_type": "bash_executed"
}
```

`local_assistant` — ローカルアシスタント実行完了

| フィールド            | 型                | 説明                           |
| ---------------- | ---------------- | ---------------------------- |
| `tool_name`      | `string`         | `"local_assistant"`          |
| `message`        | `string`         | 実行されたタスク説明                   |
| `success`        | `boolean`        | 成功フラグ                        |
| `result`         | `string`         | 実行結果テキスト                     |
| `files_created`  | `string[]`       | 作成されたファイルのパス配列               |
| `files_modified` | `string[]`       | 変更されたファイルのパス配列               |
| `error`          | `string \| null` | エラー内容（失敗時のみ）                 |
| `execution_time` | `number`         | 実行時間（秒）                      |
| `turns_used`     | `number`         | 内部ターン数                       |
| `status`         | `string`         | `"completed"` または `"failed"` |

```json
"metadata": {
  "tool_name": "local_assistant",
  "call_id": "call_01HXYZ",
  "sub_event_type": "local_assistant",
  "message": "Python スクリプトの作成とテスト",
  "success": true,
  "result": "指定された Python スクリプトを作成し、ユニットテストも追加しました。",
  "files_created": [
    "/workspace/exec-12345/src/data_processor.py",
    "/workspace/exec-12345/tests/test_data_processor.py"
  ],
  "files_modified": [
    "/workspace/exec-12345/requirements.txt"
  ],
  "error": null,
  "execution_time": 23.5,
  "turns_used": 8,
  "status": "completed"
}
```

> **進捗通知の最小形**
>
> `claude-code-mcp` 経由のツール呼び出しでは、完了結果とは別に **進捗通知の最小形** が配信される場合があります。この場合の `metadata` には `tool_name` と `call_id` のみが含まれ、上記の `message` / `result` / `status` 等は**含まれません**。進捗通知として扱うか、`status` 未設定を理由にスキップする実装を推奨します。

`file_edited` — ファイル編集 (write / edit / multiedit / apply\_patch / notebook\_edit / render\_diagram)

`file_edited` は複数のツール経由で発行されます。`tool_name` で分岐してください。

**共通フィールド**

| フィールド       | 型        | 説明                                                                                                                              |
| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `tool_name` | `string` | 編集ツール名。実行経路により異なる（例: `"write"`, `"edit"`, `"multiedit"`, `"file_edit"`, `"apply_patch"`, `"notebook_edit"`, `"render_diagram"`） |
| `file_path` | `string` | 対象ファイルパス（複数ファイル編集時は代表ファイル）                                                                                                      |
| `status`    | `string` | `"created"` \| `"updated"` \| `"edited"` \| `"multi_edited"` \| `"error"`                                                       |

**write 固有（`tool_name: "write"`）**

| フィールド               | 型                | 説明                                                         |
| ------------------- | ---------------- | ---------------------------------------------------------- |
| `lines_written`     | `number`         | 書き込み行数                                                     |
| `file_size`         | `number`         | ファイルサイズ（バイト）                                               |
| `line_start`        | `number \| null` | 書き込み開始行                                                    |
| `line_end`          | `number \| null` | 書き込み終了行                                                    |
| `content_truncated` | `boolean`        | コンテンツが大きすぎて `message` に含まれなかった場合のみ `true`（省略時は `false` 相当） |

```json
"metadata": {
  "tool_name": "write",
  "call_id": "call_01HXYZ",
  "sub_event_type": "file_edited",
  "file_path": "/workspace/exec-12345/src/new_module.py",
  "lines_written": 45,
  "file_size": 1234,
  "line_start": 1,
  "line_end": 45,
  "status": "created"
}
```

**edit 固有（`tool_name: "edit"`）**

| フィールド               | 型         | 説明                                                 |
| ------------------- | --------- | -------------------------------------------------- |
| `replacements_made` | `number`  | 置換回数                                               |
| `strategy_used`     | `string`  | 適用された置換戦略（例: `"exact"`, `"whitespace_normalized"`） |
| `diff`              | `string`  | 差分テキスト                                             |
| `lines_count`       | `number`  | 編集後のファイル行数                                         |
| `content_truncated` | `boolean` | コンテンツが大きすぎて `message` に含まれなかった場合のみ `true`          |

```json
"metadata": {
  "tool_name": "edit",
  "call_id": "call_01HXYZ",
  "sub_event_type": "file_edited",
  "file_path": "/workspace/exec-12345/src/main.py",
  "replacements_made": 3,
  "strategy_used": "exact_match",
  "diff": "- old_function()\n+ new_function()",
  "lines_count": 150,
  "status": "edited"
}
```

**multiedit 固有（`tool_name: "multiedit"`）**

| フィールド               | 型         | 説明                                        |
| ------------------- | --------- | ----------------------------------------- |
| `total_edits`       | `number`  | 総編集回数                                     |
| `successful_edits`  | `number`  | 成功した編集数                                   |
| `failed_edits`      | `number`  | 失敗した編集数                                   |
| `diff`              | `string`  | 差分テキスト                                    |
| `lines_count`       | `number`  | 編集後のファイル行数                                |
| `content_truncated` | `boolean` | コンテンツが大きすぎて `message` に含まれなかった場合のみ `true` |

```json
"metadata": {
  "tool_name": "multiedit",
  "call_id": "call_01HXYZ",
  "sub_event_type": "file_edited",
  "file_path": "/workspace/exec-12345/src/config.py",
  "total_edits": 5,
  "successful_edits": 4,
  "failed_edits": 1,
  "diff": "- DEBUG = False\n+ DEBUG = True",
  "lines_count": 120,
  "status": "multi_edited"
}
```

**apply\_patch 固有（`tool_name: "apply_patch"`）**

| フィールド            | 型          | 説明                          |
| ---------------- | ---------- | --------------------------- |
| `added_files`    | `string[]` | 追加されたファイルパス配列               |
| `modified_files` | `string[]` | 変更されたファイルパス配列               |
| `deleted_files`  | `string[]` | 削除されたファイルパス配列               |
| `moved_files`    | `object[]` | 移動されたファイル（`{from, to}` の配列） |
| `total_files`    | `number`   | 影響を受けたファイルの総数               |
| `success`        | `boolean`  | パッチ適用が成功したか                 |
| `errors`         | `string[]` | エラーメッセージ配列（失敗時）             |

```json
"metadata": {
  "tool_name": "apply_patch",
  "call_id": "call_01HXYZ",
  "sub_event_type": "file_edited",
  "file_path": "/workspace/exec-12345/src/main.py",
  "added_files": ["/workspace/exec-12345/src/new_feature.py"],
  "modified_files": ["/workspace/exec-12345/src/main.py"],
  "deleted_files": [],
  "moved_files": [],
  "total_files": 2,
  "success": true,
  "errors": [],
  "status": "edited"
}
```

**notebook\_edit 固有（`tool_name: "notebook_edit"`）**

| フィールド         | 型        | 説明                                                 |
| ------------- | -------- | -------------------------------------------------- |
| `operation`   | `string` | ノートブック操作種別（例: `"insert"`, `"replace"`, `"delete"`） |
| `total_cells` | `number` | 編集後のセル総数                                           |

```json
"metadata": {
  "tool_name": "notebook_edit",
  "call_id": "call_01HXYZ",
  "sub_event_type": "file_edited",
  "file_path": "/workspace/exec-12345/analysis.ipynb",
  "operation": "insert",
  "total_cells": 12,
  "status": "edited"
}
```

**render\_diagram 固有（`tool_name: "render_diagram"`）**

| フィールド          | 型                | 説明                                 |
| -------------- | ---------------- | ---------------------------------- |
| `diagram_type` | `string`         | 図の種別（例: `"mermaid"`, `"plantuml"`） |
| `format_used`  | `string`         | 出力フォーマット（例: `"png"`, `"svg"`）      |
| `error`        | `string \| null` | エラー内容（失敗時のみ）                       |

```json
"metadata": {
  "tool_name": "render_diagram",
  "call_id": "call_01HXYZ",
  "sub_event_type": "file_edited",
  "file_path": "/workspace/exec-12345/diagrams/architecture.png",
  "diagram_type": "mermaid",
  "format_used": "png",
  "error": null,
  "status": "created"
}
```

`file_read` — ファイル読み取り

| フィールド         | 型                | 説明                                              |
| ------------- | ---------------- | ----------------------------------------------- |
| `tool_name`   | `string`         | 読み取りツール名。実行経路により異なる（例: `"read"`, `"file_read"`） |
| `file_path`   | `string`         | 読み取り対象ファイルパス                                    |
| `raw_content` | `string`         | 読み取ったファイル内容（生データ）。バイナリの場合はプレビュー不可               |
| `lines_read`  | `number`         | 読み取り行数                                          |
| `total_lines` | `number`         | ファイル全体の行数                                       |
| `is_binary`   | `boolean`        | バイナリファイルかどうか                                    |
| `truncated`   | `boolean`        | 内容が切り詰められたかどうか                                  |
| `status`      | `string`         | `"read"` 固定                                     |
| `line_start`  | `number \| null` | 読み取り開始行                                         |
| `line_end`    | `number \| null` | 読み取り終了行                                         |

```json
"metadata": {
  "tool_name": "read",
  "call_id": "call_01HXYZ",
  "sub_event_type": "file_read",
  "file_path": "/workspace/exec-12345/src/main.py",
  "raw_content": "# Main Application\nimport os\nimport sys\n\ndef main():\n    print('Hello, World!')\n",
  "lines_read": 6,
  "total_lines": 6,
  "is_binary": false,
  "truncated": false,
  "line_start": 1,
  "line_end": 6,
  "status": "read"
}
```

`file_searched` — ファイル検索 (grep / glob / ls)

| フィールド            | 型          | 説明                                                                                                                                                |
| ---------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tool_name`      | `string`   | 検索ツール名。実行経路により異なる（例: `"grep"`, `"glob"`, `"ls"`, `"file_search"`）                                                                                 |
| `status`         | `string`   | `"searched"` (grep) / `"globbed"` (glob) / `"listed"` (ls)                                                                                        |
| `pattern`        | `string`   | 検索パターン（grep / glob の場合）                                                                                                                           |
| `path`           | `string`   | 検索対象パス（grep の場合）                                                                                                                                  |
| `cmd`            | `string`   | 実行されたコマンド（grep の場合）                                                                                                                               |
| `matches`        | `string[]` | マッチ結果の生出力行（grep の場合）。`output_mode` により形式が変わる（`files_with_matches`: ファイルパス配列、`content`: `"path:line:content"` 形式の文字列配列、`count`: `"path:count"` 形式） |
| `files_searched` | `number`   | 検索対象ファイル数（grep の場合）                                                                                                                               |
| `directory`      | `string`   | 対象ディレクトリ（glob / ls の場合）                                                                                                                           |
| `files`          | `string[]` | マッチしたファイル一覧（glob の場合）                                                                                                                             |
| `file_count`     | `number`   | ファイル数（glob / ls の場合）                                                                                                                              |
| `truncated`      | `boolean`  | 結果が打ち切られたかどうか（glob の場合）                                                                                                                           |
| `tree`           | `string`   | ディレクトリツリーの文字列表現（ls の場合）                                                                                                                           |
| `dir_count`      | `number`   | ディレクトリ数（ls の場合）                                                                                                                                   |
| `total_size`     | `number`   | 合計ファイルサイズ（バイト、ls の場合）                                                                                                                             |

**grep（`tool_name: "grep"`）**

```json
"metadata": {
  "tool_name": "grep",
  "call_id": "call_01HXYZ",
  "sub_event_type": "file_searched",
  "pattern": "def main",
  "path": "/workspace/exec-12345/src",
  "cmd": "rg \"def main\" --hidden --max-columns 500 -l /workspace/exec-12345/src",
  "matches": ["src/main.py", "src/utils.py"],
  "files_searched": 2,
  "status": "searched"
}
```

**glob（`tool_name: "glob"`）**

```json
"metadata": {
  "tool_name": "glob",
  "call_id": "call_01HXYZ",
  "sub_event_type": "file_searched",
  "pattern": "**/*.py",
  "directory": "/workspace/exec-12345/src",
  "files": ["main.py", "utils.py", "config.py"],
  "file_count": 3,
  "truncated": false,
  "status": "globbed"
}
```

**ls（`tool_name: "ls"`）**

```json
"metadata": {
  "tool_name": "ls",
  "call_id": "call_01HXYZ",
  "sub_event_type": "file_searched",
  "directory": "/workspace/exec-12345",
  "tree": ".\n├── src/\n│   ├── main.py\n│   └── utils.py\n├── tests/\n└── README.md",
  "file_count": 3,
  "dir_count": 2,
  "total_size": 45678,
  "status": "listed"
}
```

`web_fetched` — Web コンテンツ取得 / ファイル転送

`web_fetched` は **Web ページ取得** と **ファイル転送（download / upload）** の 2 経路で発行されます。`tool_name` で分岐してください。

**webfetch 経由（`tool_name: "webfetch"`）**

| フィールド              | 型         | 説明                                                           |
| ------------------ | --------- | ------------------------------------------------------------ |
| `url`              | `string`  | 取得対象 URL                                                     |
| `content_type`     | `string`  | レスポンスの Content-Type                                          |
| `status_code`      | `number`  | HTTP ステータスコード                                                |
| `truncated`        | `boolean` | 内容が切り詰められたかどうか                                               |
| `from_cache`       | `boolean` | キャッシュから取得したかどうか                                              |
| `status`           | `string`  | `"fetched"` 固定                                               |
| `duration_ms`      | `number`  | 取得時間（ミリ秒）                                                    |
| `response_headers` | `object`  | レスポンスヘッダー                                                    |
| `title`            | `string`  | ツール用の短縮ラベル（`"Fetch: "` + URL 先頭 50 字）。Task レベルの `title` とは別物 |

```json
"metadata": {
  "tool_name": "webfetch",
  "call_id": "call_01HXYZ",
  "sub_event_type": "web_fetched",
  "url": "https://example.com",
  "content_type": "text/html",
  "status_code": 200,
  "truncated": false,
  "from_cache": false,
  "duration_ms": 523,
  "response_headers": {
    "content-type": "text/html; charset=UTF-8",
    "content-length": "1256"
  },
  "title": "Fetch: https://example.com",
  "status": "fetched"
}
```

**ファイル転送系（`tool_name`: `"download"` / `"upload"` / `"download_file"` / `"download_multiple_files"` / `"download_with_resume"` / `"get_file_info_from_url"` / `"check_url_accessibility"` / `"upload_to_ftp"` / `"react_upload_file"` 等）**

| フィールド          | 型                | 説明                            |
| -------------- | ---------------- | ----------------------------- |
| `url`          | `string`         | 対象 URL（アップロード時は `upload_url`） |
| `file_path`    | `string`         | ローカルファイルパス                    |
| `status`       | `string`         | `"completed"` または `"error"`   |
| `success`      | `boolean`        | 成功フラグ                         |
| `file_size`    | `number \| null` | ファイルサイズ（バイト）                  |
| `content_type` | `string`         | ファイルの Content-Type            |

```json
"metadata": {
  "tool_name": "download_file",
  "call_id": "call_01HXYZ",
  "sub_event_type": "web_fetched",
  "url": "https://example.com/data.csv",
  "file_path": "/workspace/exec-12345/downloads/data.csv",
  "success": true,
  "file_size": 204800,
  "content_type": "text/csv",
  "status": "completed"
}
```

`task_launched` — サブタスク起動

| フィールド              | 型                | 説明                                                                                                       |
| ------------------ | ---------------- | -------------------------------------------------------------------------------------------------------- |
| `tool_name`        | `string`         | `"task"`                                                                                                 |
| `agent_type`       | `string`         | 起動したサブエージェント種別                                                                                           |
| `task_description` | `string`         | サブタスクの説明                                                                                                 |
| `success`          | `boolean`        | 成功フラグ                                                                                                    |
| `status`           | `string`         | `"completed"` または `"failed"`                                                                             |
| `title`            | `string`         | ツール用の短縮ラベル（`"{agent_type}: {task_description}"`。30 字超の場合は先頭 27 字 + `"..."` に切り詰め）。Task レベルの `title` とは別物 |
| `duration_ms`      | `number`         | 実行時間（ミリ秒）                                                                                                |
| `error_details`    | `string \| null` | エラー詳細（失敗時のみ）                                                                                             |

```json
"metadata": {
  "tool_name": "task",
  "call_id": "call_01HXYZ",
  "sub_event_type": "task_launched",
  "agent_type": "data_analysis",
  "task_description": "売上データの分析",
  "success": true,
  "title": "data_analysis: 売上データの分析",
  "duration_ms": 45678,
  "error_details": null,
  "status": "completed"
}
```

`video_generated` — 動画生成完了

`video_generated` は **単体生成** と **バッチ生成** の 2 経路で発行されます。`tool_name` で分岐してください。

**単体生成（`tool_name: "generate_video"`）**

| フィールド          | 型                | 説明             |
| -------------- | ---------------- | -------------- |
| `success`      | `boolean`        | 成功フラグ          |
| `job_id`       | `string`         | 動画生成ジョブ ID     |
| `status`       | `string`         | ジョブステータス       |
| `preview_urls` | `string[]`       | プレビュー用 URL 配列  |
| `final_url`    | `string \| null` | 最終動画の URL      |
| `used_prompt`  | `string`         | 実際に使用されたプロンプト  |
| `error`        | `string \| null` | エラー内容（失敗時）     |
| `error_type`   | `string \| null` | エラー種別          |
| `model`        | `string`         | 使用モデル          |
| `created_at`   | `string`         | 作成日時（ISO 8601） |
| `completed_at` | `string`         | 完了日時（ISO 8601） |

```json
"metadata": {
  "tool_name": "generate_video",
  "call_id": "call_01HXYZ",
  "sub_event_type": "video_generated",
  "success": true,
  "job_id": "job-azure-sora-12345",
  "preview_urls": [
    "https://storage.example.com/previews/frame001.jpg",
    "https://storage.example.com/previews/frame002.jpg"
  ],
  "final_url": "https://blob.example.com/exec-12345/generated_video.mp4",
  "used_prompt": "A beautiful sunset over the ocean with waves gently crashing on the shore",
  "error": null,
  "error_type": null,
  "model": "azure/sora-2",
  "created_at": "2026-04-18T15:00:00Z",
  "completed_at": "2026-04-18T15:02:30Z",
  "status": "succeeded"
}
```

**バッチ生成（`tool_name: "generate_videos_batch"`）**

単体生成のフィールド（`job_id` / `preview_urls` / `final_url` / `used_prompt` / `model` 等）は含まれません。バッチ実行の集計値のみが入ります。

| フィールド       | 型         | 説明          |
| ----------- | --------- | ----------- |
| `success`   | `boolean` | バッチ全体の成功フラグ |
| `total`     | `number`  | バッチで処理した動画数 |
| `succeeded` | `number`  | 成功した動画数     |
| `failed`    | `number`  | 失敗した動画数     |

```json
"metadata": {
  "tool_name": "generate_videos_batch",
  "call_id": "call_01HXYZ",
  "sub_event_type": "video_generated",
  "success": false,
  "total": 4,
  "succeeded": 3,
  "failed": 1
}
```

`image_generated` — 画像生成完了

| フィールド             | 型                | 説明                                     |
| ----------------- | ---------------- | -------------------------------------- |
| `tool_name`       | `string`         | `"generation_image"`                   |
| `success`         | `boolean`        | 成功フラグ                                  |
| `image_url`       | `string \| null` | 生成画像の URL                              |
| `local_path`      | `string \| null` | ローカル保存パス                               |
| `original_prompt` | `string`         | 元のプロンプト                                |
| `revised_prompt`  | `string \| null` | リライトされたプロンプト（API が返した場合のみ。返らなければ null） |
| `error`           | `string \| null` | エラー内容（失敗時）                             |
| `error_type`      | `string \| null` | エラー種別                                  |
| `model`           | `string`         | 使用モデル（例: `"gpt-image-1"`）              |
| `created_at`      | `string`         | 作成日時（ISO 8601）                         |

```json
"metadata": {
  "tool_name": "generation_image",
  "call_id": "call_01HXYZ",
  "sub_event_type": "image_generated",
  "success": true,
  "image_url": null,
  "local_path": "/workspace/exec-12345/generated_image.png",
  "original_prompt": "山と湖のある風景画を作成して",
  "revised_prompt": "A serene landscape with mountains in the background, a calm lake in the foreground, and a clear blue sky",
  "error": null,
  "error_type": null,
  "model": "gpt-image-1",
  "created_at": "2026-04-18T15:00:00Z"
}
```

### グループ② 特殊な結果系

Web 検索 / シェルコマンド / MCP ツールは、それぞれ独立した `actionType` として配信されます。`metadata.sub_event_type` は付きません。

#### search\_result

Web 検索の完了結果。

| フィールド          | 型        | 説明                                                               |
| -------------- | -------- | ---------------------------------------------------------------- |
| `query`        | `string` | 検索クエリ                                                            |
| `searchType`   | `string` | 検索タイプ（`"web"` / `"news"` / `"video"` / `"image"` / `"location"`） |
| `searchEngine` | `string` | 使用された検索プロバイダー（例: `"brave"`, `"bing"`, `"duckduckgo"`）            |
| `resultCount`  | `number` | 検索結果の件数                                                          |
| `results`      | `array`  | 検索結果の配列（`SearchResult` オブジェクト — 下記参照）                            |

> **注記**
>
> 検索の完了状態は Task の `status` フィールド（メタデータ外）に入ります。失敗した場合は Task トップレベルに `error`（文字列）が付与されます。

**results\[] の各要素（`SearchResult`）**

| フィールド            | 型                 | 説明                                             |
| ---------------- | ----------------- | ---------------------------------------------- |
| `position`       | `number`          | 検索結果内の順位（1 開始）                                 |
| `url`            | `string`          | 検索結果の URL                                      |
| `title`          | `string`          | タイトル                                           |
| `description`    | `string`          | スニペット/要約                                       |
| `source`         | `string`          | この結果を提供した検索エンジン（例: `"brave"`）                  |
| `raw_content`    | `string \\| null` | ページ本文プレビュー（取得できなかった場合は `null`）                 |
| `published_date` | `string \\| null` | 公開日時（ISO 8601、取得できなかった場合は `null`）              |
| `age`            | `string \\| null` | 経過表現（例: `"December 11, 2025"`、`"2 hours ago"`） |
| `author`         | `string \\| null` | 著者（取得できなかった場合は `null`）                         |
| `site_name`      | `string \\| null` | サイトドメイン名（例: `"softbank.jp"`）                   |

```json
"metadata": {
  "query": "ソフトバンク AGENTIC STAR サービス",
  "searchType": "web",
  "searchEngine": "brave",
  "resultCount": 2,
  "results": [
    {
      "position": 1,
      "url": "https://www.softbank.jp/corp/news/press/sbkk/2025/20251211_01/",
      "title": "法人向けAIエージェントプラットフォームサービス「AGENTIC STAR」を提供開始",
      "description": "ソフトバンク株式会社は、企業におけるさまざまな業務を支援する法人向けAIエージェントプラットフォームサービス「AGENTIC STAR」を提供開始...",
      "source": "brave",
      "raw_content": null,
      "published_date": "2025-12-11T00:00:00",
      "age": "December 11, 2025",
      "author": null,
      "site_name": "softbank.jp"
    },
    {
      "position": 2,
      "url": "https://businessnetwork.jp/article/31937/",
      "title": "ソフトバンクが法人向けAIエージェント「AGENTIC STAR」",
      "description": "ソフトバンクは2025年12月11日に記者説明会を開催し、法人向けAIエージェントプラットフォームサービス「AGENTIC STAR」を提供開始したと発表した。",
      "source": "brave",
      "raw_content": null,
      "published_date": "2025-12-11T06:33:17",
      "age": "December 11, 2025",
      "author": null,
      "site_name": "businessnetwork.jp"
    }
  ]
}
```

#### command\_execution

シェルコマンド実行の完了結果。

| フィールド              | 型        | 説明        |
| ------------------ | -------- | --------- |
| `command`          | `string` | 実行されたコマンド |
| `exitCode`         | `number` | 終了コード     |
| `output`           | `string` | 標準出力      |
| `errorOutput`      | `string` | 標準エラー出力   |
| `workingDirectory` | `string` | 実行ディレクトリ  |

> **注記**
>
> 実行の完了状態は Task の `status` フィールド（`"completed"` / `"error"`、メタデータ外）に入ります。

```json
"metadata": {
  "command": "ls -la /workspace/exec-12345/output",
  "exitCode": 0,
  "output": "total 32\n-rw-r--r-- 1 user user 4201846 Mar 14 10:30 report.pdf\n",
  "errorOutput": "",
  "workingDirectory": "/workspace/exec-12345"
}
```

#### mcp\_tool

MCP (Model Context Protocol) ツール実行の通知。

`mcp_tool` は `metadata` オブジェクトを持ちません。MCP 名・実行メッセージは Task の `title` に、実行内容は `description` に入ります。

> **注記**
>
> `Task.status`（メタデータ外の Task 全体の状態）は現時点で `"in_progress"` のまま推移します。完了判定には利用せず、`description`（実行メッセージ）を参照してください。

### グループ③ ファイル通知系

エージェントが作業ディレクトリ内に成果物ファイルを作成した際の通知です。

#### file\_operation

`files` 配列に作成ファイルの詳細（TaskFile 構造）が入り、同時に `metadata.filePaths` に作業ディレクトリ内のファイルパスが配列で入ります（`files` の並び順に対応）。

**metadata フィールド**

| フィールド           | 型          | 説明                                    |
| --------------- | ---------- | ------------------------------------- |
| `operationType` | `string`   | 操作種別（現時点で `"create"` のみ）              |
| `filePaths`     | `string[]` | 作業ディレクトリ内のファイルパス配列（`files` 配列の並び順に対応） |

`files` の各要素の構造は [TaskFile 構造](#taskfile) を参照してください。

**JSON 例**

```json
{
  "actionType": "file_operation",
  "title": "ファイル作成",
  "description": "report.pdf を作成しました",
  "status": "completed",
  "metadata": {
    "operationType": "create",
    "filePaths": ["/workspace/exec-12345/output/report.pdf"]
  },
  "files": [
    {
      "filename": "report.pdf",
      "size": 4201846,
      "filepath": "https://blob.example.com/abc123/report.pdf",
      "mimeType": "application/pdf"
    }
  ]
}
```

### SSE ストリーム例（tool\_start → tool\_result ペア）

同じ `callId` / `metadata.call_id` で `tool_start` と `tool_result` が紐付きます。

**チャンク 1: ツール開始**

```json
"tasks": [{
  "messageId": "5b47837a-...",
  "conversationId": "09071b95-...",
  "callId": "0cf24f34-bbd9-4833-88c4-d7f520ce3aae",
  "actionType": "tool_start",
  "title": "local assistant",
  "description": "Processing local_assistant",
  "status": "in_progress",
  "metadata": {
    "tool_name": "local_assistant",
    "call_id": "0cf24f34-bbd9-4833-88c4-d7f520ce3aae",
    "status": "starting"
  },
  "files": [],
  "timestamp": 1773499412706,
  "createdAt": "2026-03-14T14:43:32.708Z",
  "updatedAt": "2026-03-14T14:43:32.708Z"
}]
```

**チャンク 2: ツール完了**

```json
"tasks": [{
  "messageId": "5b47837a-...",
  "conversationId": "09071b95-...",
  "callId": "0cf24f34-bbd9-4833-88c4-d7f520ce3aae",
  "actionType": "tool_result",
  "title": "success",
  "description": "Created the requested Python script.",
  "status": "completed",
  "metadata": {
    "tool_name": "local_assistant",
    "call_id": "0cf24f34-bbd9-4833-88c4-d7f520ce3aae",
    "sub_event_type": "local_assistant",
    "message": "Python スクリプトの作成",
    "success": true,
    "result": "Created the requested Python script.",
    "status": "success",
    "execution_time": 12.4,
    "turns_used": 3
  },
  "files": [],
  "timestamp": 1773499362744,
  "createdAt": "2026-03-14T14:42:42.747Z",
  "updatedAt": "2026-03-14T14:42:42.747Z"
}]
```

## 再接続

進行中の会話の SSE ストリームに再接続します。ネットワーク切断後の復帰に使用します。

```text
GET /v1/chat/completions/{conversationId}
```

### 使用例

```bash
# 進行中の会話に再接続
curl -N https://api.fd.agenticstar.tm.softbank.jp/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $TOKEN"
```

> **備考**
>
> 再接続は進行中の会話にのみ可能です。終了済みの会話には `404 Not Found` が返ります。終了済みの会話の結果は、リソース API（`GET /v1/conversations/{conversationId}/messages`）で取得できます。

## キャンセル

進行中の会話をキャンセルし、エージェントの実行を中断します。

```text
POST /v1/chat/completions/{conversationId}/cancel
```

### 使用例

```bash
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000/cancel \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"
```

### レスポンス

```json
{
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "cancelled": true
}
```

#### ストリーム側に流れるもの

キャンセルが受理されると、接続中の SSE ストリームには次のチャンクが 1 件流れ、続けて `data: [DONE]` でストリームが終了します。

```json
{
  "createdAt": "2026-03-14T10:30:07.000Z",
  "model": "AGENTIC STAR",
  "choices": [{
    "index": 0,
    "delta": { "content": "Cancelled" },
    "finishReason": "stop",
    "cancelled": true
  }]
}
```

`delta.content` は固定文言 `"Cancelled"` です。`finishReason` は `"error"` ではなく `"stop"` になるため、正常完了と区別するには `choice.cancelled` を見てください。

## エラーハンドリング

エラーは発生タイミングによって 2 種類のフォーマットで返されます。

### ストリーム開始前のエラー（HTTP エラー）

SSE 接続が確立される前に発生するエラーです。通常の HTTP レスポンスとして JSON 形式で返されます。

| ステータス | 説明                                     |
| ----- | -------------------------------------- |
| `400` | リクエストパラメータ不正（model, messages, stream等） |
| `401` | 認証トークンが無効または未指定                        |
| `403` | chat:exec スコープが不足                      |
| `409` | 指定した会話が現在処理中                           |

HTTP 400 エラーレスポンス:

```json
{
  "error": {
    "type": "invalid_request_error",
    "message": "Parameter 'model' is required",
    "code": "missing_parameter",
    "param": "model",
    "suggested_action": "Please provide the required parameter"
  }
}
```

### ストリーム中のエラー（SSE エラーチャンク）

SSE ストリーミング中にバックエンドで発生したエラーです。finishReason が "error" に設定された ChatCompletionChunk として配信されます。

```text
data: {
  "createdAt": "2026-03-14T10:30:00.000Z",
  "model": "AGENTIC STAR",
  "choices": [{
    "index": 0,
    "delta": { "content": "An error occurred..." },
    "finishReason": "error"
  }]
}

data: [DONE]
```

### リカバリー戦略

| エラー種別                 | 推奨アクション                                           |
| --------------------- | ------------------------------------------------- |
| HTTP エラー（400/401/403） | リクエストパラメータまたは認証情報を確認して再送信                         |
| HTTP 409 Conflict     | 会話の処理完了を待つか、キャンセルしてから再送信                          |
| SSE エラーチャンク           | 新しいメッセージで会話を再開するか、別の会話を開始                         |
| 接続断                   | GET /v1/chat/completions/{conversationId} で再接続を試行 |

## 完全なレスポンス例

ロールチャンク → コンテンツチャンク → 最終チャンクの典型的なストリーミングシーケンスです。

```text
// 1. ロールチャンク（最初の1回）
data: {
  "createdAt": "2026-03-14T10:30:00.000Z",
  "model": "AGENTIC STAR",
  "choices": [{
    "index": 0,
    "delta": {
      "role": "assistant",
      "messageInfo": {
        "conversationId": "550e8400-e29b-41d4-a716-446655440000",
        "messageId": "660f9511-f3ac-52e5-b827-557766551111"
      }
    }
  }]
}

// 2. コンテンツチャンク（複数回）
data: {
  "createdAt": "2026-03-14T10:30:00.123Z",
  "model": "AGENTIC STAR",
  "choices": [{
    "index": 0,
    "delta": {
      "content": "売上データの分析結果です。"
    }
  }]
}

// 2a. タスク実行情報を含むコンテンツチャンク
data: {
  "createdAt": "2026-03-14T10:30:01.500Z",
  "model": "AGENTIC STAR",
  "choices": [{
    "index": 0,
    "delta": {
      "content": "データを分析しています...",
      "tasks": [{
        "messageId": "660f9511-f3ac-52e5-b827-557766551111",
        "conversationId": "550e8400-e29b-41d4-a716-446655440000",
        "callId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "actionType": "tool_start",
        "status": "in_progress",
        "title": "local assistant",
        "metadata": { "tool_name": "local_assistant", "call_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "starting" },
        "timestamp": 1710410001500,
        "createdAt": "2026-03-14T10:30:01.500Z",
        "updatedAt": "2026-03-14T10:30:01.500Z"
      }]
    },
    "status": { "processing": true, "unfinished": true }
  }]
}

// 3. 最終チャンク（成果物・ステータス付き）
data: {
  "createdAt": "2026-03-14T10:30:05.456Z",
  "model": "AGENTIC STAR",
  "choices": [{
    "index": 0,
    "delta": {
      "content": "以上が分析結果です。",
      "tasks": [{
        "messageId": "660f9511-f3ac-52e5-b827-557766551111",
        "conversationId": "550e8400-e29b-41d4-a716-446655440000",
        "callId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "actionType": "tool_result",
        "status": "completed",
        "title": "success",
        "description": "売上データの分析が完了しました。",
        "metadata": {
          "tool_name": "local_assistant",
          "call_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "sub_event_type": "local_assistant",
          "message": "売上データの分析",
          "success": true,
          "result": "売上データの分析が完了しました。",
          "status": "success",
          "execution_time": 45.6,
          "turns_used": 3,
          "files_created": ["/files/output/report.pdf"]
        },
        "timestamp": 1710410000000,
        "createdAt": "2026-03-14T10:30:05.400Z",
        "updatedAt": "2026-03-14T10:30:05.400Z"
      }]
    },
    "finishReason": "stop",
    "status": { "processing": false, "unfinished": false },
    "deliverables": [{
      "filename": "report.pdf",
      "filepath": "/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.pdf",
      "source": "agent",
      "isPrimary": true,
      "createdAt": "2026-03-14T10:30:05.000Z",
      "mimeType": "application/pdf",
      "size": 4201846
    }]
  }]
}

// 4. ストリーム終了
data: [DONE]
```
