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

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

## このガイドの読み方

マーケットプレイス版のエージェントは、導入企業が AGENTIC STAR Platform SDK を使って自ら開発します。そのため SSE レスポンスには、**プラットフォームが必ず行う部分**と、**エージェントの実装次第で現れたり現れなかったりする部分**があります。分岐処理を書く前に、この区別を押さえてください。

### プラットフォームが必ず行うこと

接続先のエージェントに関係なく、次は常に同じです。

- 接続と終端 — `: connected` / `: heartbeat` / `data: [DONE]`、ロールチャンクと `messageInfo`、レスポンスヘッダー
- 会話開始時にプラットフォームが送る起動通知（`delta.content` を 1 件）
- Task のフィールド名と既定値の補完、`files` の正規化、内部キーの除去
- `outputFormat` を指定しない場合のプレーンテキスト化
- `finishReason: "stop"` での終端 — SDK の runner が成功のときに終端イベントを送るため（失敗のときは `finishReason: "stop"` が付かないことがあります）
- キャンセルが受理されたときの `cancelled: true` チャンク

### エージェントの実装次第で現れるもの

| 項目                    | 現れる条件                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------- |
| `delta.tasks`         | エージェントが `metadata.actionType` を指定してツールイベントを送った場合。指定が無いと Task にはならず、本文（`delta.content`）に落ちます |
| `delta.interaction`   | エージェントがユーザーへの問いかけを実装している場合                                                                  |
| `choice.deliverables` | エージェントが成果物ファイルを送った場合                                                                        |
| `delta.content` の中身   | 最終応答・途中経過・思考過程がすべてここに流れます。どれがどれかを区別する情報は付きません                                               |

これらは「届くこともある」ものです。**接続先のエージェントが実際に何を送るかを確認してから**、クライアント側の分岐を実装してください。

## 概要

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/marketplace/basic/api/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` です。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` | 条件付き | ユーザー対話リクエスト（選択肢提示等）                         |

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

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

| フィールド                 | レベル    | 説明             |
| --------------------- | ------ | -------------- |
| `delta.tasks`         | 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": "コマンドを実行しています",
      "tasks": [{
        "messageId": "5b47837a-...",
        "conversationId": "09071b95-...",
        "callId": "call-1",
        "actionType": "command_execution",
        "title": "コマンド実行",
        "description": "コマンドを実行しています",
        "status": "in_progress",
        "metadata": { "call_id": "call-1", "command": "ls -la" },
        "timestamp": 1773499412706,
        "createdAt": "2026-03-14T14:43:32.708Z",
        "updatedAt": "2026-03-14T14:43:32.708Z"
      }]
    },
    "status": { "processing": true, "unfinished": true }
  }]
}
```

### delta.interaction

エージェントがタスク実行中にユーザーの入力を求めるときに送信されます。

> **エージェントが実装している場合にのみ発生します**
>
> SDK が提供しているのは `EventType.USER_INTERACTION_REQUIRED` という**手段**だけで、どの場面で問いかけるか、そもそも問いかけるかどうかはエージェントの実装次第です。`metadata.interaction_type`（`question`・`choice`・`confirmation`）は、エージェントが自分で入れる値です。対話を実装していないエージェントでは `delta.interaction` は一度も現れません。接続先のエージェントが対話を使うかどうかを確認してから実装してください。

エージェントはこのイベントを出した時点で実行ループを止め、ターンを閉じます。したがってクライアントは内容をユーザーに提示し、**回答を次のリクエストで送って会話を継続させる必要があります**。これを実装しないと、対話を使うエージェントでは会話がそこで止まります。

| パラメータ             | 型          | 必須 | 説明                                                                              |
| ----------------- | ---------- | -- | ------------------------------------------------------------------------------- |
| `interactionType` | `string`   | ✓  | `"question"` \| `"choice"` \| `"confirmation"`                                  |
| `content`         | `string`   |    | 対話メッセージの本文                                                                      |
| `options`         | `string[]` |    | 選択肢の配列。`choice` でのみ付きます（最大 10 件・各 200 文字以内）。**要素数は決め打ちせず、渡された配列をそのまま提示してください。** |

| interactionType | 用途              | エージェントの送り方                                                                                   |
| --------------- | --------------- | -------------------------------------------------------------------------------------------- |
| `question`      | 自由記述での回答を求める    | `USER_INTERACTION_REQUIRED` を送り、`metadata` に `interaction_type: "question"` を入れる             |
| `choice`        | 選択肢を提示し、1つを選ばせる | `USER_INTERACTION_REQUIRED` を送り、`metadata` に `interaction_type: "choice"` と `options[]` を入れる |
| `confirmation`  | 承認 / 拒否を求める     | `USER_INTERACTION_REQUIRED` を送り、`metadata` に `interaction_type: "confirmation"` を入れる         |

回答は、次の `POST /v1/chat/completions` に同じ `conversationId` を指定してテキストで送信します。SSE ストリーム内で回答を返す経路はありません。`options` がある場合は選択肢として提示したうえで、ユーザーが選んだ内容をテキストで送ってください。`question` と `confirmation` には `options` が付かないため、`content` の本文を読んで回答を組み立てます。

`question` の例:

```json
"interaction": {
  "interactionType": "question",
  "content": "出力の対象期間はいつからいつまでですか？"
}
```

`choice` の例:

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

`confirmation` の例:

```json
"interaction": {
  "interactionType": "confirmation",
  "content": "このファイルを削除してよいですか？"
}
```

### 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"`）。filename から判定できない場合は省略される |
| `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` または `pending`）を入れるため、空にはなりません。値は固定の一覧ではないので、決まった値だけを想定しないでください。ツール固有の詳細ステータスは `metadata.status` に格納され、本フィールドとは別の値です |
| `callId`         | `string \| null` | エージェントが `metadata.call_id` を入れた Task のみ値を持ち、無い場合は `null`。同じ値で開始と結果の Task が紐付きます                                                                                                |
| `title`          | `string`         | タスク種別や対象の短い見出し（表示用）                                                                                                                                                            |
| `description`    | `string`         | 実行中メッセージや補足説明（表示用）                                                                                                                                                             |
| `content`        | `string`         | タスクの出力本文（表示用、長文になり得る）                                                                                                                                                          |
| `metadata`       | `object`         | `actionType` によって構造が変わる（[actionType の詳細](#action-type)参照）                                                                                                                      |
| `files`          | `TaskFile[]`     | 関連ファイル（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 から判定できない場合は省略される |

### actionType と metadata

マーケットプレイス版のエージェントは、導入企業が自ら開発し、AGENTIC STAR Platform SDK を使って実装します。**本節はその前提で記載しています。** そのため `delta.tasks[]` の中身は接続先のエージェントによって変わります。プラットフォームは Task のフィールド名と既定値を保証しますが、**値そのものは検証も変換もせず、エージェントが送ったまま配信します**。

| 決まるもの                                                                                           | 決める主体    |
| ----------------------------------------------------------------------------------------------- | -------- |
| Task のフィールド名（actionType / status / title / description / metadata / files / callId / timestamp） | プラットフォーム |
| 未指定時の既定値                                                                                        | プラットフォーム |
| `actionType` の値                                                                                 | エージェント   |
| `metadata` のキーと構造                                                                               | エージェント   |
| `title` / `description` / `content` の文言                                                         | エージェント   |
| `files` に載せる成果物                                                                                 | エージェント   |

> **未指定時の既定値**
>
> `actionType` / `title` / `description` が未指定の場合は空文字が入ります。`status` は未指定でもプラットフォームが既定値（`in_progress` または `pending`）を入れるため、空にはなりません。`timestamp` はプラットフォームが採番します。`callId` は `metadata.call_id` から取り出され、無い場合は `null` になります。

#### actionType に入る値

SDK でエージェントが `metadata.actionType` に指定できる値は、次の 7 つです。

| actionType          | 用途          |
| ------------------- | ----------- |
| `command_execution` | コマンド実行      |
| `code_execution`    | コード実行       |
| `file_operation`    | ファイル操作      |
| `browser_action`    | ブラウザ操作      |
| `search_result`     | 検索結果        |
| `image_search`      | 画像プレビュー     |
| `markdown_display`  | Markdown 表示 |

エージェント側の指定方法は [イベント / ストリーミングガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/basic/develop/guide/events-guide.md#%E8%A1%A8%E7%A4%BA%E6%96%B9%E6%B3%95%E3%81%94%E3%81%A8%E3%81%AE%E5%AE%9F%E8%A3%85%E3%82%AC%E3%82%A4%E3%83%89) を参照してください。

> **actionType を指定しないツールイベントは Task になりません**
>
> `actionType` は SDK では任意指定です。しかしプラットフォームは、`actionType` を持たない Task を `delta.tasks` に含めず、その本文を `delta.content` として配信します。つまりエージェントが `metadata.actionType` を入れていない場合、**ツール実行の情報は `delta.tasks` に一切現れません**。

> **ツール実行の開始と完了を対応付ける**
>
> SDK ではツール実行の開始・完了を `EventType.TOOL_START` / `TOOL_RESULT` で表します。どちらも `actionType` には上の 7 値のいずれかが入るため、両者の対応付けには `callId`（`metadata.call_id`）を使ってください。同じ値を持つ 2 件が 1 つのツール実行を表します。

#### 本文として届くもの

次のイベントは、いずれも `delta.content` として届きます。**種類を区別する情報は付きません。**

| SDK のイベント                               | エージェント側の意図   |
| --------------------------------------- | ------------ |
| `` `PROGRESS_MESSAGE` ``                | 処理中のローディング表示 |
| `` `THOUGHT_MESSAGE` ``                 | エージェントの思考過程  |
| `` `PHASE_START` / `PROGRESS_UPDATE` `` | フェーズ開始・進捗更新  |
| `` `COMPLETION_SUCCESS` ``              | 最終応答の本文      |

最終的な回答も、途中経過も、思考過程も、すべて `delta.content` に流れます。API 利用者側でこれらを分離する手段はありません。最終応答だけを取り出したい場合は、`finishReason: "stop"` が付いたチャンクを待ってください。

#### 終了とエラー

SDK は、成功のときは終端イベント `COMPLETION_SUCCESS`（Webhook の `finish_reason` は `"stop"`）、失敗のときは `COMPLETION_FAILURE`（`"error"`）を送ります。成功したときは、ストリームは `finishReason: "stop"` で閉じます。エージェント側で発生したエラーは、エラー内容を含んだ `delta.content` として届きます。失敗したときは、`finishReason: "stop"` のチャンクが付かないことがあるので、完了を待つときは、自分で待ち時間を決めてください。

後述の「[エラーハンドリング](#%E3%82%A8%E3%83%A9%E3%83%BC%E3%83%8F%E3%83%B3%E3%83%89%E3%83%AA%E3%83%B3%E3%82%B0)」に記載した `finishReason: "error"` と SSE エラーチャンクは、プラットフォーム側で障害が起きた場合に限られます。

#### 応答がどのように届くか

マーケットプレイス版のエージェントは、実行結果をプラットフォームの Webhook（環境変数 `WEBHOOK_URL` 宛）に送信します。この Webhook のペイロードが、本ドキュメントに記載した SSE レスポンスの元データです。SDK（`run_marketplace_agent` / `create_marketplace_handler`）がこのペイロードを組み立てます。

| SDK が送るもの                    | 外部 API に現れる場所                                                 |
| ---------------------------- | ------------------------------------------------------------- |
| `chunk_type: "task_created"` | `delta.tasks[]` の 1 要素                                        |
| `chunk_type: "content"`      | `delta.content`。`interaction_type` を伴う場合は `delta.interaction` |
| `deliverable_files`          | `choice.deliverables`                                         |

#### プラットフォームが送る最初のチャンク

会話を開始すると、エージェントが応答を返すより先に、プラットフォームがエージェントの起動を知らせる `delta.content` チャンクを 1 件配信します。文面はリクエストの言語に応じた固定文言で、日本語では「エージェント *（エージェント名）* がタスクを実行中です。」、英語では "Agent *(name)* is now executing your task." です。

このチャンクは Task にはなりません。`actionType` を持たないため `delta.tasks` には含まれず、`delta.content` としてのみ配信されます。エージェントが生成した文章ではない点に注意してください。

#### プラットフォームが除去するフィールド

エージェントが送った値のうち、以下は外部 API に出る前に取り除かれます。

| 対象                                     | 理由        |
| -------------------------------------- | --------- |
| `_` で始まるすべてのキー（Task 直下・metadata 内を問わず） | 内部用途      |
| `user` / `taskId`                      | 内部パイプライン用 |

`files` の各要素は、`filename` / `size` / `filepath` / `mimeType` の形に正規化されます（[TaskFile 構造](#taskfile)）。

#### クライアント実装の指針

- `actionType` による分岐は、**接続先エージェントが実際に送る値を確認したうえで**実装してください。上の 7 値は「指定できる値」であって、どれが送られるかはエージェント次第です。
- 未知の `actionType` / `metadata` キーは安全に無視できる実装にしてください。エージェントの更新で新しい値が増えることがあります。
- 表示だけが目的であれば、`title` / `description` / `content` と `status` だけで組み立てられます。この 4 つはどのエージェントでも同じ意味で入ります。
- プログラムの分岐に `title` / `description` / `content` を使わないでください（人間可読なテキストのため）。

## 再接続

進行中の会話の 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` | 認証トークンが無効または未指定                        |
| `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） | リクエストパラメータまたは認証情報を確認して再送信                         |
| 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.120Z",
  "model": "AGENTIC STAR",
  "choices": [{
    "index": 0,
    "delta": { "content": "エージェント 売上分析アシスタント がタスクを実行中です。" }
  }]
}

// 3. ツール実行の開始（同じ callId で完了と対応します）
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": "call-1",
        "actionType": "command_execution",
        "status": "in_progress",
        "title": "コマンド実行",
        "description": "コマンドを実行しています",
        "metadata": { "call_id": "call-1", "command": "python3 analyze.py" },
        "timestamp": 1710410001500,
        "createdAt": "2026-03-14T10:30:01.500Z",
        "updatedAt": "2026-03-14T10:30:01.500Z"
      }]
    },
    "status": { "processing": true, "unfinished": true }
  }]
}

// 4. ツール実行の完了（callId が 3 と同じ）
data: {
  "createdAt": "2026-03-14T10:30:04.200Z",
  "model": "AGENTIC STAR",
  "choices": [{
    "index": 0,
    "delta": {
      "content": "コマンドが完了しました",
      "tasks": [{
        "messageId": "660f9511-f3ac-52e5-b827-557766551111",
        "conversationId": "550e8400-e29b-41d4-a716-446655440000",
        "callId": "call-1",
        "actionType": "command_execution",
        "status": "completed",
        "title": "コマンド実行",
        "description": "コマンドが完了しました",
        "metadata": { "call_id": "call-1", "command": "python3 analyze.py", "output": "rows=1204" },
        "timestamp": 1710410004200,
        "createdAt": "2026-03-14T10:30:04.200Z",
        "updatedAt": "2026-03-14T10:30:04.200Z"
      }]
    },
    "status": { "processing": true, "unfinished": true }
  }]
}

// 5. 最終チャンク（成果物・ステータス付き）
data: {
  "createdAt": "2026-03-14T10:30:05.456Z",
  "model": "AGENTIC STAR",
  "choices": [{
    "index": 0,
    "delta": { "content": "以上が分析結果です。" },
    "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
    }]
  }]
}

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