指南

概述

基本概念、一次完整的調用與 ID 格式。

HKGAI Agent Workshop 以 API 提供 Agent（Agent as a Service）：Agent 的執行、沙箱、會話狀態和模型調度都在平台上運行，你的系統只需調用 API。

每個會話都在獨立的沙箱中執行，Agent 在裡面執行程式碼、讀寫檔案，也可以聯網搜尋（視平台配置）。圍繞會話，平台還提供：

項目	說明
API	`https://agent.hkgai.net/open/api/v1`
認證	`Authorization: Bearer sk-axon-…`
數據格式	請求與回應均為 JSON（UTF-8），上載檔案用 `multipart/form-data`；時間為 ISO 8601，UTC
事件串流	Server-Sent Events（`text/event-stream`）
API 版本	v1 · 文檔更新 2026-10-10

基本概念

概念	說明
項目 Project	資源的隔離單位。一個 API Key 只屬於一個項目，只能看到該項目下的會話、檔案、技能和 MCP 伺服器。
API Key	調用 API 的憑證，形如 `sk-axon-…`，由我們為你簽發。
會話 Session	一段與 Agent 的對話。建立時確定模型和指令，之後可以連續發送多條訊息，Agent 會記住會話內的上下文。每個會話有自己的沙箱。
輪次 Turn	一條用戶訊息及 Agent 對它的完整處理：思考、調用工具、回覆，直到結束。一個會話同一時間只執行一輪。
事件 Event	一輪中發生的每一步，例如 Agent 的一段回覆、一次工具調用。事件會被持久保存，也會透過事件串流即時推送。
檔案 File	屬於項目的檔案：你上載的，或 Agent 在某一輪中交付的。發送訊息時可以附帶上載的檔案，Agent 交付的檔案隨 `agent.tool_result` 事件給出。
技能 Skill	一份 `SKILL.md` 說明書，可以帶腳本和參考資料，告訴 Agent 怎樣完成某類任務。上載後屬於項目，發送訊息時選用。
MCP 伺服器	你自己的遠端 MCP 伺服器，註冊到項目後，建立會話時指定，Agent 就能調用它提供的工具。

建立會話，指定模型和指令。
發送一條訊息，開始一輪。需要 Agent 處理檔案時，先上載檔案，再把檔案 ID 放進訊息的 files。
訂閱事件串流，即時接收 Agent 的思考、工具調用和回覆。
收到 turn.completed、turn.failed 或 turn.cancelled 之一，本輪結束，事件串流關閉。Agent 交付的檔案在 agent.tool_result 的 files 中，用檔案 ID 下載。
需要繼續對話時，回到第 2 步發送下一條訊息。

下圖是同一過程中各方之間的請求與回應：

請求回應與推送每個請求都帶 Authorization: Bearer <API Key>，下載簽名地址除外。左右滑動查看完整的圖。

快速開始用 curl 走完這五步。

所有資源 ID 都是「前綴 + 底線 + 32 位十六進位」。請把 ID 當作不透明字串保存，不要解析其中的內容。