Autoworker Hub外部REST API契約

Autoworker Hub提供HTTP API，用於管理託管的AI工作者租戶及其執行、共用儲存空間、技能、cron工作、憑證與維運人員原則。

本技術資料說明API客戶端使用的契約，刻意省略主機部署內部細節與私有執行環境的實作細節。

基底URL

請使用維運人員提供的Hub URL：

https://<hub-host>

除非另有註明，所有管理端點均以/v1為根路徑。

驗證

管理端點要求提供：

Authorization: Bearer <token>

Webhook端點使用對應上游供應商的驗證機制。租戶執行環境的回呼端點僅供租戶執行環境使用，並非一般API客戶端介面。

回應格式

成功回應採用JSON格式，除非端點明確以串流傳送事件或下載檔案位元組。

錯誤採用問題描述式JSON，包含下列穩定欄位：

{
  "code": "invalid_argument",
  "message": "human-readable detail",
  "status": 400
}

核心端點

健康狀態與中繼資料

方法	路徑	用途
`GET`	`/v1/healthz`	存活檢查。
`GET`	`/v1/readyz`	就緒檢查。
`GET`	`/v1/version`	Hub版本與執行環境中繼資料。

租戶

方法	路徑	用途
`GET`	`/v1/tenants`	列出租戶。
`POST`	`/v1/tenants`	建立租戶並佈建資源。
`GET`	`/v1/tenants/{tenantId}`	取得單一租戶。
`PATCH`	`/v1/tenants/{tenantId}`	更新租戶中繼資料與期望設定。
`DELETE`	`/v1/tenants/{tenantId}`	刪除單一租戶。
`GET`	`/v1/tenants/{tenantId}/access`	讀取租戶存取狀態。
`PUT`	`/v1/tenants/{tenantId}/access`	設定租戶存取狀態。

租戶ID是路徑識別碼。請將其視為不解析內部結構的字串，且必須符合 API驗證規則。

租戶代理生命週期

方法	路徑	用途
`GET`	`/v1/tenants/{tenantId}/agent`	取得租戶代理的目前狀態。
`POST`	`/v1/tenants/{tenantId}/agent/start`	啟動或喚醒租戶代理。
`POST`	`/v1/tenants/{tenantId}/agent/stop`	停止租戶代理。
`POST`	`/v1/tenants/{tenantId}/agent/restart`	重新啟動租戶代理。
`GET`	`/v1/tenants/{tenantId}/agent-card`	傳回租戶的公開A2A Agent Card（代理卡片）。

執行與事件

方法	路徑	用途
`POST`	`/v1/tenants/{tenantId}/runs`	啟動一次受管理的AI工作者執行。
`GET`	`/v1/tenants/{tenantId}/runs/{runId}`	取得執行狀態與中繼資料。
`GET`	`/v1/tenants/{tenantId}/runs/{runId}/events`	以串流傳送執行事件。
`POST`	`/v1/tenants/{tenantId}/runs/{runId}/stop`	停止進行中的執行。
`POST`	`/v1/tenants/{tenantId}/runs/{runId}/approval`	處理待決的執行核准。

執行事件串流是長時間持續的回應。API客戶端應處理重新連線與執行的終止狀態。

租戶檔案

方法	路徑	用途
`GET`	`/v1/tenants/{tenantId}/files`	列出租戶可見的檔案根目錄與目錄。
`GET`	`/v1/tenants/{tenantId}/files/content`	讀取可用文字預覽的檔案內容。
`GET`	`/v1/tenants/{tenantId}/files/download`	下載單一租戶可見的檔案。
`GET`	`/v1/tenants/{tenantId}/runtime-inspection`	檢視解析後的租戶執行環境路徑與非機密環境資訊。

僅公開租戶可見的根目錄。機密、私有執行環境狀態及其他租戶的私有區域不屬於檔案API的範圍。

租戶環境索引鍵

方法	路徑	用途
`GET`	`/v1/tenants/{tenantId}/env`	列出租戶範圍內的環境索引鍵名稱與中繼資料。
`PUT`	`/v1/tenants/{tenantId}/env/{name}`	設定單一允許的租戶範圍索引鍵。
`DELETE`	`/v1/tenants/{tenantId}/env/{name}`	移除單一租戶範圍索引鍵。

僅可設定允許的租戶範圍機密類型名稱。Hub管理的執行環境索引鍵為保留鍵。

技能

方法	路徑	用途
`GET`	`/v1/tenants/{tenantId}/skills`	列出已安裝的租戶技能。
`GET`	`/v1/tenants/{tenantId}/skills/{category}/{skill}/files`	列出單一技能的檔案。
`GET`	`/v1/tenants/{tenantId}/skill-files/{skillPath}`	讀取單一技能檔案。
`PUT`	`/v1/tenants/{tenantId}/skills/{skillName}/state`	設定技能的啟用／停用狀態。

代理cron

方法	路徑	用途
`GET`	`/v1/tenants/{tenantId}/agent-cron`	列出租戶代理的cron工作。
`POST`	`/v1/tenants/{tenantId}/agent-cron`	建立代理cron工作。
`GET`	`/v1/tenants/{tenantId}/agent-cron/{jobId}`	取得單一cron工作。
`PATCH`	`/v1/tenants/{tenantId}/agent-cron/{jobId}`	更新單一cron工作。
`DELETE`	`/v1/tenants/{tenantId}/agent-cron/{jobId}`	刪除單一cron工作。
`POST`	`/v1/tenants/{tenantId}/agent-cron/{jobId}/pause`	暫停單一cron工作。
`POST`	`/v1/tenants/{tenantId}/agent-cron/{jobId}/resume`	恢復單一cron工作。
`POST`	`/v1/tenants/{tenantId}/agent-cron/{jobId}/run`	立即觸發單一cron工作。

cron工作的結構描述由租戶代理執行環境掌管。Hub直接傳遞工作定義，並傳回執行環境的回應。

共用群組與共用檔案

方法	路徑	用途
`GET`	`/v1/share-groups`	列出共用群組。
`POST`	`/v1/share-groups`	建立共用群組。
`GET`	`/v1/share-groups/{groupId}`	取得單一共用群組。
`PATCH`	`/v1/share-groups/{groupId}`	更新單一共用群組。
`DELETE`	`/v1/share-groups/{groupId}`	刪除單一共用群組。
`PUT`	`/v1/share-groups/{groupId}/members/{tenantId}`	設定成員的存取權限。
`DELETE`	`/v1/share-groups/{groupId}/members/{tenantId}`	移除成員。
`GET`	`/v1/tenants/{tenantId}/shares`	列出租戶可見的共用資源。

共用檔案操作以租戶與共用群組為範圍：

/v1/tenants/{tenantId}/shares/{groupId}/list
/v1/tenants/{tenantId}/shares/{groupId}/read
/v1/tenants/{tenantId}/shares/{groupId}/stat
/v1/tenants/{tenantId}/shares/{groupId}/grep
/v1/tenants/{tenantId}/shares/{groupId}/find
/v1/tenants/{tenantId}/shares/{groupId}/write
/v1/tenants/{tenantId}/shares/{groupId}/mkdir
/v1/tenants/{tenantId}/shares/{groupId}/move
/v1/tenants/{tenantId}/shares/{groupId}/remove

讀取操作需要具備該共用資源的成員資格。變更操作需要對該共用資源具備寫入權限。

A2A邊界介面

方法	路徑	用途
`POST`	`/a2a/{tenantId}`	租戶A2A端點。
`GET`	`/a2a/{tenantId}/.well-known/agent.json`	公開的代理中繼資料。
`GET`	`/a2a/{tenantId}/.well-known/agent-card.json`	公開的Agent Card。
`GET`	`/v1/tenants/{tenantId}/a2a-peers`	列出已引介的對等端。
`POST`	`/v1/tenants/{tenantId}/a2a-peers`	引介對等端。
`GET`	`/v1/tenants/{tenantId}/a2a-peers/{peerId}`	取得單一對等端。
`DELETE`	`/v1/tenants/{tenantId}/a2a-peers/{peerId}`	移除單一對等端。
`POST`	`/a2a/callbacks/{messageId}`	接受經權能驗證的非同步對等端Task更新。
`GET`	`/v1/peer-callback-outbox/metrics`	傳回持久化回呼傳遞的彙總指標。

非同步對等端回覆使用A2A推播通知設定及每則訊息專屬的回呼權能，而非Hub控制用的Bearer權杖。已完成、失敗與已取消的Task更新會在確認收到前持久化提交。完全相同的終止狀態重複更新具備冪等性；衝突的狀態轉換會遭到拒絕。暫時性回呼失敗會重試最長24小時，且重試會在Hub重新啟動後持續。

憑證與機密

方法	路徑	用途
`GET`	`/v1/tenants/{tenantId}/a2a-credentials`	傳回租戶A2A憑證。
`GET`	`/v1/tenants/{tenantId}/api-credentials`	傳回租戶範圍內的API憑證。
`POST`	`/v1/tenants/{tenantId}/api-credentials/rotate`	輪替租戶範圍內的API憑證。
`GET`	`/v1/secrets`	列出受管理的機密中繼資料。
`POST`	`/v1/secrets`	註冊受管理的機密，不傳回機密內容。
`GET`	`/v1/secrets/{secretId}`	傳回受管理的機密中繼資料。
`DELETE`	`/v1/secrets/{secretId}`	刪除受管理的機密中繼資料與內容。
`POST`	`/v1/secrets/{secretId}:replace-material`	取代僅可寫入的機密內容。
`POST`	`/v1/secrets/{secretId}:refresh`	重新整理單一OAuth2機密。
`POST`	`/v1/secrets/{secretId}:rotate`	輪替單一受管理的API金鑰機密。
`POST`	`/v1/secrets:refresh-due`	重新整理所有已到期的OAuth2機密。

機密內容僅可寫入。讀取API僅傳回中繼資料與狀態。

Flavor（代理專長設定）、發行版本與評估

方法	路徑	用途
`GET`	`/v1/hermes-agent/releases`	列出已安裝的代理發行版本。
`POST`	`/v1/hermes-agent/releases`	註冊或安裝發行版本。
`GET`	`/v1/hermes-agent/releases/{releaseId}`	取得單一發行版本。
`DELETE`	`/v1/hermes-agent/releases/{releaseId}`	刪除未啟用且未使用的發行版本。
`POST`	`/v1/hermes-agent/releases/{releaseId}:activate`	放行發行版本。
`GET`	`/v1/flavors`	列出Flavor目錄。
`POST`	`/v1/flavors`	安裝Flavor套件。
`GET`	`/v1/flavors/{flavorId}`	取得單一Flavor目錄條目。
`GET`	`/v1/flavors/{flavorId}/versions/{flavorVersion}`	取得單一Flavor版本。
`DELETE`	`/v1/flavors/{flavorId}/versions/{flavorVersion}`	刪除未使用的Flavor版本。
`GET`	`/v1/flavors/{flavorId}/versions/{flavorVersion}/contents`	傳回可呈現的Flavor內容。
`GET`	`/v1/flavors/{flavorId}/versions/{flavorVersion}/eval-suites`	列出Flavor評估套件。
`POST`	`/v1/flavors/{flavorId}/versions/{flavorVersion}/eval-runs`	啟動一次評估執行。
`POST`	`/v1/flavors/{flavorId}/versions/{flavorVersion}:deprecate`	將Flavor版本標示為已棄用。
`GET`	`/v1/eval-runs`	列出評估執行。
`GET`	`/v1/eval-runs/{evalRunId}`	取得單次評估執行。
`POST`	`/v1/eval-runs/{evalRunId}:cancel`	取消一次評估執行。

原則與設定

方法	路徑	用途
`GET`	`/v1/agent-policy`	傳回整個Hub的代理原則。
`PUT`	`/v1/agent-policy`	取代整個Hub的代理原則。
`GET`	`/v1/agent-features`	列出已知的代理功能。
`GET`	`/v1/agent-specialization`	取得託管代理的預設專長設定。
`PUT`	`/v1/agent-specialization`	取代預設專長設定。
`DELETE`	`/v1/agent-specialization`	停用預設專長設定。
`GET`	`/v1/tenants/{tenantId}/agent-policy`	取得租戶實際生效的原則與覆寫設定。
`PUT`	`/v1/tenants/{tenantId}/agent-policy`	取代租戶原則覆寫設定。
`DELETE`	`/v1/tenants/{tenantId}/agent-policy`	刪除租戶原則覆寫設定。
`GET`	`/v1/config/tenant-impact`	傳回影響租戶的設定檢視。
`PATCH`	`/v1/config/tenant-impact`	暫存影響租戶的設定變更。
`POST`	`/v1/config/tenant-impact:apply`	套用已暫存的設定變更。

指標與商務金鑰

方法	路徑	用途
`GET`	`/v1/metrics/runs`	列出執行指標。
`GET`	`/v1/metrics/runs/{runId}`	取得單筆執行指標紀錄。
`GET`	`/v1/metrics/schedules`	列出排程指標。
`GET`	`/v1/metrics/usage/aggregate`	彙總用量指標。
`GET`	`/v1/admin/business-keys`	列出商務金鑰。
`POST`	`/v1/admin/business-keys`	建立商務金鑰。
`DELETE`	`/v1/admin/business-keys/{businessKeyId}`	刪除商務金鑰。

Webhook

方法	路徑	用途
`POST`	`/webhooks/telegram`	Telegram Bot API訊息事件。

Webhook主體由供應商定義。

非供API客戶端使用的執行環境回呼端點

/v1/tenant-runtime/{tenantId}/...下的路徑保留供租戶執行環境回呼及Hub管理的執行環境Proxy使用。外部API客戶端不應直接呼叫這些端點，除非正在實作相容的租戶執行環境，且持有租戶執行環境憑證。