指南

事件參考

每種事件的欄位與順序保證。

公共欄位

除增量事件外，每個事件都包含以下欄位，再加上各自類型的欄位。事件歷史和事件串流中的同一個事件，JSON 完全相同。

欄位	類型	說明
`id`	string	事件 ID，`evt_…`。用它在歷史和事件串流之間去重。
`type`	string	事件類型，見下表。
`turn_id`	string	所屬輪次。
`created_at`	string	發生時間。

事件類型

type	欄位	說明
`user.message`	`content`、`files`、`skills`	你發送的訊息，每輪的第一個事件。`files` 是這條訊息附帶的檔案，`skills` 是它選用的技能（`id`、`name`）。
`agent.thinking`	`content`	Agent 一段完整的思考內容。僅在 `thinking_enabled` 為 `true` 且模型輸出思考時出現。
`agent.message`	`content`	Agent 一段完整的回覆文字。一輪中可以有多段，例如「我先查一下」、調用工具，再給出結論。
`agent.tool_use`	`tool_use_id`、`name`、`input`	Agent 調用一個工具。`name` 為工具名，`input` 為參數物件。工具列表見 Agent 執行環境；MCP 伺服器的工具名形如 `mcp__shop__lookup_order`。
`agent.tool_result`	`tool_use_id`、`content`、`is_error`、`files`	工具的執行結果，用 `tool_use_id` 與對應的 `agent.tool_use` 配對。`files` 是這次調用交付的檔案，只有 `deliver_file` 工具會產生。
`turn.completed`	`usage`	本輪正常完成（終止事件）。
`turn.failed`	`reason`、`usage`	本輪失敗（終止事件）。`reason` 見下文；`usage` 在還沒有調用過模型時為 `null`。
`turn.cancelled`	`usage`	本輪被取消（終止事件）。排隊中就被取消時 `usage` 為 `null`。

範例：工具調用與結果

{"id": "evt_9a03…", "type": "agent.tool_use", "turn_id": "turn_3f2a…", "created_at": "…",
 "tool_use_id": "toolu_01JB…", "name": "bash", "input": {"command": "python3 analyze.py data.csv"}}

{"id": "evt_c71e…", "type": "agent.tool_result", "turn_id": "turn_3f2a…", "created_at": "…",
 "tool_use_id": "toolu_01JB…", "content": "rows: 1204\nmean: 37.5", "is_error": false, "files": []}

範例：交付檔案

{"id": "evt_2d84…", "type": "agent.tool_use", "turn_id": "turn_3f2a…", "created_at": "…",
 "tool_use_id": "toolu_01KC…", "name": "deliver_file", "input": {"path": "/workspace/summary.csv"}}

{"id": "evt_e1a0…", "type": "agent.tool_result", "turn_id": "turn_3f2a…", "created_at": "…",
 "tool_use_id": "toolu_01KC…", "content": "File delivered: summary.csv (1,532 bytes)", "is_error": false,
 "files": [{"id": "file_7b1e…", "filename": "summary.csv", "mime_type": "text/csv", "size_bytes": 1532}]}

files 中每個元素包含 id、filename、mime_type、size_bytes。拿 id 調用下載檔案即可下載。

範例：終止事件

{"id": "evt_4b9f…", "type": "turn.completed", "turn_id": "turn_3f2a…", "created_at": "…",
 "usage": {"input_tokens": 2026, "output_tokens": 120}}

{"id": "evt_6da9…", "type": "turn.failed", "turn_id": "turn_3f2a…", "created_at": "…",
 "reason": "model_error", "usage": null}

用量 usage

usage 是本輪所有模型調用的合計 token 數：input_tokens 為輸入，output_tokens 為輸出。它只出現在三種終止事件上。

失敗原因 reason

reason	含義	建議
`model_error`	模型服務出錯且無法恢復，例如上游服務不可用、內容被攔截。	稍後重試；內容被攔截時調整輸入。
`timeout`	本輪到了約 1 小時的時長上限後仍未能收尾（見限流與限制）。到點時能正常停下的輪次不會是這個原因。	把任務拆小後重試。
`empty_output`	Agent 結束時沒有給出任何回覆。	重試，或換一種問法。
`internal_error`	平台內部錯誤。	重試；持續出現請聯絡我們，並提供 `turn_id`。
`worker_lost`	執行本輪的節點失去回應，系統終止了這一輪。	重試。
`worker_shutdown`	執行節點因維護或發佈而停止，本輪被中止。	重試。

以後可能增加新的 reason，請把不認識的值當作一般失敗處理。

增量事件（僅事件串流）

為了邊生成邊顯示，事件串流還會推送兩種增量事件。它們不會保存，不出現在事件歷史中，也沒有 id 和 created_at：

type	欄位	說明
`agent.message.delta`	`type`、`turn_id`、`content`	回覆文字的一小段，按順序拼接即為正在生成的回覆。
`agent.thinking.delta`	`type`、`turn_id`、`content`	思考內容的一小段。

增量不是按 token 推送的：平台把連續的片段攢到 200 個字元或 50 毫秒（先到為準）再推一條，遇到其他事件時立即推出已攢的部分。

增量是臨時的。隨後到達的 agent.message（或 agent.thinking）包含這一段的完整文字，應當用它替換之前拼出來的內容，而不是追加。具體規則見增量的處理。

順序保證

同一輪內的事件按發生順序推送和保存；事件歷史與事件串流中的順序一致。
每輪第一個事件是 user.message；最後一個是三種終止事件之一，並且恰好一個。
Agent 先說話再調用工具時，agent.message 排在它引出的 agent.tool_use 之前。
每個 agent.tool_use 都恰好對應一個 agent.tool_result。工具因為取消或逾時沒有執行完時，結果為 {"is_error": true, "content": "Cancelled."}。
content 為空字串的 agent.message 表示撤回之前流出的文字：模型的這次輸出被丟棄並重試了。
agent.thinking 的 content 從不為空：模型這一段沒有輸出思考（或提供商不返回思考）時，既沒有 agent.thinking.delta，也沒有 agent.thinking。撤回正文的空 agent.message 不撤回它之前的思考——那段思考已經作為 agent.thinking 保存，重試後的思考是新的一段。