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）に戻る

接続ライフサイクル

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":"tool_result","callId":"0cf24f34-bbd9-4833-88c4-d7f520ce3aae","title":"success","status":"completed","timestamp":1773499412706}]}}]}
                                     ↑ タスク実行情報を含むチャンク（複数回）

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

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）が含まれることもあります。複数回配信されます。
: heartbeat	SSE コメント行。長時間アイドル時のコネクション維持用（プロキシのアイドルタイムアウト対策）。約30秒間隔で挿入されます。data: で始まらないため通常のクライアントは自動的に無視します。
最終チャンク	finishReason が設定されたチャンク。status（実行状態）や deliverables（成果物）が含まれることがあります。
data: [DONE]	ストリーム終了シグナル。この後 SSE 接続が閉じられます。

レスポンスヘッダー

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

レスポンスオブジェクト

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

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	エージェントが生成した成果物ファイルの配列

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 データモデル」を参照してください。

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.interaction

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

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

型	説明	含まれるフィールド
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	エージェントがバックグラウンドで処理を継続中かどうか。通常は 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": "/files/output/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」「status」「deliverables」までの仕様は基盤が保証する範囲です。

delta.tasks[] の actionType 値や metadata の内部構造は、SaaS 版のエージェント実装に基づいて記載しています。マーケットプレイス版で独自エージェントを開発する場合、これらは実装に依存するため、参考情報として利用してください。

全体像

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" で除外しても構いません。

共通フィールド

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

フィールド	型	説明
messageId	string	Task が属するメッセージの ID
conversationId	string	Task が属する会話の ID
actionType	string	可変部の構造を決める discriminator（§ actionType 分岐マップ）
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 によって構造が変わる（グループごとの詳細参照）
files	TaskFile[]	関連ファイル。主に file_operation で使用（TaskFile の構造は こちら）
timestamp	number	Task のタイムスタンプ（Unix ミリ秒）
createdAt	string	作成日時（ISO 8601）
updatedAt	string	更新日時（ISO 8601）

表示用テキストをプログラム分岐に使わない

title / description / content は人間可読なテキストです。プログラム側の分岐条件には使用しないでください。分岐には actionType / status / metadata.sub_event_type を使います。

フィールド	典型的な用途
title	タスク種別・対象の短い見出し（例: ツール名、MCP 名）
description	実行中メッセージや補足説明
content	ツール出力の本文

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 ストリーム例 を参照してください。

---

次からはグループごとに 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 種）
status	string	ツール固有の実行結果ステータス。Task.status（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 ストリームに送信されます。（Desktop App 連携時に限り、macos_automation が追加されることがあります。未知の値として安全に無視する実装を推奨します。）

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 オブジェクト — 下記参照）

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	実行ディレクトリ

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) ツール実行の通知。

metadata は現時点で省略

actionType: "mcp_tool" のタスクでは metadata は現時点で省略されます。ツール名・実行ステータスは title（MCP 名）と description（実行メッセージ）から参照してください。将来的に metadata にフィールドが追加される可能性があります。

なお、Task.status は現時点で "in_progress" のまま推移します。完了判定には利用せず、description（実行メッセージ）を参照してください。

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

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

file_operation

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

metadata フィールド

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

TaskFile 構造

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

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

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 ストリームに再接続します。ネットワーク切断後の復帰に使用します。

GET /v1/chat/completions/{conversationId}

使用例

curl

# 進行中の会話に再接続
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）で取得できます。

キャンセル

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

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

使用例

curl

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
}

エラーハンドリング

エラーは発生タイミングによって 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 として配信されます。

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

完全なレスポンス例

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

// 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": "/files/output/report.pdf",
      "source": "agent",
      "isPrimary": true,
      "createdAt": "2026-03-14T10:30:05.000Z",
      "mimeType": "application/pdf",
      "size": 4201846
    }]
  }]
}

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