SSE 事件
流式模式（Accept: text/event-stream）下，發起對話和繼續對話會以一系列 SSE 事件推送運行過程。本頁列出所有事件類型及解析方式。
幀格式
每一幀 SSE 都使用同樣的信封結構：SSE 的 event 字段恆為 message，data 字段是一個 JSON 對象：
event: message
data: {"event":"<event_type>","workflow_run_id":"745910371102313","data":{...}}| 名稱 | 類型 | 說明 |
|---|---|---|
| event | string | 事件類型，按此字段分發處理 |
| workflow_run_id | string | 本次運行的 ID，為數字 ID 的字符串形式（如 "745910371102313"），同一次運行的所有事件中該值一致 |
| data | object | 事件負載，結構隨事件類型而不同（見下文） |
解析規則：
- 按
data.event分發，而不是 SSE 的event字段（它恆為message）。 - 忽略未知事件類型。 事件類型可能隨時新增，只處理已知事件的客戶端可保持向前兼容。
- 除特別說明外，
started_at/finished_at為 Unix 秒級時間戳，elapsed_time為秒數。
典型事件序列
一次運行始於 chat_started、止於 chat_finished，中間的事件取決於運行結果：
成功：
chat_started → workflow_started → thinking_started → message (type=think) ...
→ node_tool_use_started / node_tool_use_finished ...
→ thinking_finished → message (type=answer) ...
→ workflow_finished (status=succeeded) → chat_finished中斷（Agent 需要你補充信息，通過繼續對話恢復）：
chat_started → workflow_started → ... → human_interaction_required → chat_finished注意：中斷的運行不會發送 workflow_finished；繼續被中斷的運行時，恢復後的流不會再次發送 workflow_started。
失敗：
chat_started → workflow_started → ... → workflow_finished (status=failed) → chat_finished最簡客戶端
純問答場景只需處理四種事件，其餘事件都是可選的過程展示：
| 事件 | 處理方式 |
|---|---|
message（type=answer） | 將 data.text 追加到正在展示的回答中 |
human_interaction_required | 展示問題，攜帶答案調用繼續對話接口 |
workflow_finished | 讀取最終 status 和 outputs.answer；失敗時展示錯誤 |
chat_finished | 關閉流，本次運行結束 |
會話生命週期
chat_started
每個流的第一個事件。會話和消息記錄已創建；保存 chat_uid（用於追問）和 message_id（用於中斷後繼續）。
| 名稱 | 類型 | 說明 |
|---|---|---|
| chat_id | int64 | 會話內部 ID |
| chat_uid | string | 會話標識，用於後續請求 |
| message_id | int64 | 本輪消息 ID |
json
{"event":"chat_started","workflow_run_id":"745910371102313","data":{"chat_id":1001,"chat_uid":"ct_9f2c1a5b","message_id":42}}chat_finished
每個流的最後一個事件，之後服務端關閉連接。
| 名稱 | 類型 | 說明 |
|---|---|---|
| chat_id | int64 | 會話內部 ID |
| chat_uid | string | 會話標識 |
| message_id | int64 | 本輪消息 ID |
| error | string | 錯誤詳情，成功時為空 |
| error_message | string | 面向用戶的錯誤信息，成功時為空 |
運行生命週期
workflow_started
Agent 運行已開始。通過繼續對話恢復被中斷的運行時不會發送此事件。
| 名稱 | 類型 | 說明 |
|---|---|---|
| workflow_id | int64 | 該 Agent 底層工作流的 ID |
| started_at | int64 | 開始時間（Unix 秒） |
| inputs | object | 運行輸入 |
| hit_cache | bool | 為 true 時表示答案命中緩存，流會直接進入回答階段 |
workflow_finished
運行已結束——成功、失敗或被用戶停止。在此讀取最終結果。
| 名稱 | 類型 | 說明 |
|---|---|---|
| status | string | succeeded / failed / stopped |
| outputs | object | 運行輸出；outputs.answer 為完整的最終回答文本 |
| elapsed_time | number | 運行耗時（秒） |
| error | string | 本地化的錯誤描述，僅 status 為 failed 時存在 |
| error_code | int32 | 錯誤碼，僅 status 為 failed 時存在 |
| error_message | string | 面向用戶的錯誤信息，僅失敗時存在 |
| error_args | object | 額外錯誤上下文（如 workflow_run_id），可能省略 |
| process_data | object[] | 運行經過的過程階段，僅用於展示 |
json
{"event":"workflow_finished","workflow_run_id":"745910371102313","data":{"status":"succeeded","elapsed_time":3.21,"outputs":{"answer":"特斯拉（TSLA.US）近期..."}}}說明：
outputs.answer是權威的完整回答。如果你通過message事件拼接了回答，可用它校驗或替換。status為stopped（用戶停止運行）時，outputs.answer為已生成的部分回答。
回答流式輸出
message
增量文本片段。這是頻率最高的事件，按到達順序拼接 text 即可。
| 名稱 | 類型 | 說明 |
|---|---|---|
| text | string | 增量文本片段 |
| type | string | answer — 最終回答文本；think — 推理過程；process — 階段進度描述 |
| key | string | 片段所屬流段的標識。相同 key 的片段構成一個連續塊，渲染時按 key 分組 |
| started_at | int64 | 該流段開始時間（Unix 秒） |
| stage | string | 階段標識，僅 type=process 時存在 |
| stage_title | string | 階段進行中的標題，僅 type=process 時存在 |
| stage_finished_title | string | 階段完成後的標題，僅 type=process 時存在 |
| outputs | object | 附加在片段上的額外負載，通常不存在 |
json
{"event":"message","workflow_run_id":"745910371102313","data":{"text":"特斯拉","type":"answer","key":"n_llm_1:answer","started_at":1752048000}}解析：
- 只有
type=answer的片段屬於用戶可見的回答，全部拼接後與workflow_finished.outputs.answer一致。 type=think的片段是 Agent 的中間推理，可放入可摺疊的「思考」區域展示，也可忽略。type=process的片段描述階段進度，附帶stage系列字段用於分組。
思考階段
thinking_started
Agent 進入推理階段（分析問題、規劃工具調用）。在它與 thinking_finished 之間可能出現 type=think 的 message 事件和工具調用事件。
| 名稱 | 類型 | 說明 |
|---|---|---|
| started_at | int64 | 開始時間（Unix 秒） |
thinking_finished
推理階段結束，隨後是回答文本（type=answer 的 message）。
| 名稱 | 類型 | 說明 |
|---|---|---|
| finished_at | int64 | 結束時間（Unix 秒） |
| elapsed_time | int32 | 推理耗時（秒） |
工具調用
Agent 在生成回答的過程中會調用工具（行情、賬戶、聯網搜索等）。每次調用都由一對 started/finished 事件包裹——用 tool_use_id 配對。
這對事件覆蓋所有普通工具調用。只有兩種特殊調用改用各自的事件族上報：派生子智能體（subagent_*，見下文）和把另一個 Agent 作為工具調用（agent_tool_*，見下文）。如果你的 Agent 沒有使用這兩項能力，所有工具調用都只會以 node_tool_use_started / node_tool_use_finished 出現。
node_tool_use_started
一次工具調用已開始。
| 名稱 | 類型 | 說明 |
|---|---|---|
| tool_use_id | string | 本次調用的唯一 ID，用於與 finished 事件配對 |
| tool_name | string | 工具的本地化展示名（用於界面顯示） |
| tool_func_name | string | 與語言無關的穩定工具標識，按工具類型處理邏輯時用它 |
| tool_args | string | 調用參數（JSON 字符串） |
| tips | string | 可直接展示的進度文案（如「正在聯網搜索…」） |
| tip_chips | string[] | 與 tips 配套的短標籤，可能省略 |
| iteration | int | 輪次編號。同一輪（相同 iteration）的調用是並行執行的 |
| started_at | int64 | 開始時間（Unix 秒） |
node_tool_use_finished
工具調用已結束。
| 名稱 | 類型 | 說明 |
|---|---|---|
| tool_use_id | string | 與 started 事件的 tool_use_id 一致 |
| status | string | succeeded / failed |
| error | string | 失敗時的錯誤描述 |
| elapsed_time | number | 調用耗時（秒） |
| started_at | int64 | 開始時間（Unix 秒） |
| tool_name | string | 本地化展示名 |
| tool_func_name | string | 穩定工具標識 |
| tool_args | string | 調用參數（JSON 字符串） |
| tool_type | string | 工具類別 |
| tips | string | 進度文案 |
| tip_chips | string[] | 短標籤，可能省略 |
| iteration | int | 輪次編號 |
| is_thinking | bool | 為 true 表示調用發生在思考階段 |
| outputs | object | 過濾後的調用結果，見下 |
outputs 只攜帶用於展示的字段：
| 字段 | 說明 |
|---|---|
| outputs.references | 工具結果引用的來源 |
| outputs.reference_domains | 引用來源的域名 |
| outputs.query | 工具執行的查詢 |
| outputs.text | 工具的原始響應文本 |
| outputs.tool_args | 解析後的請求參數 |
| outputs.data | 結構化結果，僅部分工具存在 |
json
{"event":"node_tool_use_finished","workflow_run_id":"745910371102313","data":{"tool_use_id":"call_abc123","status":"succeeded","elapsed_time":1.42,"tool_name":"聯網搜索","tool_func_name":"web_search","tool_args":"{\"query\":\"TSLA stock news\"}","tool_type":"builtin","tips":"已聯網搜索","iteration":1,"is_thinking":true,"outputs":{"query":"TSLA stock news","references":[{"index":1,"title":"...","url":"..."}]}}}子智能體事件
Agent 派生子智能體處理子任務時，其生命週期使用獨立的事件族上報，而不是 node_tool_use_*。
subagent_started
| 名稱 | 類型 | 說明 |
|---|---|---|
| node_id | string | 派生子智能體的節點 ID |
| tool_use_id | string | 本次派生的唯一 ID，與 finished 事件配對 |
| started_at | int64 | 開始時間（Unix 秒） |
| goal | string | 分配給子智能體的目標 |
| prompt | string | 交給子智能體的完整任務提示詞 |
| subagent_id | string | 子智能體標識，可能省略 |
| tools | array | 授予子智能體的工具列表，可能省略 |
subagent_progress
子智能體每調用一次自己的工具就發送一次，用於在子智能體卡片內實時渲染時間線。
| 名稱 | 類型 | 說明 |
|---|---|---|
| node_id | string | 派生子智能體的節點 ID |
| parent_tool_call_id | string | 所屬 subagent_started 事件的 tool_use_id |
| subagent_tool_name | string | 子智能體調用的工具名 |
| subagent_tool_args | string | 該調用的參數（JSON 字符串） |
| subagent_status | string | 該調用的狀態：running / succeeded / failed |
| subagent_duration_ms | int64 | 該調用耗時（毫秒） |
| subagent_iteration | int | 子智能體內部的輪次編號 |
| started_at | int64 | 開始時間（Unix 秒） |
subagent_finished
| 名稱 | 類型 | 說明 |
|---|---|---|
| node_id | string | 派生子智能體的節點 ID |
| tool_use_id | string | 與 subagent_started 的 tool_use_id 一致 |
| status | string | succeeded / failed |
| started_at | int64 | 開始時間（Unix 秒） |
| elapsed_time | number | 子智能體總耗時（秒） |
| error | string | 失敗時的錯誤描述 |
| outputs | object | 子智能體結果：通常包含 goal、result 和 subagent_tools（其工具調用時間線） |
Agent 工具事件
Agent 把另一個 Agent 作為工具調用時，該內部運行使用 agent_tool_* 事件族上報，結構與子智能體事件相似。
agent_tool_started
| 名稱 | 類型 | 說明 |
|---|---|---|
| node_id | string | 調用方節點 ID |
| tool_use_id | string | 本次調用的唯一 ID，與 finished 事件配對 |
| agent_tool_name | string | 被調用 Agent 的標識 |
| title | string | 展示標題，可能省略 |
| started_at | int64 | 開始時間（Unix 秒） |
| tool_args | string | 調用參數（JSON 字符串） |
| tool_name | string | 本地化展示名 |
| tips | string | 進度文案，可能省略 |
| tip_chips | string[] | 短標籤，可能省略 |
| is_thinking | bool | 為 true 表示發生在思考階段 |
agent_tool_progress
被委託 Agent 每進行一次內部工具調用就發送一次。
| 名稱 | 類型 | 說明 |
|---|---|---|
| node_id | string | 調用方節點 ID |
| parent_tool_call_id | string | 所屬 agent_tool_started 事件的 tool_use_id |
| agent_tool_name | string | 被調用 Agent 的標識 |
| inner_tool_name | string | 被委託 Agent 調用的內部工具名 |
| inner_tool_args | string | 該內部調用的參數（JSON 字符串） |
| status | string | 內部調用的狀態：running / succeeded / failed |
| duration_ms | int64 | 內部調用耗時（毫秒） |
| started_at | int64 | 開始時間（Unix 秒） |
| is_thinking | bool | 為 true 表示發生在思考階段 |
agent_tool_finished
| 名稱 | 類型 | 說明 |
|---|---|---|
| node_id | string | 調用方節點 ID |
| tool_use_id | string | 與 agent_tool_started 的 tool_use_id 一致 |
| agent_tool_name | string | 被調用 Agent 的標識 |
| status | string | succeeded / failed |
| started_at | int64 | 開始時間（Unix 秒） |
| elapsed_time | number | 總耗時（秒） |
| error | string | 失敗時的錯誤描述 |
| tool_args | string | 調用參數（JSON 字符串） |
| outputs | object | 被委託 Agent 的結果 |
| tool_type | string | 工具類別 |
| tips | string | 進度文案，可能省略 |
| tip_chips | string[] | 短標籤，可能省略 |
| is_thinking | bool | 為 true 表示發生在思考階段 |
中斷
human_interaction_required
運行已暫停：Agent 需要你補充信息或確認。收集 questions 的答案後調用繼續對話——答案以 tool_call_id 為鍵。
| 名稱 | 類型 | 說明 |
|---|---|---|
| node_id | string | 觸發中斷的節點 ID |
| tool_call_id | string | 本次詢問的 ID，繼續對話時作為 answers_by_tool_call 的外層鍵 |
| questions | object[] | 需要回答的問題 |
| ∟ question | string | 問題文本，繼續對話時作為 answers_by_tool_call 的內層鍵 |
| ∟ options | object[] | 選項，為空表示自由輸入 |
| ∟∟ description | string | 選項文本 |
| ∟ multi_select | boolean | 是否可多選 |
| message_id | int64 | 被暫停消息的 ID，用於繼續對話接口的 URL |
| chat_id | int64 | 所屬會話的 ID |
json
{"event":"human_interaction_required","workflow_run_id":"745910371102313","data":{"node_id":"n_ask_human","tool_call_id":"call_abc123","questions":[{"question":"你想查看哪個時間範圍？","options":[{"description":"近一週"},{"description":"近一月"}],"multi_select":false}],"message_id":43,"chat_id":1001}}此事件之後流以 chat_finished 結束；被中斷的運行不會發送 workflow_finished。
輔助事件
以下事件均為信息性事件，最簡客戶端可全部忽略。
query_masked
用戶提問中的敏感內容在處理前被脫敏。展示時用 masked_query 替換原始提問。
| 名稱 | 類型 | 說明 |
|---|---|---|
| raw_query | string | 原始用戶提問 |
| masked_query | string | 脫敏後的提問 |
plan_changed
Agent 創建或更新了任務計劃。
| 名稱 | 類型 | 說明 |
|---|---|---|
| node_id | string | 規劃節點的 ID |
| started_at | int64 | 變更時間（Unix 秒） |
| outputs | object | 當前計劃內容 |
此事件額外攜帶一個頂層 tool_name 字段（與 data 同級），標識規劃工具。
context_compress_started / context_compress_finished
長對話會觸發上下文壓縮，這兩個事件包裹壓縮過程。與其他事件不同，這裡的時間戳是 RFC 3339 字符串。
context_compress_started：
| 名稱 | 類型 | 說明 |
|---|---|---|
| started_at | string | 開始時間（RFC 3339） |
| inputs | object | 壓縮輸入摘要 |
context_compress_finished：
| 名稱 | 類型 | 說明 |
|---|---|---|
| created_at | string | 結束時間（RFC 3339） |
| inputs | object | 壓縮輸入摘要 |
| outputs | object | 壓縮結果摘要 |