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

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://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": "..."}
user.interruptユーザーが現在の実行を中断クライアントが中断イベントを送信{}
user.define_outcomeユーザーが期待する成果を定義クライアントが目標を設定{"outcome": "..."}
session.status_runningSession が実行を開始メッセージ受信後に処理開始{"status": "running"}
span.model_request_startモデルリクエスト開始Agent が LLM 呼び出しを発行{"model": "...", "span_id": "..."}
agent.thinkingAgent が思考中モデル推論プロセス中{"content": "..."}
agent.messageAgent が返信メッセージ送信モデルがテキストを出力{"content": [{"type":"text","text":"..."}]}
agent.tool_useAgent が発行したツール呼び出し（Bash/Read/Write/Edit/Glob/Grep/WebFetch/WebSearch）モデルがツール呼び出しを決定下記「ツール呼び出しペア」参照
agent.tool_resultツール実行結果、tool_use_id で tool_use とペアリングツール実行完了後下記「ツール呼び出しペア」参照
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_running    ← 実行開始
span.model_request_start      ← モデルリクエスト
agent.thinking                ← 推論中 (任意)
agent.message                 ← 返信内容 (delta が複数回発生する場合あり)
span.model_request_end        ← モデル完了
session.status_idle           ← アイドル、次のターンを待機

​
ツール呼び出しペア（pair）

各 agent.tool_use には同じ turn_id の agent.tool_result が必ずペアとなり、tool_use_id で関連付けられます。 agent.tool_use の主要フィールド： 
{
  "type": "agent.tool_use",
  "id": "toolu_bdrk_01Kj...",
  "name": "Bash",
  "input": { "command": "...", "description": "..." },
  "tool_use_id": "toolu_bdrk_01Kj...",
  "turn_id": "turn_...",
  "session_id": "sess_...",
  "requires_confirmation": false
}
注意：このイベントの id は evt_ プレフィックスではなく、外部モデル形式 toolu_bdrk_<24> です。name は先頭大文字です。 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
}
ソート推奨：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 の現在の観測値は 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"
after_id を伴う差分接続: 
curl -N \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Accept: text/event-stream" \
  "https://api.qoder.com/api/v1/cloud/sessions/sess_abc123/events/stream?after_id=evt_01abc123"

​
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', () => {
  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: 失われることはなく、バッチ集約後に送信されるだけです。最終的な内容の完全性には影響しません。