メインコンテンツへスキップ
Qoder Cloud Agents は Server-Sent Events (SSE) プロトコルを使用して、Agent のリアルタイム実行状態をクライアントへプッシュします。ポーリングは不要で、一度接続を確立すれば継続的にすべてのイベントを受信できます。

​
接続 URL

GET https://api.qoder.com/api/v1/cloud/sessions/{session_id}/events/stream
リクエストヘッダー: 
Authorization: Bearer $QODER_PAT
Accept: text/event-stream

​
SSE 形式

各イベントは 3 行で構成され、空行で区切られます。 
id: evt_01abc123
event: agent.message
data: {"content":[{"type":"text","text":"Hello, I'm ready to help."}]}
フィールド説明
idイベント一意識別子。再接続に利用
eventイベントタイプ。data の構造を決定
dataJSON 形式のイベントペイロード

​
イベントタイプ一覧

イベントタイプ意味トリガータイミングdata 構造
user.messageユーザーがメッセージ送信クライアントがイベントを POST した後{"content": [{"type":"text","text":"..."}]}
user.interruptユーザーが現在の実行を中断クライアントが中断イベントを送信{}
user.define_outcomeユーザーが期待する成果を定義クライアントが目標を設定{"outcome": "..."}
session.status_runningSession が実行を開始メッセージ受信後に処理開始{"status": "running"}
span.model_request_startモデルリクエスト開始Agent が LLM 呼び出しを発行{"model": "...", "span_id": "..."}
agent.thinkingAgent が思考中モデル推論プロセス中{"thinking": "..."}
agent.messageAgent が返信メッセージ送信モデルがテキストを出力{"content": [{"type":"text","text":"..."}]}
agent.tool_useAgent が組み込みツール呼び出しを発行モデルが組み込みツール呼び出しを決定下記「ツール呼び出し」参照
agent.tool_result組み込みツールの実行結果ツール実行完了後下記「ツール呼び出し」参照
agent.custom_tool_useAgent がクライアントサイドのカスタムツールをリクエストモデルがカスタムツール呼び出しを決定下記「ツール呼び出し」参照
session.status_idleSession がアイドル状態に入る1 ターンの対話が完了下記「status_idle 完整スキーマ」参照
span.model_request_endモデルリクエスト終了LLM 呼び出し完了{"span_id": "...", "usage": {...}}
session.errorSession でエラー発生実行時例外{"error": "...", "code": "..."}
terminatedSession 終了Session がクローズまたはタイムアウト{"reason": "..."}
各イベントの data JSON には、上記の固有フィールド以外に次の共通フィールドも含まれます：id、type、turn_id（user.define_outcome では省略）、session_id、created_at、processed_at、schema_version。

​
典型的なイベントのライフサイクル

1 ターンの完全な対話で、イベントは次の順序でトリガーされます。 
user.message                  ← ユーザー入力
session.status_running    ← 実行開始
span.model_request_start      ← モデルリクエスト
agent.thinking                ← 推論中 (任意)
agent.message                 ← 返信内容 (delta が複数回発生する場合あり)
session.status_idle           ← 完了、または requires_action で一時停止
span.model_request_end        ← モデルリクエストの終了

​
ツール呼び出し

組み込みツール呼び出しは agent.tool_use を使用します。呼び出しが許可されプラットフォームで実行された場合、同じ turn_id 内で対応する agent.tool_result が生成されます。 agent.tool_use の主要フィールド： 
{
  "type": "agent.tool_use",
  "id": "evt_1d4c9b3c873b...",
  "name": "Bash",
  "input": { "command": "...", "description": "..." },
  "evaluated_permission": "allow",
  "turn_id": "turn_...",
  "session_id": "sess_..."
}
このイベントの id は他のイベントと同様に evt_ 接頭辞を使用します。evaluated_permission が ask の場合、このイベントの id を user.tool_confirmation.tool_use_id として使用してください。 agent.tool_result の主要フィールド： 
{
  "type": "agent.tool_result",
  "id": "evt_<32hex>",
  "name": "Bash",
  "content": [{ "type": "text", "text": "..." }],
  "tool_use_id": "toolu_bdrk_01Kj...",
  "turn_id": "turn_...",
  "is_error": false
}
クライアントサイドのカスタムツールは agent.custom_tool_use を使用し、アプリケーション側で処理します： 
{
  "type": "agent.custom_tool_use",
  "id": "evt_1f2e3d4c5b6a...",
  "name": "lookup_order",
  "input": { "order_id": "ord_123" },
  "turn_id": "turn_...",
  "session_id": "sess_..."
}
カスタムツールイベントの id を user.custom_tool_result.custom_tool_use_id として使用してください。 ソート推奨：created_at → タイプ（tool_use が tool_result より前）→ id の 3 段階ソート。id だけでソートしないでください——プラットフォーム生成の tool_result id は辞書順で tool_use id より小さい場合があります。

​
status_idle 完整スキーマ

session.status_idle イベントは status の他に stop_reason、usage、turn_id、session_id を含みます： 
{
  "type": "session.status_idle",
  "id": "evt_840b8dc4b1534e52a2b858bf26b7de00",
  "status": "idle",
  "stop_reason": { "type": "end_turn" },
  "usage": {
    "input_tokens": 23487,
    "output_tokens": 1024,
    "cache_read_input_tokens": 11223,
    "cache_creation_input_tokens": 0
  },
  "turn_id": "turn_...",
  "session_id": "sess_..."
}
ツール確認またはカスタムツール結果を待ってターンが一時停止した場合、stop_reason.type は requires_action となり、event_ids にクライアントの応答が必要なイベントが示されます： 
{
  "type": "session.status_idle",
  "id": "evt_0f1e2d3c4b5a...",
  "status": "idle",
  "stop_reason": {
    "type": "requires_action",
    "event_ids": ["evt_1f2e3d4c5b6a..."]
  },
  "turn_id": "turn_...",
  "session_id": "sess_..."
}
その他の stop_reason.type の値には end_turn、cancel、max_turns、error があり、シナリオに応じて出現します。

​
再接続と after_id

SSE 接続を確立すると、デフォルトではすべての履歴イベントを最初から再生します。差分イベントのみが必要なら after_id パラメータを渡します。 
GET /sessions/{session_id}/events/stream?after_id=evt_01abc123
ブラウザ標準の EventSource は再接続時に Last-Event-ID リクエストヘッダーを自動的に付与し、サーバーはそれをもとに差分イベントを返します。
接続を長時間維持する際は、最後に受信した id をクライアントで記録し、切断時に after_id で復帰することを推奨します。

​
delta_flush_interval_ms

クエリパラメータで agent.message の delta イベントのフラッシュ間隔を制御します。 
GET /sessions/{session_id}/events/stream?delta_flush_interval_ms=100
デフォルト値は 50ms です。値を大きくするとイベント頻度を下げ、クライアントのレンダリング負荷を軽減できます。

​
curl の例

curl -N \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Accept: text/event-stream" \
  "https://api.qoder.com/api/v1/cloud/sessions/sess_abc123/events/stream"

​
JavaScript EventSource の例

const url = new URL('https://api.qoder.com/api/v1/cloud/sessions/sess_abc123/events/stream');
// 差分が必要な場合: url.searchParams.set('after_id', lastEventId);

const es = new EventSource(url, {
  headers: { 'Authorization': `Bearer ${QODER_PAT}` }
});

es.addEventListener('agent.message', (e) => {
  const data = JSON.parse(e.data);
  console.log('Agent:', data.content);
});

es.addEventListener('session.status_idle', (e) => {
  const data = JSON.parse(e.data);
  if (data.stop_reason?.type === 'requires_action') {
    console.log('ターン一時停止、応答が必要:', data.stop_reason.event_ids);
  } else {
    console.log('ターン完了、次の入力を待機');
  }
});

es.addEventListener('session.error', (e) => {
  const data = JSON.parse(e.data);
  console.error('エラー:', data.error);
  es.close();
});

es.onerror = () => {
  console.warn('接続切断、ブラウザが自動再接続します');
};

​
クライアント実装の推奨事項

  1. last event id を記録 — イベント受信のたびに更新し、再接続時の復帰に使用。
  2. delta の連結処理 — agent.message はストリーミング delta で到着する場合があるため、クライアント側で完全なテキストへ連結する必要あり。
  3. terminated を監視 — 受信したら自発的に接続を閉じ、再接続を行わない。
  4. タイムアウト再試行 — 30 秒間イベントがなければ自発的に切断・再接続 (サイレントな切断を回避)。
  5. イベントのフィルタ — 業務上関心のあるイベントタイプのみリッスンし、span レベルのイベントは無視することで処理コストを削減。

​
よくある質問

Q: 接続後に大量の履歴イベントを受信したら? A: after_id パラメータを渡し、最後に処理したイベント ID を指定してください。サーバーはそれ以降のイベントのみを返します。 Q: SSE 接続は自動でクローズしますか? A: Session 終了時にサーバーは terminated イベントを送信した後、接続をクローズします。アイドルタイムアウトは Session 構成によります。 Q: WebSocket で代替できますか? A: 現在は SSE のみサポートしています。SSE は単方向プッシュシナリオに対して軽量で、自然に再接続をサポートします。 Q: delta_flush_interval_ms を大きくしすぎるとイベントが失われますか? A: 失われることはなく、バッチ集約後に送信されるだけです。最終的な内容の完全性には影響しません。

​
次のステップ

Session の開始

Session を作成し、ターン中にイベントを購読する。

権限ポリシー

ツール確認イベントの応答方法を理解する。

Agent ツール

agent.tool_use / agent.custom_tool_use を発行するツール構成。

Outcomes の定義

user.define_outcome で成功基準を設定する。