session&event数据结构 - Qoder CN 系列

适用于 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 摘要，字段见添加网页链接。
`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 统计信息，字段见添加网页链接。
`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 事件。