创建 Cloud Agent

通过 v1 创建持久 Agent 与首轮 Run，配置仓库、模型、环境和任务能力。

This page has not been translated into English yet. The original Chinese version is shown below.

POST /v1/agents 创建持久 Agent，同时排入首轮 Run，响应分别返回 agent 和 run。v1 当前为 public beta，字段可能在正式发布前变化。

最小请求

curl --request POST \
  --url https://api.cursor.com/v1/agents \
  -u YOUR_API_KEY: \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": { "text": "Add a README with setup instructions" },
    "repos": [
      { "url": "https://github.com/your-org/your-repo", "startingRef": "main" }
    ]
  }'

prompt.text 必填。省略 model 时依次使用用户默认、团队默认、系统默认。指定时提供 model.id；用 GET /v1/models 发现当前 ID、aliases、parameters 和 variants，只传模型实际支持的 model.params 组合。

仓库和环境

字段	规则
`env.type`	`cloud`、`pool` 或 `machine`
`env.name`	命名云端环境、池或机器；pool 未指定时为 `default`，未知 pool 返回 400
`repos`	最多 20 项；不能与命名 Cursor 托管环境同时指定
`repos[].url`	每项必填，即使同项已给 `prUrl`
`repos[].startingRef`	起始分支或 SHA；有 `prUrl` 时忽略
`repos[].prUrl`	PR/MR 地址，使任务基于该请求的仓库与分支工作

同时省略 env 和 repos 可启动无仓库 Agent。自托管只有命名的 any-repo pool 支持多仓库；My Machines、default pool 和绑定仓库的池只接受一个，否则返回 400 validation_error。any-repo pool 可省略 repos。

请求支持已连接的 GitHub Cloud/Enterprise Server、GitLab Cloud/Self-Hosted、Bitbucket Cloud 和 Azure DevOps，仓库 URL 保留服务商实际主机名。

分支与 PR

workOnCurrentBranch 默认 false，推送到新生成的 cursor/... 分支；普通任务基于 startingRef，有 prUrl 时基于 PR base。设为 true 后，普通任务直接推送 startingRef，PR 任务直接推送 PR head。不要把此选项当作纯粹的命名偏好。

autoCreatePR 控制完成后是否开 PR。skipReviewerRequest 仅在 autoCreatePR 为 true 时生效。实际推送分支见返回的 git.branches[]。

图像、名称与模式

name 最长 100 字符，省略时从提示生成。mode 默认 agent，也可设 plan。prompt.images 最多 5 张，每张最大 15 MB，支持 PNG、JPEG、GIF、WebP；提供 data 时还需 mimeType，或提供 HTTP/HTTPS url。这是 API 限制，不是网页附件限制。

Secrets 与扩展

envVars 最多 50 项，名称最多 255 bytes 且不能以 CURSOR_ 开头，值最多 4096 bytes；加密存储、注入 shell，随 Agent 删除。该字段处于逐步开放的 beta，未开放账号会静默忽略，首次运行必须检查实际注入结果。自托管只在管理员启用 Secret sync 且 pool worker 使用 --sync-dashboard-secrets 时接收，My Machines 不接收。

mcpServers 最多 50 个且名称唯一。remote 可用 headers/OAuth，stdio 在 VM 内启动并可设置 env。端点字段表列出 http、sse、stdio，而 Cloud Agents MCP 专题仍说明云端不支持直接 SSE；部署前按实际支持核实，本文示例不依赖该有冲突的传输方式。

customSubagents 最多 20 个，每项需要 name、description、prompt，可选 model。名称不能重复或与 explore、debug、shell、computerUse 等内建项冲突。

重复创建保护

可自供 agentId，格式 bc-<uuid>；重复 POST 同一 ID 返回 409 agent_id_conflict，不会新建第二个 Agent，也不是自动重放原成功响应。agentId 与 envVars 不能一起使用，需要会话 secrets 时由服务端生成 ID。

创建后按Runs 与状态跟踪首轮结果。