Cloud Agent API
基於 Cursor 官方 Cloud Agents API v1 文件整理 agent、run、stream、artifacts、archive、worker tokens、models 和 repositories endpoints。
Cloud Agents API v1 用來以程式方式建立和管理 Cloud Agents。官方當前標記為 public beta，GA 前 API 可能變化。
閱讀目標：讀完本章，你應該能看懂 Cloud Agents API 的物件模型，並能判斷一個整合應該呼叫 agent、run、artifact、token 還是 metadata endpoint。
1. 物件模型
v1 API 把工作拆成 durable agent 和 per-prompt runs。
| 物件 | 含義 |
|---|---|
| Agent | 持久任務容器，儲存 repo、branch、URL、latestRunId、archive 狀態 |
| Run | 每次 prompt 執行，帶狀態、建立時間和更新時間 |
| Artifact | agent workspace 中 artifacts/ 下的產物 |
| Worker token | 給 My Machines worker 使用的短期 user-scoped token |
| Metadata | 當前 API key、可選 models、可訪問 repositories |
這和舊 v0 的 flatter surface 不同。遷移時要把“建立一個任務”理解成“建立 agent 並 enqueue 初始 run”。
2. 認證和前置
Cloud Agents API 使用 Basic Authentication。API key 可從 Cursor Dashboard -> Integrations 生成，也可以使用 service account API key。
上線前先確認：
- 使用 user API key 還是 service account API key。
- API key 許可權是否只覆蓋需要的團隊和 repo。
- rate limits、錯誤處理和 retry 策略是否按 API Overview 實現。
- 是否需要讀取 OpenAPI specification 生成型別或 SDK。
- 是否仍依賴 v0 webhooks；v1 webhooks 官方說明為 coming soon。
3. Agent endpoints
| Endpoint | 用途 | 注意 |
|---|---|---|
POST /v1/agents | 建立 Cloud Agent 並 enqueue 初始 run | 返回 agent 和 run |
GET /v1/agents | 列出 authenticated user 的 agents | newest first，支援 pagination、PR filter、includeArchived |
GET /v1/agents/{id} | 讀取 durable agent metadata | 執行狀態在 run 上，不在 agent 上 |
建立 agent 時核心欄位：
| Field | 說明 |
|---|---|
prompt.text | 必填任務指令 |
prompt.images | 可選圖片輸入，最多 5 張，每張 15 MB |
model.id | 可選顯式模型 ID；不填則按 user default、team default、system default 解析 |
model.params | 可選模型引數，例如 reasoning effort 或 max mode |
repos[0].url | GitHub repo URL；v1 當前支援一個 repository |
repos[0].startingRef | branch、tag 或 commit hash |
repos[0].prUrl | 指定 PR URL；提供後忽略 url 和 startingRef |
branchName | 自定義建立分支名 |
autoGenerateBranch | 配合 PR URL 決定新建 branch 還是推現有 head branch |
autoCreatePR | run 完成後是否建立 PR |
skipReviewerRequest | 自動建立 PR 時是否跳過把使用者請求為 reviewer |
envVars | session-scoped env vars，加密儲存，agent 刪除時刪除，名稱不能以 CURSOR_ 開頭 |
envVars 適合 run-scoped 配置，不適合長期憑據治理。長期 secrets 仍應走 Cloud Agents dashboard。
4. Run endpoints
| Endpoint | 用途 | 注意 |
|---|---|---|
POST /v1/agents/{id}/runs | 給 active agent 傳送 follow-up prompt | 同一 agent 只能有一個 active run |
GET /v1/agents/{id}/runs | 列出某 agent 的 runs | newest first，支援 pagination |
GET /v1/agents/{id}/runs/{runId} | 查詢具體 run 狀態和 timestamps | terminal state 也從這裡讀 |
GET /v1/agents/{id}/runs/{runId}/stream | 用 SSE stream 一個 run | 不 replay prior runs |
POST /v1/agents/{id}/runs/{runId}/cancel | 取消 active run | terminal 後不可恢復 |
如果在已有 run 處於 CREATING 或 RUNNING 時建立新 run，會返回 409 agent_busy。呼叫方應該等待、輪詢、stream 或先 cancel。
SSE stream 事件包括：
| Event | 含義 |
|---|---|
status | run 狀態更新 |
assistant | assistant text delta |
thinking | thinking text delta |
tool_call | tool call 狀態 |
heartbeat | keepalive |
result | terminal run status |
error | stream error |
done | stream complete |
斷線重連可用 Last-Event-ID，但 event id 必須屬於該 run，否則返回 400 invalid_last_event_id。stream retention 過期後可能返回 410 stream_expired，這時改用 Get A Run 讀取最終狀態。
5. Artifacts endpoints
Artifacts 是 agent-scoped，因為 workspace 會跨 runs 保留。
| Endpoint | 用途 | 注意 |
|---|---|---|
GET /v1/agents/{id}/artifacts | 列出 agent artifacts | path 是相對 artifacts/ 的路徑 |
GET /v1/agents/{id}/artifacts/download | 獲取 artifact 臨時下載 URL | 返回 15 分鐘 presigned S3 URL |
v1 只接受相對 artifact path。舊 v0 那種 /opt/cursor/artifacts/... 絕對路徑不能直接用。
下載 URL 是臨時 S3 presigned URL。產品裡展示 artifacts 時要考慮過期、許可權、敏感截圖和日誌內容。
6. Lifecycle endpoints
| Endpoint | 用途 | 行為 |
|---|---|---|
POST /v1/agents/{id}/archive | 歸檔 agent | 可讀但不能接受新 runs |
POST /v1/agents/{id}/unarchive | 取消歸檔 | 恢復接受新 runs |
DELETE /v1/agents/{id} | 永久刪除 agent | 不可逆 |
商業系統裡預設優先 archive。只有在合規、資料保留和審計要求都明確時，才呼叫永久 delete。
7. Worker tokens
POST /v1/sub-tokens 建立一小時有效的 user-scoped token，用於 My Machines worker 以某個 active team member 身份執行。
要求：
- 使用 agent-scoped team service account API key。
- 透過
forUserEmail或forUserId精確指定目標使用者，二選一。 - 返回 token 1 小時後過期，不能自重新整理。
- 需要重新整理時，用 service account API key 重新 mint。
這適合自管 per-user workers 或 Kubernetes 中的 token rotation。不要把它當長期 token。
8. Metadata endpoints
| Endpoint | 用途 | 注意 |
|---|---|---|
GET /v1/me | 檢視當前 API key 資訊 | 用於啟動前自檢 |
GET /v1/models | 列出推薦 explicit model IDs | 不填 model 時使用預設解析鏈 |
GET /v1/repositories | 列出 Cursor GitHub App 可訪問 repo | rate limit 很嚴格 |
GET /v1/repositories 官方強調限制嚴格：每使用者每分鐘 1 次、每使用者每小時 30 次。使用者 repo 很多時可能響應幾十秒。整合時必須快取，並能 graceful fallback。
9. API 整合驗收
上線前至少完成：
- API key 型別和許可權邊界已確認。
- 建立 agent 後能儲存
agent.id、run.id和 dashboard URL。 409 agent_busy、410 stream_expired、cancel 失敗等狀態有處理。- stream 斷線可恢復，恢復失敗能回退到 Get A Run。
- artifacts 下載 URL 過期後能重新請求。
- archive / delete 採用軟刪除優先策略。
envVars不承載長期 secrets。- repository list 做快取和限流。
- public beta 變化納入版本監控。
深讀：API 適合接系統，不適合跳過產品治理
API 能把 Cloud Agents 接到內部平臺、任務系統、CI、排障機器人或審批流裡。它也會讓 agent 建立、follow-up、cancel、artifact 下載變得更容易自動化。越是自動化，越要把 API key、repo 許可權、run 狀態、artifact 洩露和不可逆 delete 管住。
官方來源
- Cursor Cloud Agents API —— 官方 v1 API、agent、run、stream、artifacts、lifecycle、worker tokens 和 metadata endpoints。
- Cursor API Overview —— 官方 authentication、rate limits 和 API best practices。
- Cursor Service Accounts —— 官方 service account API key。
- Cursor My Machines —— 官方 user-scoped worker token 背景。