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

Documentation Index

Fetch the complete documentation index at: https://docs.qoder.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
接続 URL

GET https://openapi.qoder.sh/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":"Hello, I'm ready to help."}
フィールド説明
idイベント一意識別子。再接続に利用
eventイベントタイプ。data の構造を決定
dataJSON 形式のイベントペイロード

​
イベントタイプ一覧

イベントタイプ意味トリガータイミングdata 構造
user.messageユーザーがメッセージ送信クライアントがイベントを POST した後{"content": "..."}
user.interruptユーザーが現在の実行を中断クライアントが中断イベントを送信{}
user.define_outcomeユーザーが期待する成果を定義クライアントが目標を設定{"outcome": "..."}
session.status_rescheduledSession が実行スケジュールに入るメッセージ受信後に処理開始{"status": "rescheduled"}
span.model_request_startモデルリクエスト開始Agent が LLM 呼び出しを発行{"model": "...", "span_id": "..."}
agent.thinkingAgent が思考中モデル推論プロセス中{"content": "..."}
agent.messageAgent が返信メッセージ送信モデルがテキストを出力{"content": "...", "delta": true}
session.status_idleSession がアイドル状態に入る1 ターンの対話が完了{"status": "idle"}
span.model_request_endモデルリクエスト終了LLM 呼び出し完了{"span_id": "...", "usage": {...}}
session.errorSession でエラー発生実行時例外{"error": "...", "code": "..."}
terminatedSession 終了Session がクローズまたはタイムアウト{"reason": "..."}

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

1 ターンの完全な対話で、イベントは次の順序でトリガーされます。 
user.message                  ← ユーザー入力
session.status_rescheduled    ← スケジュール開始
span.model_request_start      ← モデルリクエスト
agent.thinking                ← 推論中 (任意)
agent.message                 ← 返信内容 (delta が複数回発生する場合あり)
span.model_request_end        ← モデル完了
session.status_idle           ← アイドル、次のターンを待機

​
再接続と 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://openapi.qoder.sh/api/v1/cloud/sessions/ses_abc123/events/stream"
after_id を伴う差分接続: 
curl -N \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Accept: text/event-stream" \
  "https://openapi.qoder.sh/api/v1/cloud/sessions/ses_abc123/events/stream?after_id=evt_01abc123"

​
JavaScript EventSource の例

const url = new URL('https://openapi.qoder.sh/api/v1/cloud/sessions/ses_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', () => {
  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: 失われることはなく、バッチ集約後に送信されるだけです。最終的な内容の完全性には影響しません。