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.
I