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": "客户支持会话",
  "metadata": {
    "source": "web",
    "biz_id": "ticket_123"
  },
  "config": {
    "environment_variables": {
      "API_KEY": "sk-xxx"
    }
  },
  "stats": {
    "active_seconds": 30,
    "duration_seconds": 3600
  },
  "usage": {
    "total_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 摘要。
`source_type`	string	是	Session 来源：`api`、`im`、`schedule` 或 `batch`。
`status`	string	是	Session 运行状态：`idle`、`running`、`rescheduling`、`canceling` 或 `terminated`。归档状态通过 `archived_at` 表达。
`title`	string	是	Session 标题。
`metadata`	object	否	调用方业务元数据。
`config`	object	否	Session 配置；未传入时可能省略。
`config.environment_variables`	object	否	会话级环境变量，key-value 形式；在 Template + Identity Config 编译结果基础上追加合并，同名变量覆盖基础层的值。
`stats`	object	否	Session 统计信息，字段见 Session stats。
`usage`	object	否	用量信息；相关计费模块未启用时可能省略。
`usage.total_credits`	number	否	累计 Credit 消耗，推荐使用的用量字段。仅新创建的 Session 返回该字段，历史 Session 可能不包含。
`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`。

Thread 对象

Thread 表示 Session 运行时中的一个执行分支。列出、获取和归档 Thread 接口都会返回该对象。

{
  "id": "sthr_child_xxx",
  "type": "session_thread",
  "session_id": "sess_xxx",
  "parent_thread_id": "sthr_coordinator_xxx",
  "template_id": "tmpl_worker",
  "name": "research",
  "role": "child",
  "status": "idle",
  "stop_reason": { "type": "end_turn" },
  "created_by_tool_use_id": "toolu_xxx",
  "created_at": "2026-06-22T11:00:00Z",
  "updated_at": "2026-06-22T11:05:00Z"
}

字段	类型	必返	说明
`id`	string	是	`sthr_` 前缀的 Thread ID。
`type`	string	是	固定为 `"session_thread"`。
`session_id`	string	是	Thread 所属 Session ID。
`parent_thread_id`	string	否	父 Thread ID；coordinator Thread 不返回该字段。
`template_id`	string	否	运行时 Agent 能可靠映射到父 Session 的 Forward Template 时返回。
`name`	string	否	Thread 的公开名称。
`role`	string	是	Thread 角色：`coordinator` 或 `child`。
`status`	string	是	未归档时为 `idle`、`running`、`rescheduling` 或 `terminated` 等运行状态；`archived_at` 非空时归一为 `archived`。
`stop_reason`	object	否	Thread 停止原因。
`created_by_tool_use_id`	string	否	创建 child Thread 的 tool use ID。
`archived_at`	string	否	归档时间，RFC 3339 格式；未归档时省略。
`created_at`	string	否	创建时间，RFC 3339 格式。
`updated_at`	string	否	最近更新时间，RFC 3339 格式。

Thread 响应不会暴露 CAS Agent ID、Agent 对象、Agent Version 或 Template Version。

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。
`session_thread_id`	string	否	Thread lifecycle Event 描述的 Thread ID。
`processed_at`	string	否	事件被处理的时间，RFC 3339 格式。部分 agent 生成事件或增量事件可能不包含该字段。

按事件类型允许出现的 payload 字段如下。表中不重复列出通用字段 id、type、session_id、session_thread_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`
`agent.message`	`content`
`agent.thinking`	`thinking`、`text`
`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`
`event_start`	`event`
`event_delta`	`event_id`、`delta`
`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.thread_created`	`session_thread_id`
`session.thread_status_running`	`session_thread_id`
`session.thread_status_idle`	`session_thread_id`
`session.thread_status_rescheduled`	`session_thread_id`
`session.thread_status_terminated`	`session_thread_id`
`session.error`	`error`
`session.updated`	`agent`、`metadata`、`title`
`span.model_request_end`	`is_error`、`model_request_start_id`、`model_usage`

客户端可发送事件类型

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

类型	必填字段	说明
`user.message`	`content`	用户消息。`content` 必须是非空 content block 数组，仅支持 `text`、`image` 类型。
`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` 可选。

公开事件类型

查询历史和订阅 SSE 事件流时，可能收到以下公开事件类型；其中 event_start 和 event_delta 仅在订阅 SSE 且传入 event_deltas[] 时可能返回： user.message、user.interrupt、user.tool_confirmation、user.tool_result、user.custom_tool_result、user.define_outcome、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、event_start、event_delta、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.thread_created、session.thread_status_running、session.thread_status_idle、session.thread_status_rescheduled、session.thread_status_terminated、session.error、session.updated 和 span.model_request_end。

模型用量事件

一次模型调用完成后，事件流会输出 span.model_request_end 事件，携带本次模型调用的用量信息：

{
  "id": "evt_xxx",
  "type": "span.model_request_end",
  "is_error": false,
  "model_request_start_id": "evt_yyy",
  "model_usage": {
    "credits": 0.42
  },
  "processed_at": "2026-06-22T11:00:01Z"
}

字段	类型	说明
`is_error`	boolean	本次模型请求是否因错误或取消而结束。
`model_request_start_id`	string	对应的模型请求开始事件的 Event ID。
`model_usage`	object	本次模型调用的用量对象。
`model_usage.credits`	number	本次模型调用消耗的 credits。

model_usage.credits 是单次调用增量，不是 Session 累计值。消费端可按 Event ID 去重后，将其累加到该 Session 的模型用量记录中；事件流不提供 Session 累计用量，累计值请通过获取 Session 接口读取 usage.total_credits，并可用其校准事件累加结果。

增量流式事件

流式增量事件通过订阅 Session Event Stream 接口的 event_deltas[] 查询参数开启。支持重复传参，允许值如下：

`event_deltas[]` 取值	说明
`agent.message`	订阅 assistant 文本消息的增量内容。
`agent.thinking`	订阅 thinking 的增量内容。

开启后，SSE 事件流中可能额外返回以下两类顶层 Event：

Event 类型	关键字段	说明
`event_start`	`event`	表示某个公开事件开始生成。`event` 中只保留 `id`、`type`、`name`、`mcp_server_name`。
`event_delta`	`event_id`、`delta`	表示某个公开事件的增量片段。`event_id` 指向对应的事件。

event_start.event 字段：

字段	类型	说明
`id`	string	对应事件的 Event ID。
`type`	string	对应事件的公开 Event 类型，当前为 `agent.message` 或 `agent.thinking`。
`name`	string	预留字段；当前 `event_deltas[]` 不支持工具调用类 selector，通常不会返回。
`mcp_server_name`	string	预留字段；当前 `event_deltas[]` 不支持 MCP 工具调用类 selector，通常不会返回。

event_delta.delta 字段：

字段	类型	说明
`type`	string	增量类型，例如 `content_delta`。
`index`	integer	content block 下标。
`content`	object	增量内容。当前只透出 `type` 和 `text`。
`content.type`	string	内容类型，例如 `text` 或 `thinking`。
`content.text`	string	本次增量文本片段。

event_start 示例：

{
  "id": "evt_xxx",
  "type": "event_start",
  "session_id": "sess_xxx",
  "event": {
    "id": "evt_xxx",
    "type": "agent.message"
  }
}

event_delta 示例：

{
  "id": "evt_xxx",
  "type": "event_delta",
  "session_id": "sess_xxx",
  "event_id": "evt_xxx",
  "delta": {
    "type": "content_delta",
    "index": 0,
    "content": {
      "type": "text",
      "text": "这是"
    }
  }
}

流式增量事件解析约定：

只有订阅 SSE 事件流且传入 event_deltas[] 时，才会返回 event_start / event_delta；历史查询不返回这类流式增量事件。
最终完整公开事件仍会返回。客户端可使用流式增量事件做即时展示，再以最终完整事件作为持久化或展示校准结果。
include_thinking=false 时，会过滤 agent.thinking 事件开始信号和 delta.content.type=thinking 的增量片段。
include_tool_calls=false 不影响 event_deltas[] 当前支持的 agent.message 和 agent.thinking 流式增量事件，但仍会过滤普通工具调用事件和旧版工具输入/输出 delta。

旧版增量流式事件数据结构

为兼容既有客户端，事件流和历史查询仍可能返回旧版增量事件。由创建 Session 时的 incremental_streaming_enabled 字段控制。新接入不建议依赖这些事件，最终完整的 agent.message 仍会返回。旧版顶层增量事件类型如下：

事件类型	关键字段	说明
`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 示例：

{
  "id": "evt_delta_xxx",
  "type": "agent.content_block_delta",
  "session_id": "sess_xxx",
  "message_id": "msg_xxx",
  "index": 0,
  "delta": {
    "type": "text_delta",
    "text": "这是"
  },
  "processed_at": "2026-06-22T11:00:01Z"
}

旧版增量事件解析约定：

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 事件。

​Session 对象

​Template 摘要

​Session stats

​Thread 对象

​Event 对象

​客户端可发送事件类型

​公开事件类型

​模型用量事件

​增量流式事件

​旧版增量流式事件数据结构