> ## 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.

# SSE 事件流

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

## 连接 URL

```text theme={null}
GET https://api.qoder.com/api/v1/cloud/sessions/{session_id}/events/stream
```

请求头：

```text theme={null}
Authorization: Bearer $QODER_PAT
Accept: text/event-stream
```

Stream endpoint 支持 `Last-Event-ID` header 进行断线重连——传入上次收到的事件 ID 后，流从该事件之后开始重放。事件类型 query filter 当前不支持。

增量流式通过创建 Session 时的字段开启：

```json theme={null}
{
  "incremental_streaming_enabled": true
}
```

不能通过某次 stream 连接的 query 参数或 header 临时开启。开启后，同一组 stream 和 list 接口会在最终完整事件之外额外暴露增量事件。快速验证流程见 [增量流式](/zh/cloud-agents/incremental-streaming)。

## SSE 格式

每条事件使用标准 SSE 字段：

```text theme={null}
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 以保持连接。

## 常见事件流

```text theme={null}
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 的增量序列如下：

```text theme={null}
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` 中，例如：

```json theme={null}
{
  "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：

```json theme={null}
{
  "events": [
    {
      "type": "user.tool_confirmation",
      "tool_use_id": "evt_01JZ6Q3FB6SG8F7J1M2N",
      "result": "allow"
    }
  ]
}
```

当事件流产生 `agent.custom_tool_use` 时，由客户端执行自定义工具，并发送 `user.custom_tool_result`。

## 事件历史

历史事件和分页请使用 list endpoint：

```bash theme={null}
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`。详见 [列出事件](/zh/cloud-agents/api/sessions/list-events) 和 [Session 数据结构](/zh/cloud-agents/api/sessions/schemas#公开事件类型)。