常見問題

怎麼邊生成邊顯示回覆？

把 agent.message.delta 的 content 依次追加顯示，收到 agent.message 時用完整文字替換。見增量的處理。

發送訊息返回 409 session_running？

上一輪還沒有結束。等事件串流收到終止事件（或查詢會話，狀態不再是 RUNNING）後再發送；如果不再需要上一輪的結果，可以先取消。

怎樣把會話和我自己的用戶關聯起來？

在 metadata 中記錄你的用戶 ID 等資訊，例如 {"user": "u_42"}。平台不讀取也不驗證其中的內容。

如何統計用量？

每輪的終止事件都帶有 usage（輸入、輸出 token 數），按 turn_id 彙總即可得到每輪、每個會話的用量。

事件串流斷開了，會丟數據嗎？

完整事件不會丟：它們都存進了歷史。同一輪 24 小時內帶上 Last-Event-ID 重連即可接著收（增量片段不保存，重連後以隨後的完整事件為準）；任何時候也都可以透過事件歷史拿到完整記錄。

可以直接在網頁裡調用嗎？

不建議。API Key 只能保存在你的伺服器端。請由伺服器端調用 API 並訂閱事件串流，再轉發給你的前端。

怎樣讓 Agent 處理我的檔案？

先上載檔案拿到檔案 ID，再在發送訊息時放進 files。Agent 會在 /workspace/inputs/ 下找到它們。

怎樣拿到 Agent 生成的檔案？

在訊息中明確要求，例如「把結果保存成 summary.csv 交付給我」。Agent 用 deliver_file 交付後，agent.tool_result 的 files 中會有檔案 ID，調用下載檔案即可。也可以在本輪結束後用 GET /v1/files?session_id=… 列出該會話交付的所有檔案。

怎樣讓 Agent 按我們的固定流程做事？

把流程寫成技能：一份 SKILL.md，必要時附上腳本。上載後在發送訊息時放進 skills，見技能。

怎樣讓 Agent 查詢或操作我自己的系統？

把它做成 MCP 伺服器，註冊後在建立會話時指定，見 MCP 伺服器。Agent 在需要時會調用你定義的工具。

Agent 沒有使用我的技能或 MCP 工具？

技能：事件裡沒有 use_skill 多半是描述沒說清什麼時候用，或任務與它無關，可以在訊息裡點名；見排查技能問題。MCP：先看伺服器的 last_connect_error，再檢查 allowed_tools 和工具描述；見排查 MCP 問題。

出現問題怎麼回饋？

請提供發生問題的時間、session_id、turn_id，以及錯誤回應中的 request_id，便於我們查日誌。