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

# 订阅 Session Event Stream

> 通过 SSE 订阅 Forward Session 事件流。

`GET /api/v1/forward/sessions/{session_id}/events/stream`

以 Server-Sent Events 方式推送 Session 事件流。需要流式输出的新集成应使用 `event_deltas[]` 订阅。

## 请求头

| Header        | 是否必填 | 说明                  |
| ------------- | ---- | ------------------- |
| Authorization | 是    | `Bearer <PAT>`      |
| Accept        | 是    | `text/event-stream` |
| Last-Event-ID | 否    | 从该 Event ID 之后恢复订阅。 |

## 路径参数

| 参数          | 类型     | 是否必填 | 说明          |
| ----------- | ------ | ---- | ----------- |
| session\_id | string | 是    | Session ID。 |

## 查询参数

| 参数                   | 类型      | 是否必填 | 默认值    | 说明                                                                                                                                                                 |
| -------------------- | ------- | ---- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| event\_deltas\[]     | string  | 否    | -      | 订阅指定公共事件类型的流式增量事件。支持重复参数。允许值：`agent.message`、`agent.thinking`。详见 [Event delta streaming](/cloud-agents/api/forward/sessions/data-structure#event-delta-streaming)。 |
| include\_tool\_calls | boolean | 否    | `true` | 是否包含工具调用事件。                                                                                                                                                        |
| include\_thinking    | boolean | 否    | `true` | 是否包含 thinking 事件。                                                                                                                                                  |

## 示例请求

```bash theme={null}
curl -s -X GET 'https://api.qoder.com/api/v1/forward/sessions/sess_xxx/events/stream' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Accept: text/event-stream"
```

订阅文本与 thinking 的流式增量事件：

```bash theme={null}
curl -N -G 'https://api.qoder.com/api/v1/forward/sessions/sess_xxx/events/stream' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Accept: text/event-stream" \
  --data-urlencode 'event_deltas[]=agent.message' \
  --data-urlencode 'event_deltas[]=agent.thinking'
```

## 示例响应

**HTTP 200 OK**

```text theme={null}
id: evt_xxx
event: agent.message
data: {"id":"evt_xxx","type":"agent.message","session_id":"sess_xxx","content":[{"type":"text","text":"Here is the analysis result."}],"processed_at":"2026-06-22T11:00:03Z"}
```

## Event delta streaming 示例

```text theme={null}
id: evt_xxx
event: event_start
data: {"id":"evt_xxx","type":"event_start","session_id":"sess_xxx","event":{"id":"evt_xxx","type":"agent.message"}}

id: evt_xxx
event: event_delta
data: {"id":"evt_xxx","type":"event_delta","session_id":"sess_xxx","event_id":"evt_xxx","delta":{"type":"content_delta","index":0,"content":{"type":"text","text":"Here"}}}
```

## 响应字段

| 字段    | 类型     | 说明                                                                                                                                                                    |
| ----- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id    | string | SSE event ID，等于 Event ID。                                                                                                                                             |
| event | string | Event 类型。                                                                                                                                                             |
| data  | object | 标准公共事件遵循 List Session Events 所记录的 Event `type` 矩阵；event delta 流式帧详见 [Event delta streaming](/cloud-agents/api/forward/sessions/data-structure#event-delta-streaming)。 |

## 错误

| HTTP | Type                   | Code                      | 触发条件                           |
| ---- | ---------------------- | ------------------------- | ------------------------------ |
| 404  | `not_found_error`      | `not_found_error`         | `Last-Event-ID` 不属于当前 Session。 |
| 404  | `not_found_error`      | `session_not_found`       | Session 不存在。                   |
| 401  | `authentication_error` | `authentication_required` | PAT 无效或已过期。                    |

## 注意事项

* `event_deltas[]` 是推荐的流式输出方式；未提供该参数时仅返回标准公共事件。
* `incremental_streaming_enabled` 是保留用于向后兼容的旧版流式开关。若 Session 创建时设置了 `incremental_streaming_enabled=true`，则该 Session 使用旧版流式，`event_deltas[]` 不会在该 Session 上生效。
* 未知 Event 类型在可用时作为仅包含信封的事件转发。
* `include_thinking=false` 过滤 thinking 事件、旧版 thinking delta 以及新流式 `agent.thinking` event start 信号和 `delta.content.type=thinking` 片段。
* `include_tool_calls=false` 过滤工具调用事件和旧版工具 input/output delta。

## 相关

<CardGroup cols={2}>
  <Card title="创建 Session" icon="plus" href="/cloud-agents/api/forward/sessions/create" />

  <Card title="列出 Session Events" icon="list" href="/cloud-agents/api/forward/sessions/list-events" />
</CardGroup>