メインコンテンツへスキップ

​
エージェント実行（ストリーミング）

Server-Sent Events (SSE) を使ってエージェントを実行し、応答をリアルタイムにストリーミングで受け取ります。エージェントがテキストを生成するたびに delta イベントが送信されます。
長時間の調査タスクや、リアルタイムで応答を表示したい UI アプリケーションに最適です。完了まで待つだけなら エージェント実行（非ストリーミング） も使えます。

​
新規実行

POST /api/v1/agent/run/stream

​
ヘッダー

ヘッダー必須説明
AuthorizationはいBearer snorbe_... 形式の API キー
Content-Typeはいapplication/json
Acceptはいtext/event-stream

​
リクエストボディ

{
  "modelName": "gpt-5-mini-2025-08-07",
  "inputText": "AIエージェントの最新論文を調べて",
  "promptKey": "chat-routing",
  "locale": "ja",
  "fileUrls": [],
  "mentions": [],
  "maxBrowsingSteps": 5,
  "extendedContextEnabled": false
}

​
パラメータ

パラメータ型必須説明
modelNamestringはい使用するモデル名
inputTextstringはいエージェントへの入力テキスト
promptKeystringはいプロンプトキー（通常は "chat-routing"）
localestringはい"ja" または "en"
fileUrlsstring[]いいえ添付ファイル URL（最大10件）。デフォルト: []
agentIdstringいいえエージェント ID。省略時はデフォルトエージェント
mentionsMention[]いいえ@メンション（エンティティ・AgentRun・ソース・他 Agent の参照）。デフォルト: []。type: "agent" を含めると呼び出し先が mentionAgent で他 Agent に委譲できる（詳細は /agent/run を参照）
maxBrowsingStepsnumberいいえブラウジングの最大ステップ数（1-100）
maxChainStepsnumberいいえAgent 間メンション連鎖の最大深さ（1-50、デフォルト 10）
maxRetriesnumberいいえリトライ回数（0-5）
retryDelayMsnumberいいえリトライ間隔（ms、0-10000）
includeOthersEntitiesbooleanいいえ他ユーザーのエンティティも RAG 検索対象にする。デフォルト: true
extendedContextEnabledbooleanいいえ拡張コンテキスト（モデル最大トークンの 80% を使用）。デフォルト: false
matrixEditContextobjectいいえマトリクス編集コンテキスト（sourceRunId + selection）
matrixContinueContextobjectいいえマトリクス継続コンテキスト（sourceRunId）
matrixSelectionContentstringいいえマトリクス選択 XML（<matrix_selection> 形式）

​
Mention オブジェクト

{
  "id": "entity_abc123",
  "type": "entity",
  "label": "GPT-5"
}
フィールド型説明
idstring参照先の ID（エンティティ・AgentRun・ソース）
typestring"entity" / "agent-run" / "public-source" / "private-source"
labelstring表示名

​
レジューム（既存実行の再開）

HITL（Human-in-the-Loop）によるプラン確認やレポート確認の後に、実行を再開する場合に使用します。 
POST /api/v1/agent/run/stream/{runId}

​
リクエストボディ

{
  "modelName": "gpt-5-mini-2025-08-07",
  "extendedContextEnabled": false
}

​
パラメータ

パラメータ型必須説明
modelNamestringはい使用するモデル名
extendedContextEnabledbooleanいいえ拡張コンテキストを有効にするか。デフォルト: false

​
SSE イベント形式

各イベントは data: {JSON}\n\n 形式で送信されます。

​
config イベント

ストリーム開始時に1回送信されます。 
data: {"type":"config","payload":{"runId":"clxyz...","modelName":"gpt-5-mini-2025-08-07","locale":"ja","inputText":"..."}}

​
delta イベント

エージェントがテキストを生成するたびに送信されます。 
data: {"type":"delta","payload":{"runId":"clxyz...","deltaText":"生成されたテキスト","responseText":"これまでの全テキスト","stepIndex":0,"modelId":"gpt-5-mini-2025-08-07","provider":"openai"}}

​
step イベント

各実行ステップの完了時に送信されます。 
data: {"type":"step","payload":{"runId":"clxyz...","stepIndex":0,"status":"complete","finishReason":"stop","usage":{"inputTokens":1234,"outputTokens":567}}}

​
browse イベント

browse ツールが選ばれた場合は、ブラウザ操作の進行状況が送信されます。 
data: {"type":"browse-start","payload":{"runId":"clxyz...","websocketInfo":{"session_id":"browser-session-id","user_id":"user-id","ws_url":"wss://...","token":"..."}}}
data: {"type":"browse-step","payload":{"runId":"clxyz...","stepIndex":1,"action":"クリック","screenshot":"..."}}
data: {"type":"browse-ask-human","payload":{"runId":"clxyz...","status":"pending","question":"どのメニューを開きますか？"}}
data: {"type":"browse-final","payload":{"runId":"clxyz...","result":"取得した情報..."}}
data: {"type":"browse-end","payload":{"runId":"clxyz..."}}
browse-ask-human を受け取ったら、browse-start.payload.websocketInfo.session_id を sessionId として /browser/answer-question に回答します。plan/report/matrix と違い、回答後に /agent/run/stream/{runId} を呼ぶ必要はありません。

​
complete イベント

エージェント実行が完了した時に送信されます。ストリームの最後のイベントです。 
data: {"type":"complete","payload":{"runId":"clxyz...","text":"最終応答テキスト","finishReason":"stop","status":"completed","model":{"id":"gpt-5-mini-2025-08-07","provider":"openai"}}}

​
error イベント

エラーが発生した時に送信されます。 
data: {"type":"error","payload":{"message":"エラーメッセージ"}}

​
追加の内部イベント

SSE ストリームはエージェントの内部処理をすべて 逐次配信します。上記の基本イベント （config / delta / step / browse-* / complete / error）に加えて、以下も流れます:
カテゴリイベント種別
プラン（HITL）plan・plan-draft-delta・plan-draft-complete・plan-confirmed・plan-rejected
レポート構造（HITL）report-structure-draft-delta・report-structure-draft-complete・report_structure_confirmed・report_structure_rejected
マトリクス（HITL）matrix-structure-draft-delta・matrix-structure-draft-complete・matrix-data-preview・matrix-data-updated・matrix_structure_confirmed・matrix_structure_rejected
ソース要約source-summary-start・source-summary-delta・source-summary-item・source-summary-complete
グラフ抽出graph-start・graph・graph-extraction-entity-delta
ストリームが切断された場合の回収: SSE で途中まで受信したイベント列は agentRun.process として DB に永続化されます。後から GET /turn/list を叩くと、turns[].agentRun.process から同じイベント列を取得できます。参照したソースは turns[].agentRun.publicSourceAgentRuns / privateSourceAgentRuns に入っています。

​
使用例

curl -N -X POST "https://app.snorbe.deskrex.ai/api/v1/agent/run/stream" \
  -H "Authorization: Bearer snorbe_your_api_key_here" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "modelName": "gpt-5-mini-2025-08-07",
    "inputText": "AIエージェントの最新論文を調べて",
    "promptKey": "chat-routing",
    "locale": "ja"
  }'

​
レジュームの使用例

# HITL 確認後に実行を再開
curl -N -X POST "https://app.snorbe.deskrex.ai/api/v1/agent/run/stream/clxxx123" \
  -H "Authorization: Bearer snorbe_your_api_key_here" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"modelName":"gpt-5-mini-2025-08-07"}'

​
エラーレスポンス

ストリーム開始前にエラーが発生した場合は、SSE ではなく通常の JSON レスポンスが返ります。
HTTP ステータス説明
401API キーが無効
400バリデーションエラー
404指定された runId のエージェント実行が存在しない（レジューム時）