Pular para o conteúdo principal
Com background agents, cria agentes assíncronos que editam e executam código em um ambiente remoto. Acompanha o status deles, envia 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 Agente em Segundo Plano: Use a aba de agente em segundo plano na barra lateral nativa do Cursor para ver todos os agentes em segundo plano associados à sua conta, buscar agentes existentes e iniciar novos.
  2. Modo de Agente em Segundo Plano: Pressione para ativar o modo de agente em segundo plano na interface.
Depois de enviar um prompt, selecione seu agente na lista para ver o status e entrar na máquina.

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

​
Configuração

Agentes em segundo plano são executados, por padrão, em uma máquina isolada baseada em Ubuntu. Eles têm acesso à internet e podem instalar pacotes.

​
Conexão com o GitHub

Agentes em segundo plano clonam teu repositório do GitHub e trabalham em um branch separado, fazendo push para teu repositório para facilitar a passagem. Concede privilégios de leitura e escrita ao teu repositório (e a quaisquer repositórios dependentes ou submódulos). No futuro, vamos dar 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 precisar configurar o acesso para os agentes em segundo plano. Consulta a documentação de integração do GitHub para instruções completas de configuração, incluindo informações de contato e endereços IP.

​
Configuração de ambiente base

Para casos avançados, configura o ambiente por conta própria. Conecta uma instância do IDE à máquina remota. Configura tua máquina, instala ferramentas e pacotes e, depois, cria um snapshot. Configura as definições de runtime:
  • O comando de instalação roda antes de o agente iniciar e instala as 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 pra configurar 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 usa COPY pro projeto inteiro — a gente gerencia o workspace e faz checkout do commit correto. Ainda assim, mantém a instalação de dependências no script de instalação. Insere quaisquer segredos necessários pro teu ambiente de dev — eles ficam armazenados criptografados em repouso (usando KMS) no nosso banco de dados e são 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 máquina nova, começamos pelo ambiente base e depois executamos o comando install do teu environment.json. Esse comando é o que um desenvolvedor executaria ao trocar de branch — instalar quaisquer novas dependências. Para a maioria das pessoas, o comando install é npm install ou bazel build. Para garantir uma inicialização rápida da máquina, armazenamos em cache o estado do disco depois que o comando install roda. Projeta-o para rodar várias vezes. Apenas o estado do disco persiste a partir do comando install — processos iniciados aqui não estarão em execução quando o agente começar.

​
Comandos de Inicialização

Depois de rodar install, a máquina inicia e a gente executa o comando start e depois inicia quaisquer terminals. Isso levanta processos que precisam estar ativos quando o agente for executado. O comando start muitas vezes pode ser pulado. Usa ele se teu ambiente de dev depende do 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 ti 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": "Rodar Next.js",
      "command": "npm run dev"
    }
  ]
}
Formalmente, a especificação é definida aqui.

​
Modelos

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

​
Preços

Saiba mais sobre os preços do Background Agent.

​
Segurança

Background Agents estão disponíveis no Modo de Privacidade. A gente nunca treina com teu código e só mantém o código pelo tempo necessário pra executar o agente. Saiba mais sobre o Modo de Privacidade. O que tu precisa saber:
  1. Concede privilégios de leitura e escrita pro 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 da VM 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 foreground, que exige aprovação do usuário pra cada comando. A execução automática introduz risco de exfiltração de dados: atacantes podem executar ataques de prompt injection, induzindo o agente a enviar código pra sites maliciosos. Vê a explicação da OpenAI sobre riscos de prompt injection pra agentes em background.
  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 agente em background 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 definiçõ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 tu escolher um repositório. Fornecer um repositório aqui deixa tu pular essa etapa.
  • Branch base – a branch a partir 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 Nenhuma (todos os membros podem iniciar agentes em segundo plano) ou Lista de permissão. Quando definido como Lista de permissão, você especifica exatamente quais colegas podem criar agentes.
  • Follow-ups da equipe – quando ativado, qualquer pessoa no workspace pode adicionar mensagens de follow-up a um agente iniciado por outra pessoa. Desativa isso para restringir os follow-ups ao dono do agente e aos admins.
  • Exibir resumo do agente – controla se o Cursor mostra as imagens de diff de arquivos e trechos de código do agente. Desativa isso se preferir não expor caminhos de arquivo ou código na barra lateral.
  • Exibir resumo do agente em canais externos – estende o toggle anterior para o Slack ou qualquer canal externo que você conectou.
As mudanças são salvas instantaneamente e afetam novos agentes imediatamente.