> ## 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 数据结构

> 适用于 Forward Session API 的 Session 与 Event 相关数据结构说明。

## Session 对象

创建、获取、列出、更新和归档 Session 的接口都会返回该对象。

```
{
  "id": "sess_xxx",
  "type": "session",
  "identity_id": "idn_xxx",
  "template": {
    "id": "tmpl_support",
    "type": "template",
    "name": "客服助手",
    "model": "ultimate",
    "version": 3
  },
  "source_type": "api",
  "status": "idle",
  "title": "客户支持会话",
  "incremental_streaming_enabled": true,
  "metadata": {
    "source": "web",
    "biz_id": "ticket_123"
  },
  "config": {
    "environment_variables": {
      "API_KEY": "sk-xxx"
    }
  },
  "stats": {
    "active_seconds": 30,
    "duration_seconds": 3600
  },
  "usage": {
    "credits": 12.5
  },
  "archived_at": null,
  "created_at": "2026-06-22T10:00:00Z",
  "updated_at": "2026-06-22T11:00:00Z"
}
```

| 字段                              | 类型             | 必返 | 说明                                                                                                   |
| ------------------------------- | -------------- | -- | ---------------------------------------------------------------------------------------------------- |
| `id`                            | string         | 是  | `sess_`\ 前缀的 Session ID。                                                                             |
| `type`                          | string         | 是  | 固定为\ `"session"`。                                                                                    |
| `identity_id`                   | string         | 是  | Forward Identity ID，表示该 Session 归属的终端用户身份。                                                           |
| `template`                      | object         | 是  | Forward Template 摘要，字段见 [Template 摘要](#template-摘要)。                                                 |
| `source_type`                   | string         | 是  | Session 来源：`api`、`im`\ 或\ `schedule`。                                                                |
| `status`                        | string         | 是  | Session 运行状态：`idle`、`running`、`rescheduling`、`canceling`\ 或\ `terminated`。归档状态通过\ `archived_at`\ 表达。 |
| `title`                         | string         | 是  | Session 标题。                                                                                          |
| `incremental_streaming_enabled` | boolean        | 是  | 是否为该 Session 开启增量流式事件。创建时省略则为\ `false`，创建后不支持修改。                                                     |
| `metadata`                      | object         | 否  | 调用方业务元数据。                                                                                            |
| `config`                        | object         | 否  | Session 配置；未传入时可能省略。                                                                                 |
| `config.environment_variables`  | object         | 否  | 会话级环境变量，key-value 形式。                                                                                |
| `stats`                         | object         | 否  | Session 统计信息，字段见 [Session stats](#session-stats)。                                                    |
| `usage`                         | object         | 否  | 用量信息；相关计费模块未启用时可能省略。                                                                                 |
| `usage.credits`                 | number         | 否  | Credit 消耗。                                                                                           |
| `archived_at`                   | string \| null | 是  | 归档时间，未归档时为\ `null`。                                                                                  |
| `created_at`                    | string         | 是  | 创建时间，RFC 3339 格式。                                                                                    |
| `updated_at`                    | string         | 是  | 最近更新时间，RFC 3339 格式。                                                                                  |

## Template 摘要

| 字段        | 类型      | 必返 | 说明                     |
| --------- | ------- | -- | ---------------------- |
| `id`      | string  | 是  | Forward Template ID。   |
| `type`    | string  | 是  | 固定为\ `"template"`。     |
| `name`    | string  | 是  | Template 名称。           |
| `model`   | string  | 是  | Template 使用的模型档位或模型标识。 |
| `version` | integer | 是  | Template 版本号。          |

## Session stats

| 字段                 | 类型      | 必返 | 说明                                   |
| ------------------ | ------- | -- | ------------------------------------ |
| `active_seconds`   | integer | 否  | 活跃处理时长，单位秒；新 Session 通常为\ `0`。       |
| `duration_seconds` | integer | 否  | Session 持续时长，单位秒；新 Session 通常为\ `0`。 |

## Event 对象

接口返回的 Event 是按 `type` 变化的 JSON 对象。所有返回 Event 都包含通用字段，不同事件类型会携带不同的 payload 字段。

```
{
  "id": "evt_xxx",
  "type": "agent.message",
  "session_id": "sess_xxx",
  "content": [
    {
      "type": "text",
      "text": "这是分析结果。"
    }
  ],
  "processed_at": "2026-06-22T11:00:03Z"
}
```

| 字段             | 类型     | 必返 | 说明                                               |
| -------------- | ------ | -- | ------------------------------------------------ |
| `id`           | string | 是  | `evt_`\ 前缀的 Event ID。                            |
| `type`         | string | 是  | Event 类型。                                        |
| `session_id`   | string | 是  | Event 所属 Session ID。                             |
| `processed_at` | string | 否  | 事件被处理的时间，RFC 3339 格式。部分 agent 生成事件或增量事件可能不包含该字段。 |

按事件类型允许出现的 payload 字段如下。表中不重复列出通用字段 `id`、`type`、`session_id` 和 `processed_at`。

| Event 类型                    | 允许字段                                                    |
| --------------------------- | ------------------------------------------------------- |
| `user.message`              | `content`                                               |
| `user.interrupt`            | 无                                                       |
| `user.tool_confirmation`    | `tool_use_id`、`result`、`deny_message`                   |
| `user.tool_result`          | `tool_use_id`、`content`、`is_error`                      |
| `user.custom_tool_result`   | `custom_tool_use_id`、`content`、`is_error`               |
| `user.define_outcome`       | `description`、`rubric`、`outcome_id`、`max_iterations`    |
| `system.message`            | `content`                                               |
| `agent.message`             | `content`                                               |
| `agent.thinking`            | 无                                                       |
| `agent.message_start`       | `message_id`、`message`                                  |
| `agent.content_block_start` | `message_id`、`index`、`content_block`                    |
| `agent.content_block_delta` | `message_id`、`index`、`delta`                            |
| `agent.content_block_stop`  | `message_id`、`index`                                    |
| `agent.message_delta`       | `message_id`、`delta`、`usage`                            |
| `agent.message_stop`        | `message_id`                                            |
| `agent.tool_use`            | `name`、`input`、`evaluated_permission`                   |
| `agent.tool_result`         | `tool_use_id`、`content`、`is_error`                      |
| `agent.custom_tool_use`     | `name`、`input`                                          |
| `agent.mcp_tool_use`        | `mcp_server_name`、`name`、`input`、`evaluated_permission` |
| `agent.mcp_tool_result`     | `mcp_tool_use_id`、`content`、`is_error`                  |
| `agent.artifact_delivered`  | `file_id`、`original_filename`、`size`、`content_type`     |
| `session.status_running`    | 无                                                       |
| `session.status_idle`       | `stop_reason`                                           |
| `session.status_terminated` | 无                                                       |
| `session.error`             | `error`                                                 |
| `session.updated`           | `agent`、`metadata`、`title`                              |

## 客户端可发送事件类型

`POST /api/v1/forward/sessions/{session_id}/events` 只接受以下事件类型。

| 类型                        | 必填字段                   | 说明                                                                          |
| ------------------------- | ---------------------- | --------------------------------------------------------------------------- |
| `user.message`            | `content`              | 用户消息。`content`\ 必须是非空 content block 数组，支持\ `text`、`image`、`document`\ 等块类型。 |
| `user.interrupt`          | 无                      | 请求中断当前处理。                                                                   |
| `user.tool_confirmation`  | `tool_use_id`、`result` | 工具调用确认。`result`\ 为\ `allow`\ 或\ `deny`；拒绝时可传\ `deny_message`。               |
| `user.tool_result`        | `tool_use_id`          | 返回内置工具结果；`content`\ 和\ `is_error`\ 可选。                                      |
| `user.custom_tool_result` | `custom_tool_use_id`   | 返回客户端自定义工具结果；`content`\ 和\ `is_error`\ 可选。                                  |
| `user.define_outcome`     | `description`、`rubric` | 定义期望结果和评判标准；`max_iterations`\ 可选。                                           |

`system.message` 是公开 Event 类型，但不作为 Forward 客户端写入事件开放。

## 公开事件类型

查询历史和订阅 SSE 事件流时，可能收到以下公开事件类型：

`user.message`、`user.interrupt`、`user.tool_confirmation`、`user.tool_result`、`user.custom_tool_result`、`user.define_outcome`、`system.message`、`agent.message`、`agent.thinking`、`agent.message_start`、`agent.content_block_start`、`agent.content_block_delta`、`agent.content_block_stop`、`agent.message_delta`、`agent.message_stop`、`agent.tool_use`、`agent.tool_result`、`agent.custom_tool_use`、`agent.mcp_tool_use`、`agent.mcp_tool_result`、`agent.artifact_delivered`、`session.status_running`、`session.status_idle`、`session.status_terminated`、`session.error` 和 `session.updated`。

## 增量流式事件

是否暴露增量流式事件由创建 Session 时的 `incremental_streaming_enabled` 字段控制，不通过查询历史或订阅 SSE 的请求参数控制：

* `true`：事件流会在最终完整 `agent.message` 之前返回 assistant 输出片段；历史查询也会返回同一批增量事件。

* `false` 或省略：保持普通模式，只返回完整公开事件，不返回增量事件。

开启增量流式后，最终完整的 `agent.message` 仍会返回。客户端可使用增量事件做即时展示，再以最终 `agent.message` 作为持久化或展示校准结果。

顶层增量事件类型只有以下 6 种：

| 事件类型                        | 关键字段                                 | 说明                                                       |
| --------------------------- | ------------------------------------ | -------------------------------------------------------- |
| `agent.message_start`       | `message_id`、`message`               | 开始一条 assistant message。                                  |
| `agent.content_block_start` | `message_id`、`index`、`content_block` | 开始一个 content block，例如 text、thinking 或 tool use。          |
| `agent.content_block_delta` | `message_id`、`index`、`delta`         | 承载\ `index`\ 对应 content block 的增量片段。                     |
| `agent.content_block_stop`  | `message_id`、`index`                 | 结束\ `index`\ 对应 content block。                           |
| `agent.message_delta`       | `message_id`、`delta`、`usage`         | 承载 message 级增量，例如\ `stop_reason`、`stop_sequence`\ 或用量信息。 |
| `agent.message_stop`        | `message_id`                         | 结束一条 assistant message。                                  |

`text_delta`、`thinking_delta`、`signature_delta`、`input_json_delta` 和 `tool_output_delta` 不是顶层 Event 类型，只会作为 `agent.content_block_delta.delta.type` 出现。

| `delta.type`        | 字段             | 说明                                            |
| ------------------- | -------------- | --------------------------------------------- |
| `text_delta`        | `text`         | 文本输出片段，客户端可追加\ `delta.text`\ 重建文本。            |
| `thinking_delta`    | `thinking`     | 模型或 provider 输出 thinking 时的思考片段。              |
| `signature_delta`   | `signature`    | thinking block 的签名片段，存在时透出。                   |
| `input_json_delta`  | `partial_json` | 工具入参 JSON 片段。                                 |
| `tool_output_delta` | varies         | 预留给未来的工具输出流式；当前仍以完整\ `agent.tool_result`\ 为准。 |

`agent.content_block_delta` 示例：

```
1{2  "id": "evt_delta_xxx",3  "type": "agent.content_block_delta",4  "session_id": "sess_xxx",5  "message_id": "msg_xxx",6  "index": 0,7  "delta": {8    "type": "text_delta",9    "text": "这是"10  },11  "processed_at": "2026-06-22T11:00:01Z"12}
```

增量事件解析约定：

* SSE `event:` 与 JSON `data.type` 都使用公开 Event 类型。

* `agent.content_block_delta.index` 用于区分多个 content block。

* `processed_at` 在增量事件上可能缺失，客户端应按可选字段处理。

* 网络中断后可使用 `Last-Event-ID` 携带最后收到的 Event ID 重连。

* `include_thinking=false` 时，会过滤 `thinking_delta`、`signature_delta` 及可识别的 thinking content block start/stop 事件。

* `include_tool_calls=false` 时，会过滤 `input_json_delta`、`tool_output_delta` 及可识别的 tool content block start/stop 事件。