跳转到主要内容
Qoder Cloud Agents 通过 Server-Sent Events (SSE) 流式输出 Session 公开事件。

​
连接 URL

GET https://api.qoder.com/api/v1/cloud/sessions/{session_id}/events/stream
请求头： 
Authorization: Bearer $QODER_PAT
Accept: text/event-stream
Stream endpoint 支持 Last-Event-ID header 进行断线重连——传入上次收到的事件 ID 后，流从该事件之后开始重放。事件类型 query filter 当前不支持。 增量流式通过创建 Session 时的字段开启： 
{
  "incremental_streaming_enabled": true
}
不能通过某次 stream 连接的 query 参数或 header 临时开启。开启后，同一组 stream 和 list 接口会在最终完整事件之外额外暴露增量事件。快速验证流程见 增量流式。

​
SSE 格式

每条事件使用标准 SSE 字段： 
id: evt_019e392c0d787cfaa21bda98e06cd913
event: agent.message
data: {"id":"evt_019e392c0d787cfaa21bda98e06cd913","type":"agent.message","content":[{"type":"text","text":"Hello"}],"processed_at":"2026-05-18T03:40:48.888851795Z"}
服务端可能发送 heartbeat comment 以保持连接。

​
常见事件流

user.message
session.status_running
span.model_request_start
agent.thinking
agent.tool_use
agent.tool_result
agent.message
span.model_request_end
session.status_idle
并非每一轮都会包含全部事件。Managed-agent Session 还可能产生 session.thread_created、session.thread_status_running、agent.thread_message_sent、agent.thread_message_received 等 thread 事件。
说明：公开的 agent.thinking 事件 payload 只包含 id、processed_at、type 三个字段，思考内容不对外公开——把该事件当作”Agent 暂停推理”的标记即可。其它若干 agent.* 事件也可能省略 processed_at，解析时请将其视为可选字段。

​
增量事件

当 incremental_streaming_enabled 为 true 时，客户端可能收到以下顶层增量事件类型： agent.message_start、agent.content_block_start、agent.content_block_delta、agent.content_block_stop、agent.message_delta 和 agent.message_stop。 一条典型 assistant message 的增量序列如下： 
agent.message_start
agent.content_block_start
agent.content_block_delta
agent.content_block_stop
agent.message_delta
agent.message_stop
文本片段、thinking 片段、工具入参片段等 delta 概念都承载在 agent.content_block_delta.delta.type 中，例如： 
{
  "type": "agent.content_block_delta",
  "index": 0,
  "delta": {
    "type": "text_delta",
    "text": "Hello"
  }
}
当前实现暂不流式输出工具执行结果片段；工具结果仍以完整 agent.tool_result 事件返回。

​
连接生命周期

  • session.status_idle 表示当前 turn 结束，连接应当保持，等待下一轮。
  • session.status_terminated 和 session.deleted 是终态事件——客户端应停止重连，不会再有更多事件。
  • session.status_rescheduled 是临时信号，连接可能短暂断开，运行时恢复后会自动重连。
  • 网络中断时使用 Last-Event-ID header 携带最后一次收到的事件 ID 重连，服务器会从该 ID 之后开始重放。

​
工具响应

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

​
事件历史

历史事件和分页请使用 list endpoint： 
curl -s "https://api.qoder.com/api/v1/cloud/sessions/$SESSION_ID/events?limit=20&order=desc" \
  -H "Authorization: Bearer $QODER_PAT"
列表响应使用 data 和 next_page。详见 列出事件 和 Session 数据结构。