Skip to main content
Qoder Cloud Agents 通过 Server-Sent Events (SSE) 流式输出 Session 公开事件。

​
连接 URL

请求头：
默认情况下，Agent 响应会在生成完成后，以完整公开事件（例如 agent.message）的形式写入 Session 事件历史并通过 stream 输出。下文将这种完整事件称为 buffered 事件。 Stream endpoint 支持使用 Last-Event-ID header 断线重连。对于普通 buffered 事件，stream 从该 ID 之后继续；在途 event delta 的特殊行为见下文。 使用 event_deltas[] 可在当前 stream 连接中增量接收 Agent 响应。重复传入该参数可同时请求两种支持的事件类型：
该选项只对当前 stream 连接生效，不会影响同一 Session 的其它连接。不传 event_deltas[] 时，连接只会在响应完成后收到完整事件。Thread event stream 不支持该参数。

​
SSE 格式

每条事件使用标准 SSE 字段：
服务端可能发送 heartbeat comment 以保持连接。

​
Event Delta

agent.message 的增量输出以 event_start 开始，随后输出一个或多个 event_delta：
agent.thinking 的增量输出只有开始事件，不会输出 event_delta：
对于同一个 message 或 thinking 事件，SSE id:、event_start.event.id、每个 event_delta.event_id 以及后续 buffered 事件的 id 完全相同。同时请求两种事件类型时，典型顺序如下：
Event delta 帧的 JSON payload 不包含顶层 id 或 processed_at 字段，也不会出现在事件 list/history 响应中。buffered agent.message 是权威结果，agent.thinking 不会暴露思考内容。

​
Event Delta 期间重连

断线重连时使用 SSE Last-Event-ID header。具体行为取决于游标位置，以及当前 message 是否仍在生成：
  1. 游标指向当前 event_start 之前的事件，且 message 仍在生成。 Stream 会重新输出该 message 的 event_start 和已保留的历史 event_delta，然后继续输出新 delta。
  2. 游标等于当前 event_start.event.id，且 message 仍在生成。 该 message 已经输出过的历史 delta 不会重放；stream 只输出重连后新生成的 delta，随后输出 buffered 最终事件。
  3. Message 已经生成完成。 该 message 的历史 delta 不再重放。从更早的 buffered 事件重连时，只会收到最终 agent.message；如果使用该最终 message 的 ID 重连，则从它之后继续。
同一个增量事件的所有帧使用相同 ID。如果客户端在断线后需要完整重建仍在生成的事件，应将游标回退到该事件 event_start 之前最近的 buffered 事件 ID，清空或去重本地的部分状态，并重新处理服务端返回的 event_start 和 event_delta。

​
常见事件流

并非每一轮都会包含全部事件。Managed-agent Session 还可能产生 session.thread_created、session.thread_status_running、agent.thread_message_sent、agent.thread_message_received 等 thread 事件。

​
模型请求 span

span.model_request_start 包含 id、processed_at 和 type。与之配对的 span.model_request_end 包含 id、is_error、model_request_start_id、processed_at 和 type，其中 model_request_start_id 等于对应 start 事件的 id。
说明：公开的 agent.thinking 事件 payload 只包含 id、processed_at、type 三个字段，思考内容不对外公开——把该事件当作”Agent 暂停推理”的标记即可。其它若干 agent.* 事件也可能省略 processed_at，解析时请将其视为可选字段。

​
连接生命周期

  • session.status_idle 表示当前 turn 结束，连接应当保持，等待下一轮。
  • session.status_terminated 和 session.deleted 是终态事件——客户端应停止重连，不会再有更多事件。
  • session.status_rescheduled 是临时信号，连接可能短暂断开，运行时恢复后会自动重连。
  • 网络中断时使用 Last-Event-ID header 重连；在途增量事件的特殊处理见 Event Delta 期间重连。

​
工具响应

当事件流产生需要确认的 agent.tool_use 时，向 POST /api/v1/cloud/sessions/{session_id}/events 发送 user.tool_confirmation，并使用工具事件 ID：
当事件流产生 agent.custom_tool_use 时，由客户端执行自定义工具，并发送 user.custom_tool_result。

​
事件历史

历史事件和分页请使用 list endpoint：
列表响应使用 data 和 next_page。详见 列出事件 和 Session 数据结构。