使用背景代理，在遠端環境中啟動非同步代理來編輯與執行程式碼。你可以查看它們的狀態、補充指示，或隨時接手操作。

​
如何使用

你可以透過兩種方式使用背景代理：
  1. Background Agent Sidebar：在原生 Cursor 側邊欄的 background agent 分頁中，查看帳號下的所有背景代理、搜尋現有代理，並啟動新的代理。
  2. Background Agent Mode：按下 以在介面中啟用背景代理模式。
提交提示後，從清單中選擇你的代理以查看狀態並進入機器。

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

​
意見回饋

歡迎在 我們的 Discord #background-agent 頻道 或寄信至 background-agent-feedback@cursor.com 提出意見。可以回報 bug、提功能需求，或分享任何點子。

​
設定

Background agents 預設在隔離的 ubuntu 基底機器上執行。Agents 具備網路存取能力，並可安裝套件。

​
GitHub 連線

Background agents 會從 GitHub 將你的 repo clone 下來，在獨立分支上作業，並 push 回你的 repo，方便交接。 授予你的 repo（以及任何相依的 repos 或 submodules）讀寫權限。未來我們也會支援其他提供者（GitLab、BitBucket 等）。
IP Allow List 設定
如果你的組織使用 GitHub 的 IP allow list 功能，你需要為 background agents 設定存取權。完整的設定說明（包含聯絡資訊與 IP 位址）請參考 GitHub integration documentation。

​
基礎環境設定

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

​
維護指令

在設定新機器時，我們會從基礎環境開始，接著執行你 environment.json 裡的 install 指令。這個指令就像開發者在切換分支時會執行的步驟——用來安裝任何新的相依套件。 對多數人而言，install 指令就是 npm install 或 bazel build。 為了確保機器快速啟動，我們會在 install 指令執行後快取磁碟狀態。請將它設計為可重複執行。只有 install 指令產生的磁碟狀態會被保留——在這裡啟動的程序不會在 agent 啟動時存活。

​
啟動指令

執行完 install 之後，機器會啟動，然後我們會先執行 start 指令，再啟動任何 terminals。這會啟動在 agent 執行時需要持續運作的程序。 start 指令通常可以省略。如果你的開發環境仰賴 docker，就把 sudo service docker start 放到 start 指令裡。 terminals 是給 app 程式碼用的。這些 terminals 會在一個你與 agent 都可使用的 tmux 工作階段中執行。舉例來說，許多網站 repos 會把 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 Mode 的模型能用於背景代理。

​
訂價

進一步了解 Background Agent 的訂價。

​
安全性

Background Agents 可在隱私模式下使用。我們絕不會用你的程式碼訓練模型，且只會為了執行代理而暫存程式碼。深入了解隱私模式。 你應該知道：
  1. 為你想編輯的 repo，替我們的 GitHub app 授予讀寫權限。我們會用它來 clone 該 repo 並進行變更。
  2. 你的程式碼會在我們的 AWS 基礎設施內、隔離的 VM 中執行，並在代理可用期間儲存在 VM 磁碟上。
  3. 代理可存取網際網路。
  4. 代理會自動執行所有終端機指令，讓它能迭代跑測試。這和前景代理不同，前景代理每個指令都需要使用者同意。自動執行帶來資料外洩風險：攻擊者可能發動提示注入攻擊，誘使代理把程式碼上傳到惡意網站。參見 OpenAI 對背景代理提示注入風險的說明。
  5. 如果關閉隱私模式，我們會收集提示和開發環境資料，用來改進產品。
  6. 如果在啟動背景代理時關閉隱私模式，之後在代理執行期間再啟用，代理仍會維持隱私模式關閉直到完成。