---
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="/docs/cursor/official" />
  <Card title="Cloud Agent Settings" description="回看 API 集成前的团队默认和安全设置。" href="/docs/cursor/official/04-cloud-agents/60-settings" />
</Cards>
