---
title: "Cloud Agent API"
description: "基於 Cursor 官方 Cloud Agents API v1 文件整理 agent、run、stream、artifacts、archive、worker tokens、models 和 repositories endpoints。"
verifiedAt: "2026-05-09"
---

Cloud Agents API v1 用來以程式方式建立和管理 Cloud Agents。官方當前標記為 public beta，GA 前 API 可能變化。

> [!NOTE]
> **閱讀目標**：讀完本章，你應該能看懂 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 變化納入版本監控。

<details>
<summary>深讀：API 適合接系統，不適合跳過產品治理</summary>

API 能把 Cloud Agents 接到內部平臺、任務系統、CI、排障機器人或審批流裡。它也會讓 agent 建立、follow-up、cancel、artifact 下載變得更容易自動化。越是自動化，越要把 API key、repo 許可權、run 狀態、artifact 洩露和不可逆 delete 管住。
</details>

## 官方來源

- [Cursor Cloud Agents API](https://cursor.com/docs/cloud-agent/api/endpoints.md) —— 官方 v1 API、agent、run、stream、artifacts、lifecycle、worker tokens 和 metadata endpoints。
- [Cursor API Overview](https://cursor.com/docs/api.md) —— 官方 authentication、rate limits 和 API best practices。
- [Cursor Service Accounts](https://cursor.com/docs/account/enterprise/service-accounts.md) —— 官方 service account API key。
- [Cursor My Machines](https://cursor.com/docs/cloud-agent/my-machines.md) —— 官方 user-scoped worker token 背景。

## 接下來去哪

<Cards>
  <Card title="Cursor 官方教程目錄" description="返回 Cursor 官方資料總目錄。" href="/zh-Hant/docs/cursor/official" />
  <Card title="Cloud Agent Settings" description="回看 API 整合前的團隊預設和安全設定。" href="/zh-Hant/docs/cursor/official/04-cloud-agents/60-settings" />
</Cards>
