Cloud Agents SSE 初回接続動作変更のお知らせ

公告日： 2026 年 8 月 10 日
適用開始日時： 2026 年 8 月 24 日 00:00（UTC+8）
対象： Cloud Agents

Cloud Agents は、クライアントが SSE エンドポイントへ初回接続する際のイベント配信動作を変更します。

変更内容

変更の適用後、クライアントが Last-Event-ID リクエストヘッダーを指定せずに SSE 接続を確立した場合、サーバーは接続時点のイベントストリーム末尾から配信を開始します。接続確立後に新しく生成されたイベントのみを配信し、Session または Thread にすでに存在する履歴イベントは再送しません。この変更は、イベントデータやイベント形式には影響しません。履歴イベントは引き続き List Events エンドポイントからページ単位で取得できます。Last-Event-ID を使用した再接続の動作も変更されません。

変更理由

現在、Last-Event-ID を指定しない新規接続では、すべての履歴イベントを再送した後に新しいイベントを配信します。Session に多くのイベントが蓄積されている場合、接続のたびに処理済みの大量のデータが繰り返し転送されます。そのため、クライアント側で解析と重複排除が必要になり、再送イベントとリアルタイムイベントを区別することも困難です。変更後は、用途ごとの役割が明確になります。SSE はリアルタイムイベントを配信し、List Events は履歴イベントを取得し、Last-Event-ID は再接続位置を指定します。これにより、不要なデータ転送がなくなります。

対象エンドポイント

エンドポイントまたは機能	変更	内容
`GET /api/v1/cloud/sessions/{session_id}/events/stream`	あり	`Last-Event-ID` がない場合、接続時点の Session イベントストリーム末尾から開始し、以降の新規イベントのみを配信します
`GET /api/v1/cloud/sessions/{session_id}/threads/{thread_id}/stream`	あり	`Last-Event-ID` がない場合、接続時点の指定 Thread のイベントストリーム末尾から開始し、その Thread の以降の新規イベントのみを配信します
`Accept: text/event-stream` を指定した `GET /api/v1/cloud/sessions/{session_id}/events` および `GET /api/v1/cloud/sessions/{session_id}/threads/{thread_id}/events`	あり	SSE として使用する場合、対応する Stream エンドポイントと同じ動作になります
`Last-Event-ID` を使用した再接続	なし	有効な `Last-Event-ID` がある場合、従来どおりそのイベントの次から配信を再開します
上記 2 つの List Events エンドポイントへの JSON クエリ	なし	保存済みの公開イベントを引き続きページ単位で取得できます
`POST /api/v1/cloud/sessions/{session_id}/events`	なし	リクエストおよびレスポンスの仕様は変更されません

動作例

ある Session に接続前から 4 件のイベントが存在し、接続後にさらに 4 件のイベントが生成される場合を考えます。以下ではイベント ID を短縮しています。

接続前から存在するイベント：
evt_00l82zhn…ls0e   session.status_running
evt_00l82zhmp…c9t4  user.message
evt_00l82zhoi…pskrt agent.message
evt_00l830291…ct2zo session.status_idle

接続後に生成されたイベント：
evt_00l830465…7yh4u session.status_running
evt_00l83045n…jlw6i user.message
evt_00l83046h…r1c3b agent.message
evt_00l830yjc…k2tb  session.status_idle

変更前は、Last-Event-ID を指定しない接続に 8 件すべてのイベントが配信されます。変更後は、接続後に生成された 4 件のみが配信されます。最新のイベントを含め、履歴イベントは一切再送されません。有効な Last-Event-ID を指定して再接続した場合は、従来どおり、そのイベントの次から配信を再開します。既存の接続はこの変更の影響を受けません。新しい動作は、適用開始日時以降に確立または再確立された接続にのみ適用されます。

移行ガイド

次のいずれかに該当するクライアントは、適用開始日時までに対応してください。

新しい SSE 接続を使用して履歴イベントを取得している。
メッセージ送信または Agent 実行の開始後に、カーソルなしの SSE 接続を確立し、履歴の再送によってイベントを受信している。
切断後に Last-Event-ID を指定せずに再接続し、履歴の再送によって切断中のイベントを復旧している。

次の方法で接続してください。

List Events のページネーションを使用して履歴イベントを取得します。
SSE でリアルタイムイベントを受信し、処理に成功したら最新のイベント ID を記録します。
接続が中断した場合、その ID を Last-Event-ID ヘッダーに指定して再接続し、イベント ID に基づいて処理を冪等にします。
ある操作で生成されるリアルタイムイベントをすべて受信する必要がある場合は、その操作を開始する前に SSE 接続が確立されていることを確認します。

SSE をリアルタイムイベントの受信だけに使用し、履歴の再送に依存していないクライアントは対応不要です。

適用開始日時

この変更は、Cloud Agents を対象として 2026 年 8 月 24 日 00:00（UTC+8） に適用されます。それまでは現在の動作が維持されます。影響の確認や接続方法に関するサポートが必要な場合は、contact@qoder.com までお問い合わせください。

​変更内容

​変更理由

​対象エンドポイント

​動作例

​移行ガイド

​適用開始日時

変更内容

変更理由

対象エンドポイント

動作例

移行ガイド

適用開始日時