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