后台代理（Background Agent）

借助后台代理，您可以启动异步代理，这些代理能够在远程环境中编辑和运行代码。您可以随时查看其状态、发送后续指令或接管操作。

使用方法

1. 按下 Ctrl+E 打开后台代理控制面板，该面板支持列出已有代理、创建新代理以及查看代理状态。

2. 提交提示词后，从列表中选择代理即可查看其状态，并进入代理正在运行的机器环境。

信息

后台代理功能需要保留数日量级的数据才能正常运行。

反馈渠道

欢迎通过以下方式直接反馈：

• 我们的 Discord #background-agent 频道
• 发送邮件至 [email protected]

请向我们提交错误报告、功能请求或改进建议。

运行环境

后台代理默认运行在基于 Ubuntu 的隔离机器镜像中。该代理具有互联网访问权限，可安装运行应用程序所需的软件包。

GitHub 连接

当前后台代理会从 GitHub 克隆您的代码仓库。这些代理会在独立分支上完成工作，并将修改推送至您的仓库，方便您后续接管他们的工作。

这意味着您需要为代码仓库（以及所有依赖仓库或子模块）授予读写权限。未来我们也将支持其他代码托管平台（GitLab、BitBucket 等）。

基础环境配置

对于更高级的用例，您可以自行配置开发环境。您将获得一个连接至远程机器的 IDE 实例。请先完成机器配置并安装开发工具和软件包，待所有设置就绪后创建环境快照。接下来配置运行时设置：

• 安装命令会在代理启动前执行，用于安装运行时依赖。通常需要执行 npm install 或 bazel build 等命令
• 终端允许您在代理运行期间执行后台进程，例如启动 Web 服务器或编译 protobuf 文件

对于最复杂的场景，您还可以使用 Dockerfile 进行机器配置。通过 Dockerfile 可以声明式地配置系统级依赖：安装特定版本的编译器、调试器，甚至完全替换基础操作系统镜像。请注意 Dockerfile 不应使用 COPY 复制整个项目——我们会管理工作区并检出正确的提交版本。与基于快照的配置类似，您仍需在安装脚本中处理依赖项的安装。

如需为开发环境配置必要密钥，这些凭证将以静态加密（使用 KMS）形式存储在我们的数据库中，并在后台代理环境中自动提供。

机器配置信息存储在 .cursor/environment.json 文件中，该文件可以提交至代码仓库（推荐做法）或设置为用户私有配置。我们的配置流程将引导您创建正确的 environment.json 文件。

// 示例环境配置文件
{
"runtime": {
"installCommand": "npm install && pip install -r requirements.txt"
},
"dockerfile": "./Dockerfile",
"terminals": [
{
"name": "web_server",
"command": "python app.py"
}
]
}

提示

• 使用 Dockerfile 时建议选择轻量级基础镜像（如 Alpine Linux）
• 定期更新环境快照可确保团队成员保持一致的开发环境
• 密钥管理可通过 cursor.com/settings 控制面板进行配置

维护命令

当为新后台代理配置新机器时，我们从基础环境开始，然后运行您在 environment.json 文件中配置的 install 命令。该命令可以理解为开发者在切换代码分支时需要运行的命令。特别需要注意的是，它应该安装所有可能新增的依赖项。

对于大多数用户而言，install 命令通常是类似 npm install 或 bazel build 的操作。

为了确保机器启动速度，我们会在运行 install 命令后缓存磁盘状态。这意味着该命令需要设计为可重复多次执行。只有通过 install 命令产生的磁盘状态会被持久化，因此当代理启动时，在此阶段启动的任何进程都不会保持运行状态。

启动命令

执行 install 命令完成环境初始化后，系统将启动并自动运行 start 命令，随后开启所有配置的 terminals 终端。这种机制可确保在代理程序运行时维持必要的进程存活。

通常可以省略 start 命令。一个典型使用场景是当开发环境依赖 Docker 时，您需要将 sudo service docker start 配置在 start 命令中。

terminals 终端专为应用程序代码设计。这些终端会在 tmux 会话中运行，该会话对开发者和 AI 代理均可见。例如，大多数网站代码库会将 npm run watch 配置为终端命令之一。

environment.json 规范说明

非正式情况下，environment.json 文件可能如下所示：

{
"snapshot": "POPULATED_FROM_SETTINGS",
"install": "npm install",
"terminals": [
{
"name": "Run Next.js",
"command": "npm run dev"
}
]
}

正式规范定义请参见此处。

模型

仅支持兼容 Max 模式 的模型用于后台代理（Background Agents）。计费基于令牌（Token）使用量。未来我们可能还会对开发环境计算资源的使用收取费用。

安全性

后台代理功能可在隐私模式下使用。我们绝不会基于您的代码进行模型训练，且仅会出于运行代理的目的暂时保留代码。详细了解隐私模式

关于此功能的重要须知：

1. 需要授予 GitHub 应用读写权限：您需要为希望使用后台代理编辑的代码库，向我们的 GitHub 应用授予读写权限。此权限用于克隆代码库并执行变更操作。
2. 代码运行环境隔离：您的代码将在 AWS 基础设施的隔离虚拟机中运行，只要代理处于可访问状态，代码就会存储在虚拟机磁盘上。
3. 互联网访问权限：后台代理默认拥有互联网访问能力。
4. 自动执行终端命令的风险：与需要逐条审批命令的前台代理不同，后台代理会自动执行所有终端命令以实现测试迭代。这种自动化机制存在数据泄露风险：攻击者可能通过提示词注入攻击诱使代理将代码上传至恶意网站。具体风险分析可参考 OpenAI 关于后台代理网络访问风险的说明。
5. 数据收集说明：若未启用隐私模式，我们会收集提示词和开发环境数据用于产品优化。
6. 隐私模式切换规则：如果在启动后台代理时未启用隐私模式，即使中途开启隐私模式，当前代理仍会以非隐私模式运行直至任务完成。