使用 background agents，在遠端環境中啟動非同步代理來編輯並執行程式碼。你可以隨時查看它們的狀態、傳送後續指示，或直接接手。

​
如何使用

你可以用兩種方式使用背景代理：
  1. 背景代理側邊欄：在 Cursor 的原生側邊欄使用背景代理分頁，查看與你帳號相關的所有背景代理、搜尋既有代理，並啟動新的代理。
  2. 背景代理模式：按下 以在介面中啟用背景代理模式。
提交提示後，從清單中選擇你的代理來查看狀態並進入執行環境。

背景代理需要保留資料數天。

​
回饋

歡迎到 我們的 Discord #background-agent 頻道 或寄信到 background-agent-feedback@cursor.com 提供回饋。也歡迎回報 bug、提出功能需求或分享點子。

​
設定

背景代理預設在隔離的 Ubuntu 基礎環境中執行。代理可連網，並且可以安裝套件。

​
GitHub 連線

後台代理會從 GitHub clone 你的 repo，並在獨立分支上作業，將變更 push 回你的 repo，方便交接。 請對你的 repo（以及任何相依的 repos 或 submodules）授予讀寫權限。未來我們也會支援其他供應商（GitLab、Bitbucket 等）。
IP 允許清單設定
如果你的組織使用 GitHub 的 IP 允許清單功能，你需要為背景代理設定存取權限。請參考 GitHub 整合文件，取得完整設定指南，包括聯絡方式與 IP 位址。

​
基礎環境設定

進階用法下，請自行設定環境。先讓 IDE 執行個體連上遠端機器。把你的機器設定好、安裝工具與套件，然後建立快照。再設定執行階段參數：
  • Install 指令會在代理啟動前執行，用來安裝執行階段相依性。可能需要跑 npm install 或 bazel build。
  • Terminals 會在代理工作時執行背景程序，例如啟動網頁伺服器或編譯 protobuf 檔案。
若是最進階的情境，使用 Dockerfile 進行機器設定。Dockerfile 允許你設定系統層級相依性：安裝特定版本的編譯器、除錯器，或切換基底作業系統映像。不要 COPY 整個專案——我們會管理工作區並檢出正確的提交（commit）。相依性的安裝仍然放在 install 腳本處理。 輸入開發環境所需的任何機密（secrets）——它們會在我們的資料庫中以靜態加密（使用 KMS）保存，並在背景代理的環境中提供。 機器設定位於 .cursor/environment.json，可以提交到你的 repo（建議）或私下保存。設定流程會引導你建立 environment.json。

​
維護指令

在設定新機器時，我們會從基礎環境開始，接著執行你在 environment.json 中的 install 指令。這個指令就是開發者在切換分支時會跑的——用來安裝任何新的相依套件。 對大多數人來說，install 指令就是 npm install 或 bazel build。 為了加快機器啟動，我們會在 install 指令跑完後快取磁碟狀態。請把它設計成可重複執行。只有 install 指令所產生的磁碟狀態會被保留——在這裡啟動的程序在代理程式啟動時不會持續存在。

​
啟動指令

執行 install 後，機器會啟動，接著我們會執行 start 指令，並啟動任何 terminals。這會啟動在代理執行時應常駐的程序。 start 指令通常可以省略。若你的開發環境依賴 Docker，請在 start 指令中加入 sudo service docker start。 terminals 是給應用程式程式碼用的。這些終端會在一個 tmux 工作階段中執行，供你和代理使用。比如，許多網站的程式庫會把 npm run watch 設為一個 terminal。

​
environment.json 規格

environment.json 檔案可以長這樣： 
{
  "snapshot": "POPULATED_FROM_SETTINGS",
  "install": "npm install",
  "terminals": [
    {
      "name": "Run Next.js",
      "command": "npm run dev"
    }
  ]
}
完整規格定義於此。

​
模型

只有支援 Max 模式 的模型可以用於背景代理。

​
價格

了解更多關於 Background Agent 的價格。

​
安全性

Background Agents 可在隱私模式中使用。我們絕不會用你的程式碼進行訓練，且只會在代理執行期間保留程式碼。進一步了解隱私模式。 你應該知道：
  1. 為想編輯的 repo 授予我們的 GitHub 應用程式讀寫權限。我們會用它來複製該 repo 並進行變更。
  2. 你的程式碼會在我們的 AWS 基礎架構內的隔離 VM 中執行，且在代理可存取期間儲存在 VM 磁碟上。
  3. 代理可存取網際網路。
  4. 代理會自動執行所有終端機指令，讓它能反覆執行測試。這與前景代理不同，前景代理需要使用者核准每個指令。自動執行會帶來資料外洩風險：攻擊者可能發動提示注入攻擊，誘使代理將程式碼上傳到惡意網站。請參考OpenAI 對背景代理提示注入風險的說明。
  5. 若停用隱私模式，我們會收集提示與開發環境資訊以改進產品。
  6. 如果在啟動背景代理時停用隱私模式，之後在代理執行期間再啟用，代理仍會維持隱私模式為停用狀態直到完成為止。

​
儀表板設定

工作區管理員可以在儀表板的 Background Agents 分頁中調整其他設定。

​
預設設定

  • 預設模型 – 在執行未指定模型時使用的模型。選擇任何支援 Max Mode 的模型。
  • 預設儲存庫 – 留空時，代理會請你選擇儲存庫。在這裡指定儲存庫就能跳過這個步驟。
  • 基礎分支 – 建立 pull request 時，代理會從這個分支分叉。留空則使用儲存庫的預設分支。

​
安全性設定

所有安全性選項都需要管理員權限。
  • 使用者限制 – 選擇 None（所有成員都能啟動背景代理）或 Allow list。設為 Allow list 時，你可以明確指定哪些隊友能建立代理。
  • 團隊後續訊息 – 開啟後，工作區內任何人都能替別人啟動的代理新增後續訊息。關閉則僅限代理擁有者與管理員可新增後續訊息。
  • 顯示代理摘要 – 控制 Cursor 是否顯示代理的檔案差異影像與程式碼片段。若不想在側邊欄曝光檔案路徑或程式碼，可停用此項。
  • 在外部頻道顯示代理摘要 – 將上述切換延伸到 Slack 或你連結的任何外部頻道。
變更會即時儲存，並立即套用到新建立的代理。