关于 Cloud Agents SSE 初始连接行为调整的公告

公告日期：2026 年 8 月 10 日
生效时间：2026 年 8 月 24 日 00:00（UTC+8）
影响范围：Cloud Agents

Cloud Agents 将调整 SSE 接口在初始连接阶段的事件推送行为。现将有关事项公告如下。

调整内容

调整生效后，客户端建立 SSE 连接时若未携带 Last-Event-ID 请求头，服务端将从连接建立时刻的事件流末尾开始推送，仅下发连接建立之后新产生的事件，不再回放该 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 的后续新增事件
`GET /api/v1/cloud/sessions/{session_id}/events` 及 `GET /api/v1/cloud/sessions/{session_id}/threads/{thread_id}/events`（`Accept: text/event-stream`）	是	作为 SSE 使用时，行为与对应的 Stream 接口一致
`Last-Event-ID` 断线续传	否	携带有效 `Last-Event-ID` 时，继续从该事件之后下发，续传规则不变
上述两个 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 接收实时事件、不依赖历史回放的客户端无需调整。

生效安排

本次调整计划于 2026 年 8 月 24 日 00:00（UTC+8） 生效，适用于 Cloud Agents。生效前，线上行为保持不变。如需评估本次调整的影响或获取接入支持，请通过 contact@qoder.com 与我们联系。

​调整内容

​调整原因

​涉及接口

​行为对比示例

​适配指引

​生效安排

调整内容

调整原因

涉及接口

行为对比示例

适配指引

生效安排