백그라운드 에이전트를 쓰면 원격 환경에서 코드를 편집하고 실행하는 비동기 에이전트를 띄울 수 있어. 상태를 확인하고, 후속 작업을 보내거나, 언제든 직접 개입해서 이어서 진행할 수 있어.

​
사용 방법

백그라운드 에이전트에 액세스하는 방법은 두 가지야:
  1. Background Agent Sidebar: 네이티브 Cursor 사이드바의 백그라운드 에이전트 탭에서 계정에 연결된 모든 백그라운드 에이전트를 확인하고, 기존 에이전트를 검색하고, 새로 시작할 수 있어.
  2. Background Agent Mode: UI에서 백그라운드 에이전트 모드를 호출하려면 를 눌러.
프롬프트를 제출한 다음, 목록에서 에이전트를 선택해 상태를 확인하고 머신에 진입해.

백그라운드 에이전트는 며칠간의 데이터 보존이 필요해.

​
피드백

Discord의 #background-agent 채널이나 background-agent-feedback@cursor.com로 피드백 보내줘. 버그, 기능 요청, 아이디어 전부 환영이야.

​
설정

Background agents는 기본적으로 격리된 Ubuntu 기반 머신에서 실행돼. 에이전트는 인터넷에 접근할 수 있고 패키지를 설치할 수 있어.

​
GitHub 연결

Background agents는 GitHub에서 네 리포를 클론해서 별도 브랜치로 작업하고, 핸드오프가 쉽도록 네 리포에 푸시해. 네 리포(그리고 의존 리포나 서브모듈)에 읽기/쓰기 권한을 부여해 줘. 앞으로 다른 제공자(GitLab, BitBucket 등)도 지원할 예정이야.
IP 허용 목록 구성
조직에서 GitHub의 IP 허용 목록 기능을 사용한다면, background agents에 대한 접근을 따로 설정해야 해. 연락처 정보와 IP 주소를 포함한 전체 설정 방법은 GitHub 통합 문서를 확인해.

​
기본 환경 설정

고급 케이스에선 환경을 직접 구성할 수 있어. 원격 머신에 연결된 IDE 인스턴스를 띄우고, 네 머신을 세팅한 다음 도구와 패키지를 설치하고 스냅샷을 찍어. 런타임 설정을 이렇게 구성해:
  • install 커맨드는 에이전트가 시작되기 전에 실행돼서 런타임 의존성을 설치해. npm install이나 bazel build를 실행하는 걸 의미할 수 있어.
  • terminals는 에이전트가 작업하는 동안 백그라운드 프로세스를 돌려 — 예를 들어 웹 서버를 시작하거나 protobuf 파일을 컴파일하는 식이야.
가장 고급 케이스에선 머신 설정에 Dockerfile을 사용해. Dockerfile로 시스템 수준 의존성을 설정할 수 있어: 특정 컴파일러 버전이나 디버거를 설치하거나 베이스 OS 이미지를 바꿀 수 있어. 프로젝트 전체를 COPY하진 마 — 우리가 워크스페이스를 관리하고 올바른 커밋을 체크아웃해. 의존성 설치는 여전히 install 스크립트에서 처리해. 개발 환경에 필요한 시크릿을 입력해 — 우리 데이터베이스에 암호화-at-rest(KMS 사용)로 저장되고 background agent 환경에 제공돼. 머신 설정은 .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": "Run Next.js",
      "command": "npm run dev"
    }
  ]
}
정식 스펙은 여기에 정의돼 있어.

​
모델

백그라운드 에이전트에서는 Max Mode 호환 모델만 쓸 수 있어.

​
요금제

Background Agent 요금에 대해 더 알아봐.

​
Security

Background Agents는 Privacy Mode에서 사용할 수 있어. 우린 네 코드를 학습에 절대 사용하지 않고, 에이전트를 실행하는 데에만 코드를 보관해. Privacy Mode에 대해 더 알아보기. 알아두면 좋은 점:
  1. 수정하려는 repo에 우리 GitHub 앱의 읽기-쓰기 권한을 부여해줘. 이걸로 repo를 클론하고 변경을 적용해.
  2. 네 코드는 우리 AWS 인프라의 격리된 VM에서 실행되고, 에이전트가 접근 가능한 동안 VM 디스크에 저장돼.
  3. 에이전트는 인터넷에 접근할 수 있어.
  4. 에이전트는 모든 터미널 명령을 자동으로 실행해서 테스트를 반복할 수 있게 해. 이건 매 명령마다 사용자 승인이 필요한 foreground agent와 달라. 자동 실행은 데이터 유출 위험을 초래할 수 있어: 공격자가 프롬프트 인젝션을 통해 에이전트를 속여 악성 웹사이트로 코드를 업로드하게 만들 수 있어. Background agents에서 프롬프트 인젝션 위험에 대한 OpenAI의 설명을 참고해.
  5. Privacy Mode가 비활성화되어 있으면, 제품 개선을 위해 프롬프트와 개발 환경 정보를 수집해.
  6. Background agent를 시작할 때 Privacy Mode를 끈 다음 실행 중에 켜더라도, 에이전트는 완료될 때까지 Privacy Mode가 비활성화된 상태로 계속 진행돼.