メインコンテンツへスキップ
バックグラウンドエージェントで、リモート環境上でコードを編集・実行する非同期エージェントを起動できる。ステータスを確認したり、追跡メッセージを送ったり、いつでも自分で引き継げる。

​
使い方

バックグラウンドエージェントには次の2通りでアクセスできる:
  1. Background Agent Sidebar: Cursor のネイティブサイドバーにある background agent タブで、アカウントに紐づくすべてのバックグラウンドエージェントを一覧表示し、既存のエージェントを検索したり、新しいエージェントを起動できる。
  2. Background Agent Mode: UI でバックグラウンドエージェントモードを有効化するには、 を押す。
プロンプトを送信したら、リストからエージェントを選んでステータスを確認し、マシンに入る。

バックグラウンドエージェントには、数日程度のデータ保持が必要。

​
セットアップ

バックグラウンドエージェントは、デフォルトで分離された Ubuntu ベースのマシン上で動作する。エージェントはインターネットにアクセスでき、パッケージをインストールできる。

​
GitHub 連携

バックグラウンドエージェントは GitHub からリポジトリをクローンし、別ブランチで作業して、スムーズに引き継げるようリポジトリにプッシュする。 リポジトリ（および依存リポジトリやサブモジュール）に読み取り/書き込み権限を付与してね。今後は他のプロバイダー（GitLab、Bitbucket など）にも対応予定。
IP許可リストの設定
組織でGitHubのIP許可リスト機能を使っている場合は、バックグラウンドエージェントへのアクセスを設定する必要があるよ。連絡先情報やIPアドレスを含む完全なセットアップ手順は、GitHub連携のドキュメントを確認してね。

​
ベース環境のセットアップ

高度なケースでは、自分で環境をセットアップしよう。リモートマシンに接続された IDE インスタンスを用意して、マシンをセットアップし、ツールやパッケージをインストールしてからスナップショットを取得。実行時設定を構成する:
  • Install コマンドはエージェントが起動する前に実行され、ランタイム依存関係をインストールする。これは npm install や bazel build を走らせることを意味する場合がある。
  • Terminals は、エージェントが動作している間にバックグラウンドプロセスを実行する—たとえば、Web サーバーの起動や protobuf ファイルのコンパイルなど。
さらに高度なケースでは、マシンセットアップに Dockerfile を使おう。Dockerfile ならシステムレベルの依存関係をセットアップできる: 特定のコンパイラやデバッガのバージョンを入れる、ベース OS イメージを切り替える、など。プロジェクト全体を COPY しないで—ワークスペース管理と正しいコミットのチェックアウトはこっちでやる。依存関係のインストールは引き続き install スクリプトで扱って。 開発環境に必要なシークレットを入力してね—それらはデータベース内で KMS を使って暗号化保存され、バックグラウンドのエージェント環境に渡される。 マシンセットアップは .cursor/environment.json にあり、リポジトリにコミット（推奨）することも、プライベートに保存することもできる。セットアップフローが 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 をターミナルとして設定してる。

​
environment.json の仕様

environment.json ファイルは次のようになるよ: 
{
  "snapshot": "POPULATED_FROM_SETTINGS",
  "install": "npm install",
  "terminals": [
    {
      "name": "Next.js を起動"
      "command": "npm run dev"
    }
  ]
}
形式仕様はこちらで定義されている。

​
モデル

バックグラウンドエージェントで使えるのは、Max Mode 対応のモデルだけ。

​
料金

Background Agent の料金について詳しく見る。

​
セキュリティ

Background Agents は Privacy Mode で利用できる。コードを学習に使うことは絶対にないし、エージェントの実行に必要な範囲でしかコードは保持しない。Privacy Mode の詳細 知っておいてほしいこと:
  1. 編集したいリポジトリには、GitHub アプリに読み書き権限を付与してね。これを使ってリポジトリをクローンして変更するよ。
  2. コードは AWS 上の分離された VM 内で実行され、エージェントが動作している間は VM のディスクに保存される。
  3. エージェントはインターネットにアクセスできる。
  4. エージェントはすべてのターミナルコマンドを自動実行し、テストを反復できる。これは、すべてのコマンドにユーザー承認が必要な foreground agent とは異なる。自動実行にはデータ流出リスクがある—攻撃者が prompt injection 攻撃でエージェントを欺き、悪意あるサイトにコードをアップロードさせる可能性がある。background agents に対する prompt injection のリスクに関する OpenAI の説明を参照。
  5. Privacy Mode を無効にしている場合、プロダクト改善のためにプロンプトと開発環境情報を収集する。
  6. background agent の起動時に Privacy Mode を無効にして、その実行中に有効に切り替えても、エージェントは完了するまで Privacy Mode 無効のまま動作し続ける。

​
ダッシュボード設定

Workspace の管理者は、ダッシュボードの Background Agents タブから追加の設定を行えるよ。

​
デフォルト設定

  • Default model – 実行時にモデルが指定されていない場合に使われるモデル。Max Mode をサポートしている任意のモデルを選んでね。
  • Default repository – 空の場合、エージェントがリポジトリの選択をユーザーに促す。ここでリポジトリを指定しておくと、そのステップをスキップできるよ。
  • Base branch – プルリクエスト作成時にエージェントがフォーク元として使うブランチ。空のままにすると、そのリポジトリのデフォルトブランチが使われるよ。

​
セキュリティ設定

すべてのセキュリティオプションは管理者権限が必要。
  • ユーザー制限 – なし（全メンバーがバックグラウンドエージェントを起動可能）か 許可リスト を選択。許可リスト の場合、エージェントを作成できるメンバーを正確に指定できる。
  • チームのフォローアップ – 有効にすると、ワークスペース内の誰でも他のメンバーが開始したエージェントにフォローアップメッセージを追加できる。無効にすると、フォローアップはエージェントの所有者と管理者に限定される。
  • エージェント概要の表示 – Cursor がエージェントのファイル差分イメージやコードスニペットを表示するかどうかを制御。サイドバーでファイルパスやコードを表示したくない場合は無効化する。
  • 外部チャンネルでエージェント概要を表示 – 上記のトグルを、接続済みの Slack などの外部チャンネルにも適用。
変更は即時に保存され、新しいエージェントにすぐ反映される。