Background agents を使うと、リモート環境でコードを編集・実行する非同期エージェントを起動できるよ。ステータスを確認したり、追加入力を送ったり、いつでも引き継いで操作できるよ。

使い方

バックグラウンドエージェントには次の2つの方法でアクセスできるよ:
  1. Background Agent Sidebar: ネイティブの Cursor サイドバーにある background agent タブから、アカウントに紐づくすべてのバックグラウンドエージェントの確認、既存エージェントの検索、新規作成ができる。
  2. Background Agent Mode: UIでバックグラウンドエージェントモードを起動するには、 を押す。
プロンプトを送信したら、リストからエージェントを選んでステータスを確認し、マシンに入ってね。

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

フィードバック

フィードバックは Discord の #background-agent チャンネルbackground-agent-feedback@cursor.com まで送ってね。バグ報告、機能リクエスト、アイデアも待ってるよ。

セットアップ

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

GitHub 接続

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

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

より高度なケースでは、自分で環境をセットアップしよう。リモートマシンに接続された IDE インスタンスを用意して、マシンをセットアップし、ツールやパッケージをインストールしてからスナップショットを作成。実行時設定を構成する:
  • install コマンドはエージェントの起動前に走り、ランタイム依存関係をインストールする。例えば npm installbazel build を実行することになるかも。
  • terminals はエージェントの作業中にバックグラウンドプロセスを走らせる—Web サーバーの起動や protobuf ファイルのコンパイルなど。
さらに高度なケースでは、マシンのセットアップに Dockerfile を使おう。Dockerfile ならシステムレベルの依存関係をセットアップできる:特定のコンパイラバージョンやデバッガのインストール、ベース OS イメージの切り替えなど。プロジェクト全体を COPY しないで—ワークスペース管理と正しいコミットのチェックアウトはこっちでやる。依存関係のインストールは引き続き install スクリプトで処理してね。 開発環境に必要なシークレットはここで入力してね—それらはデータベースに保存される際に(KMS を使って)保存時暗号化され、バックグラウンドエージェントの環境に提供される。 マシンのセットアップ定義は .cursor/environment.json に置く。これはリポジトリにコミットしても(推奨)、非公開で保存してもいい。セットアップフローで environment.json の作成をガイドする。

メンテナンスコマンド

新しいマシンをセットアップする際は、まずベース環境から始め、その後 environment.jsoninstall コマンドを実行する。このコマンドは、開発者がブランチを切り替えるときに走らせるもの—新しい依存関係をインストールする。 ほとんどの場合、install コマンドは npm installbazel build マシンの起動を速くするため、install コマンド実行後のディスク状態をキャッシュする。何度実行しても問題ないように設計してね。永続化されるのは install コマンド後のディスク状態だけ—ここで起動したプロセスは、エージェントが開始する時点では生きていない。

スタートアップコマンド

install の実行後、マシンが起動し、start コマンドを実行してから任意の terminals を起動する。これは、エージェント実行時に生きているべきプロセスを立ち上げる。 start コマンドは省略できることが多い。開発環境が Docker に依存しているなら使って—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. キミのコードは、分離された VM 上で動く AWS インフラ内で実行され、エージェントが利用可能な間は VM のディスクに保存される。
  3. エージェントはインターネットにアクセスできる。
  4. エージェントはすべてのターミナルコマンドを自動実行して、テストを反復できるよ。これは各コマンドごとにユーザー承認が必要なフォアグラウンドエージェントとは異なる。自動実行にはデータ流出リスクがある。攻撃者がプロンプトインジェクション攻撃でエージェントをだまし、悪意あるサイトにコードをアップロードさせる可能性がある。バックグラウンドエージェントにおけるプロンプトインジェクションのリスクに関する OpenAI の説明を参照してね。
  5. プライバシーモードが無効な場合、プロダクト改善のためにプロンプトと開発環境の情報を収集するよ。
  6. バックグラウンドエージェントを起動するときにプライバシーモードを無効にし、その後の実行中に有効化しても、完了するまでは無効のままで動作し続けるよ。