SSE ストリーミングガイド

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

概要

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

ポイント

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

Chat API リファレンスに戻る

接続ライフサイクル

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

SSE イベントフロー

: 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":"execute","title":"データ分析","status":"running","timestamp":1234567890}]}}]}
                                     ↑ タスク実行情報を含むチャンク（複数回）

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 に追記テキストが含まれます。エージェントのタスク実行情報（delta.tasks）が含まれることもあります。複数回配信されます。
最終チャンク	finishReason が設定されたチャンク。status（実行状態）や deliverables（成果物）が含まれることがあります。
data: `[DONE]`	ストリーム終了シグナル。この後 SSE 接続が閉じられます。

レスポンスヘッダー

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

ChatCompletionChunk オブジェクト

各 SSE イベントの data: 行に含まれるトップレベルオブジェクトです。

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

JSON
data: {
  "createdAt": "2026-03-14T10:30:00.000Z",
  "model": "AGENTIC STAR",
  "choices": [{ ... }]
}

Choice オブジェクト

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

パラメータ	型	説明
`index`	`number`	常に `0`
`delta`	`object`	差分データ。以下の Delta オブジェクトを参照。
`finishReason`	`string \| null`	`"stop"`（正常完了）、`"error"`（エラー）、または `null`（ストリーミング中）
`status`	`object`	`{ processing: boolean, unfinished: boolean }` — エージェントの実行状態
`deliverables`	`array`	エージェントが生成した成果物ファイルの配列

Delta オブジェクト

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

パラメータ	型	出現	説明
`role`	`string`	最初のみ	最初のチャンクでのみ送信。`"assistant"` 固定。
`messageInfo`	`object`	最初のみ	`{ conversationId, messageId }` — メッセージ識別情報
`content`	`string`	複数回	テキストコンテンツの差分
`tasks`	`array`	複数回	エージェントのタスク実行情報（タスク状態が更新されるたびに送信）
`interaction`	`object`	条件付き	ユーザー対話リクエスト（選択肢提示等）

Delta 拡張フィールド

AgenticStar は OpenAI 互換のフォーマットにエージェント固有の拡張フィールドを追加しています。各フィールドはストリーミング中またはストリーム終了時に、それぞれ固有のタイミングで配信されます。

delta.tasks

エージェントのタスク実行情報。ツール実行・ファイル作成・検索などのアクション発生時に SSE チャンクの delta.tasks 配列として配信されます。Task データモデルの完全な定義はコンセプトガイドを参照してください。

SSE 配信コンテキスト

delta.tasks はタスク状態が更新されるたびに SSE チャンクに含まれます。1 チャンクに含まれる Task は通常 1 件です。delta.content と delta.tasks は同一チャンクに共存します。

SSE チャンク内での delta.tasks の位置:

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",
        "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 }
  }]
}

Task オブジェクトフィールド

パラメータ	型	必須	説明
`messageId`	`string`	✓	タスクが属するメッセージのID
`conversationId`	`string`	✓	タスクが属する会話のID
`actionType`	`string`	✓	`"tool_start"` \| `"tool_result"` \| `"search_result"` \| `"command_execution"` \| `"mcp_tool"` \| `"file_operation"` など
`status`	`string`	✓	`"pending"` \| `"in_progress"` \| `"completed"` \| `"failed"` \| `"success"` \| `"error"`
`timestamp`	`number`	✓	タスクのタイムスタンプ（Unix ミリ秒）
`createdAt`	`string`	✓	タスク作成日時（ISO 8601）
`updatedAt`	`string`	✓	タスク更新日時（ISO 8601）
`title`	`string`		タスクのタイトル（表示用）
`description`	`string`		タスクの詳細説明
`callId`	`string \| null`		ツール呼び出しID。`tool_start` と対応する `tool_result` を紐付け。多くの actionType では `null`（[詳細](connection-guide.md#task-data-model)）
`content`	`string`		タスクの出力コンテンツ
`metadata`	`object`		タスクのメタデータ。actionType に応じて異なるフィールドを含む（[詳細](connection-guide.md#task-data-model)）
`files`	`TaskFile[]`		タスクに関連するファイルの配列

TaskFile フィールド

パラメータ	型	説明
`filename`	`string`	ファイル名
`fileType`	`string`	`"pdf"`, `"image"`, `"text"`, `"pptx"`, `"video"`, `"other"`
`size`	`number`	ファイルサイズ（バイト）
`filepath`	`string`	ファイルパス

TaskFile の例:

JSON
"files": [
  {
    "filename": "qr_code_decode_report.pdf",
    "fileType": "pdf",
    "size": 4201846,
    "filepath": "/plans/{conversationId}/files/qr_code_decode_report.pdf"
  }
]

代表的な actionType

actionType	説明
`tool_start`	特定ツールの開始通知（local_assistant / generate_video / Sandbox）
`tool_result`	汎用ツール実行の結果。`metadata.sub_event_type` でツール種別を識別
`search_result`	Web 検索の完了結果
`command_execution`	シェルコマンド実行の完了結果
`mcp_tool`	MCP ツール実行の結果（metadata なし）
`file_operation`	ファイル作成の完了通知

SSE ストリーム例: ツール実行ペア

チャンク 1: ツール開始（local_assistant）

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: ツール完了（同じ callId / metadata.call_id で紐付け）

JSON
"tasks": [{
  "messageId": "5b47837a-...",
  "conversationId": "09071b95-...",
  "callId": "call_T3GIhcQQft13amxdhcJ4cBDz",
  "actionType": "tool_result",
  "title": "success",
  "description": "{'result': 'ok'}",
  "status": "in_progress",
  "metadata": {
    "tool_name": "bash",
    "call_id": "call_T3GIhcQQft13amxdhcJ4cBDz",
    "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"
}]

delta.interaction

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

InteractionExtension フィールド

パラメータ	型	必須	説明
`interactionType`	`string`	✓	`"choice"` \| `"confirmation"`
`content`	`string`		対話メッセージの本文（choice / confirmation で送信）
`options`	`string[]`		interactionType: "choice" の場合のみ。選択肢の配列。

interactionType 一覧

型	説明	含まれるフィールド
`choice`	選択肢を提示し、ユーザーに1つを選択させる	`content`, `options`
`confirmation`	ユーザーに確認（承認/拒否）を求める	`content`

choice の例:

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

confirmation の例:

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

choice.status

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

パラメータ	型	説明
`processing`	`boolean`	エージェントがバックグラウンドで処理を継続中かどうか。`true` の場合、再接続で後続イベントを受信可能。
`unfinished`	`boolean`	タスクが未完了かどうか。ユーザー対話の待機中や長時間処理中に true となる。

JSON
"status": { "processing": false, "unfinished": false }

choice.deliverables

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

DeliverableFile フィールド

パラメータ	型	説明
`filename`	`string`	ファイル名
`filepath`	`string`	ファイルパス（ダウンロード用の相対パス）
`fileType`	`string`	`"pdf"`, `"image"`, `"text"`, `"pptx"`, `"video"`, `"other"`
`source`	`string`	`"agent"`（エージェント生成）または `"user"`（ユーザーアップロード）。
`isPrimary`	`boolean`	主要成果物かどうか
`createdAt`	`string`	作成日時（ISO 8601形式）

JSON
"deliverables": [{
  "filename": "report.pdf",
  "filepath": "/files/output/report.pdf",
  "fileType": "pdf",
  "source": "agent",
  "isPrimary": true,
  "createdAt": "2026-03-14T10:30:05.000Z"
}]

再接続

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

GET /v1/chat/completions/{conversationId}

パスパラメータ

パラメータ	型	説明
`conversationId`	`string`	再接続する会話のID

使用例

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

再接続のタイミング

シナリオ	説明
ネットワーク切断	クライアント側のネットワーク障害後、X-Conversation-Id を使って再接続

備考

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

キャンセル

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

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

使用例

curl
curl -X POST https://api.agenticstar.jp/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
}

エラーハンドリング

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

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

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

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

HTTP 400 エラーレスポンス:

JSON
{
  "error": {
    "code": 400,
    "message": "Parameter 'model' is required"
  }
}

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

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

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} で再接続を試行

完全なレスポンス例

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

JSON
// 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",
        "actionType": "tool_start",
        "status": "in_progress",
        "title": "local assistant",
        "metadata": { "tool_name": "local_assistant", "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",
        "actionType": "tool_result",
        "status": "in_progress",
        "title": "データ分析",
        "content": "分析が完了しました。",
        "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": "/files/output/report.pdf",
      "fileType": "pdf",
      "source": "agent",
      "isPrimary": true,
      "createdAt": "2026-03-14T10:30:05.000Z"
    }]
  }]
}

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

概要​

接続ライフサイクル​

SSE イベントフロー​

各フェーズの詳細​

レスポンスヘッダー​

ChatCompletionChunk オブジェクト​

Choice オブジェクト​

Delta オブジェクト​

Delta 拡張フィールド​

delta.tasks​

SSE 配信コンテキスト​

Task オブジェクト フィールド​

TaskFile フィールド​

代表的な actionType​

SSE ストリーム例: ツール実行ペア​

delta.interaction​

InteractionExtension フィールド​

interactionType 一覧​

choice.status​

choice.deliverables​

DeliverableFile フィールド​

再接続​

パスパラメータ​

使用例​

再接続のタイミング​

キャンセル​