バックグラウンドエージェント

Cursor の非同期リモートエージェント

バックグラウンドエージェントを使えば、リモート環境でコードを編集・実行する非同期エージェントを起動できる。ステータスを確認したり、フォローアップを送ったり、いつでも引き継いで操作できる。

使い方

バックグラウンドエージェントには次の2つの方法でアクセスできるよ:

1. Background Agent Sidebar: ネイティブの Cursor サイドバーにある background agent タブから、アカウントに紐づくすべてのバックグラウンドエージェントの確認、既存エージェントの検索、新規エージェントの起動ができる。
2. Background Agent Mode: UI でバックグラウンドエージェントモードを起動するには、Ctrl+E を押す。

プロンプトを送信したら、リストからエージェントを選んでステータスを確認し、マシンに入ろう。

バックグラウンドエージェントは数日程度のデータ保持を必要とするよ。

セットアップ

バックグラウンドエージェントは、デフォルトで分離された 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 に依存しているなら使ってOK—start コマンドに sudo service docker start を入れておこう。

terminals はアプリ用のコマンド。これらのターミナルは、きみとエージェントが使える tmux セッションで動く。たとえば、多くの Web サイトのリポジトリでは、ターミナルに npm run watch を設定している。

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. 編集したいリポジトリには、うちの GitHub アプリに読み書き権限を付与してね。これを使ってリポジトリをクローンして変更するよ。
2. コードは AWS のインフラ上にある分離された VM 内で実行され、エージェントが利用可能な間は VM のディスクに保存されるよ。
3. エージェントはインターネットにアクセスできるよ。
4. エージェントはすべてのターミナルコマンドを自動実行して、テストを繰り返し回せるようにしてる。これは、毎回ユーザーの承認が必要なフォアグラウンドエージェントとは異なる点だよ。自動実行にはデータ流出のリスクがある—攻撃者がプロンプトインジェクション攻撃を仕掛け、エージェントをだまして悪意あるサイトにコードをアップロードさせる可能性がある。バックグラウンドエージェントにおけるプロンプトインジェクションのリスクに関する OpenAI の説明を見てね。
5. プライバシーモードが無効な場合、プロダクト改善のためにプロンプトと開発環境の情報を収集するよ。
6. バックグラウンドエージェントの起動時にプライバシーモードを無効にして、その実行中に有効へ切り替えても、完了するまでは無効のまま動作するよ。

ダッシュボード設定

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

既定の設定

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

セキュリティ設定

すべてのセキュリティオプションは管理者権限が必要。

• ユーザー制限 – None（全メンバーがバックグラウンドエージェントを起動できる）または Allow list を選ぶ。Allow list にすると、どのチームメイトがエージェントを作成できるかを正確に指定できる。
• チームのフォローアップ – オンにすると、ワークスペース内の誰でも他の人が起動したエージェントにフォローアップメッセージを追加できる。オフにすると、フォローアップはエージェントの所有者と管理者に限定される。
• エージェント概要の表示 – Cursor がエージェントのファイル差分イメージとコードスニペットを表示するかどうかを制御する。サイドバーでファイルパスやコードを表示したくない場合は無効にする。
• 外部チャンネルでエージェント概要を表示 – 前項のトグルを Slack など接続済みの外部チャンネルにも適用する。

変更は即時に保存され、新しいエージェントにすぐ反映される。