Skip to main content
生成系エンドポイントは、完全なレスポンスを 1 回で返すか、Server-Sent Events（SSE）ストリームで返します。どちらになるかは、リクエストごとに response_mode で指定します。通常はストリーミングモードを選びます。返信を生成と同時に描画でき、長い実行が途中で打ち切られることもありません。

​
レスポンスモードの選択

blocking（ブロッキングモード）は、生成完了後に JSON ボディを 1 回で返します。短い非対話型の呼び出しでは統合が簡単です。ただし長い生成には中断のリスクがあります。デプロイの前段にあるリバースプロキシやロードバランサーは、タイムアウト時間内にレスポンスを受け取れないと接続を切断することがあります。 streaming（ストリーミングモード）は、返信を SSE イベントとして届けます。ユーザーに見せる処理と長時間の実行には、こちらを使ってください。
Agent アプリはストリーミングモードのみ対応です。

​
ストリームの解析

各イベントは 1 行の data: として届き、1 つの JSON オブジェクトを含みます。イベントの終わりは空行です。 event フィールドを読んで処理内容を判断し、data: で始まらない行はスキップします。キープアライブの ping は 10 秒ごとに届き、data: ペイロードのない event: ping 行だけで構成されます。
実際の通信では、ストリームは次のようになります。

​
イベントタイプごとの振り分け

届くイベントはアプリタイプによって異なります。イベントの一覧は チャットメッセージを送信、ワークフローを実行、完了メッセージを送信 の各イベント表を参照してください。 最低限の典型的な処理は次のとおりです。
  1. 返信チャンクを順番に連結します。
    • チャットボットと Chatflow アプリでは message イベント
    • Agent アプリでは agent_message イベント
  2. 正しい終端イベントで締めくくります。
    • チャットボットと Agent アプリは message_end
    • Chatflow アプリは message_end と workflow_finished（この順で両方届きます）
    • Workflow アプリは workflow_finished
  3. error イベントを呼び出し元に伝えます。

​
ストリーム中のエラー処理

ストリームが開いた後に失敗しても、HTTP ステータスは変わりません。接続は 200 のままです。失敗がどう現れるかは、発生した場所によって異なります。
  • ワークフローノードの失敗は、status: "failed" を持つ node_finished と workflow_finished イベントとして届きます。
  • それ以外の失敗は、status、code、message を持つ error イベントでストリームを終了させます。
どちらも処理し、いずれの場合もそのリクエストは終了とみなしてください。

​
切断後の再接続

重要な識別子は 2 つあり、混同しやすいものです。 どちらもストリーム自体から取得できます。error 以外のすべてのイベントは task_id を持ち、ワークフローとノードのイベントは workflow_run_id も持ちます。workflow_run_id は届いた時点ですぐ保存してください。接続が途中で切れた場合、結果確認の唯一の手がかりになります。 ワークフローが背後にある実行（Workflow アプリと Chatflow アプリ）では、接続が途中で切れた場合、保存した workflow_run_id を使って ワークフロー実行詳細を取得 で実行結果を確認してください。 それ以外の返信には再開用のエンドポイントがありません。返信の途中で接続が切れた場合は、新しいリクエストを送ってください。チャット系アプリでは、会話履歴メッセージ一覧を取得 で会話に保存された内容を確認できます。

​
接続の維持

クライアントの読み取りタイムアウトは、10 秒の ping 間隔より十分長く設定してください。イベント間のアイドル時間で接続が切れるのを防げます。ping 自体はスキップする以外の処理は不要です。