Com agentes em segundo plano, cria agentes assíncronos que editam e executam código em um ambiente remoto. Vê o status deles, manda follow-ups ou assume o controle a qualquer momento.

​
Como usar

Você pode acessar agentes em segundo plano de duas maneiras:
  1. Barra lateral de Agentes em Segundo Plano: Usa a guia de agentes em segundo plano na barra lateral nativa do Cursor pra ver todos os agentes em segundo plano associados à tua conta, pesquisar agentes existentes e iniciar novos.
  2. Modo Agente em Segundo Plano: Aperta pra ativar o modo de agente em segundo plano na interface.
Depois de enviar um prompt, seleciona teu agente na lista pra ver o status e entrar na máquina.

Agentes em segundo plano exigem retenção de dados por alguns dias.

​
Feedback

Manda teu feedback no nosso canal do Discord #background-agent ou para background-agent-feedback@cursor.com. Pode enviar bugs, pedidos de feature ou ideias.

​
Configuração

Agents em background rodam, por padrão, em uma máquina isolada baseada em Ubuntu. Eles têm acesso à internet e podem instalar pacotes. ---MDX_CONTENTEND---

​
Conexão com o GitHub

Agentes em segundo plano clonam teu repositório no GitHub e trabalham em um branch separado, fazendo push para o teu repositório para facilitar a entrega. Concede privilégios de leitura e escrita ao teu repositório (e a quaisquer repositórios dependentes ou submódulos). No futuro, vamos oferecer suporte a outros provedores (GitLab, Bitbucket, etc.).
Configuração da lista de IPs permitidos
Se tua organização usa o recurso de lista de IPs permitidos do GitHub, vai ser preciso configurar o acesso para os agentes em background. Consulta a documentação da integração com o GitHub para instruções completas de configuração, incluindo informações de contato e endereços de IP.

​
Configuração de Ambiente Base

Para casos avançados, configura o ambiente tu mesmo. Conecta uma instância do IDE à máquina remota. Prepara tua máquina, instala ferramentas e pacotes, depois tira um snapshot. Configura as definições de runtime:
  • O comando de instalação roda antes de o agente iniciar e instala dependências de runtime. Isso pode significar rodar npm install ou bazel build.
  • Terminais executam processos em segundo plano enquanto o agente trabalha — como iniciar um servidor web ou compilar arquivos protobuf.
Para os casos mais avançados, usa um Dockerfile para preparar a máquina. O Dockerfile permite configurar dependências em nível de sistema: instalar versões específicas de compiladores, depuradores ou trocar a imagem base do SO. Não dá COPY no projeto inteiro — a gente gerencia o workspace e faz checkout do commit correto. Ainda trata a instalação de dependências no script de instalação. Insere quaisquer segredos necessários para teu ambiente de desenvolvimento — eles ficam armazenados com criptografia em repouso (usando KMS) no nosso banco de dados e fornecidos no ambiente do agente em segundo plano. A configuração da máquina fica em .cursor/environment.json, que pode ser commitada no teu repositório (recomendado) ou armazenada de forma privada. O fluxo de configuração te guia na criação do environment.json.

​
Comandos de manutenção

Ao configurar uma nova máquina, a gente começa pelo ambiente base e depois executa o comando install do teu environment.json. Esse comando é o que devs executariam ao trocar de branch — instalar quaisquer dependências novas. Pra maioria das pessoas, o comando install é npm install ou bazel build. Pra garantir uma inicialização rápida da máquina, a gente faz cache do estado do disco depois que o comando install roda. Projeta ele pra rodar várias vezes. Só o estado do disco persiste a partir do comando install — processos iniciados aqui não vão estar ativos quando o agente iniciar.

​
Comandos de inicialização

Depois de executar install, a máquina inicia e a gente roda o comando start, seguido de iniciar quaisquer terminals. Isso inicia processos que devem estar ativos quando o agente estiver rodando. O comando start muitas vezes pode ser pulado. Usa ele se teu ambiente de dev depende de Docker — coloca sudo service docker start no comando start. terminals são para o código do app. Esses terminais rodam numa sessão tmux disponível pra você e pro agente. Por exemplo, muitos repositórios de sites colocam npm run watch como um terminal.

​
A especificação de environment.json

O arquivo environment.json pode ser assim: 
{
  "snapshot": "POPULATED_FROM_SETTINGS",
  "install": "npm install",
  "terminals": [
    {
      "name": "Executar Next.js",
      "command": "npm run dev"
    }
  ]
}
Formalmente, a especificação está definida aqui.

​
Modelos

Somente modelos compatíveis com o Max Mode estão disponíveis para agentes em segundo plano.

​
Preços

Saiba mais sobre a precificação do Background Agent.

​
Segurança

Background Agents estão disponíveis no modo de privacidade. A gente nunca treina com o teu código e só retém o código para executar o agente. Saiba mais sobre o modo de privacidade. O que você precisa saber:
  1. Concede privilégios de leitura e escrita ao nosso app do GitHub nos repositórios que tu quer editar. A gente usa isso pra clonar o repo e fazer alterações.
  2. Teu código roda na nossa infraestrutura da AWS em VMs isoladas e fica armazenado nos discos das VMs enquanto o agente estiver ativo.
  3. O agente tem acesso à internet.
  4. O agente executa automaticamente todos os comandos de terminal, permitindo iterar nos testes. Isso difere do agente em primeiro plano, que exige aprovação do usuário pra cada comando. A execução automática traz risco de exfiltração de dados: invasores podem realizar ataques de prompt injection, enganando o agente a enviar código pra sites maliciosos. Veja a explicação da OpenAI sobre riscos de prompt injection para background agents.
  5. Se o modo de privacidade estiver desativado, a gente coleta prompts e ambientes de desenvolvimento pra melhorar o produto.
  6. Se tu desativar o modo de privacidade ao iniciar um background agent e depois ativar durante a execução, o agente continua com o modo de privacidade desativado até concluir.

​
Configurações do dashboard

Admins do workspace podem configurar opções adicionais na aba Background Agents do dashboard.

​
Configurações padrão

  • Modelo padrão – o modelo usado quando uma execução não especifica um. Escolhe qualquer modelo que suporte o Max Mode.
  • Repositório padrão – quando vazio, os agentes pedem pra você escolher um repo. Informar um repo aqui permite pular essa etapa.
  • Branch base – a branch da qual os agentes fazem fork ao criar pull requests. Deixa em branco pra usar a branch padrão do repositório.

​
Configurações de segurança

Todas as opções de segurança exigem privilégios de admin.
  • Restrições de usuário – escolhe entre Nenhuma (todos os membros podem iniciar agentes em segundo plano) ou Lista de permitidos. Quando definido como Lista de permitidos, tu especifica exatamente quais colegas podem criar agentes.
  • Acompanhamentos da equipe – quando ligado, qualquer pessoa no workspace pode adicionar mensagens de acompanhamento a um agente iniciado por outra pessoa. Desliga para restringir acompanhamentos ao dono do agente e admins.
  • Exibir resumo do agente – controla se o Cursor mostra as imagens de diff de arquivos e trechos de código do agente. Desliga se preferir não expor caminhos de arquivos ou código na barra lateral.
  • Exibir resumo do agente em canais externos – estende a opção anterior para o Slack ou qualquer canal externo conectado.
As alterações são salvas instantaneamente e afetam novos agentes imediatamente.