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 背景。