跳轉到主要內容
使用 background agents，在遠端環境中啟動非同步代理來編輯和執行程式碼。隨時查看它們的狀態、發送後續指示，或直接接手。

​
如何使用

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

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

​
設定

Background agents 會在預設的隔離式 Ubuntu 基礎機器上執行。這些代理具備網路連線能力，並可安裝套件。

​
GitHub 連線

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

​
基礎環境設定

進階情境下，自己動手設定環境。先準備一個連到遠端機器的 IDE 執行個體。把你的機器設好、安裝工具和套件，然後建立快照。接著設定執行階段參數：
  • Install 指令會在代理啟動前執行，用來安裝執行階段相依項。這可能是跑 npm install 或 bazel build。
  • Terminals 會在代理運作時執行背景程序——例如啟動網頁伺服器或編譯 protobuf 檔案。
在最進階的情境，使用 Dockerfile 來做機器設定。Dockerfile 讓你設定系統層級相依：安裝特定版本的編譯器、除錯器，或更換基底作業系統映像。不要 COPY 整個專案——我們會管理工作區並檢出正確的 commit。相依安裝還是放在 install 指令的腳本裡處理。 輸入開發環境需要的任何機密——這些會以靜態加密（使用 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 工作階段中執行，供你和代理使用。比如，很多網站的 repo 會把 npm run watch 放在一個 terminal 裡。

​
environment.json 規格

environment.json 檔案可能長這樣： 
{
  "snapshot": "從設定載入"
  "install": "npm install"
  "terminals": [
    {
      "name": "執行 Next.js"
      "command": "npm run dev"
    }
  ]
}
正式來說，這份規格定義在這裡。

​
模型

只有支援 Max Mode 的模型能用於背景代理。

​
價格

進一步了解 Background Agent 的價格。

​
安全性

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

​
儀表板設定

Workspace 管理員可以在儀表板的 Background Agents 分頁中設定其他選項。

​
預設設定

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

​
安全性設定

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