Configurando e Usando Subagentes no Cursor

Subagentes no Cursor permitem que você decomponha tarefas complexas em unidades menores e especializadas que podem ser executadas em paralelo ou em sequência. Um agente planejador orquestra a tarefa geral enquanto os subagentes lidam com subtarefas específicas com seus próprios modelos, escopos e limites de segurança. Este guia cobre tudo, desde seleção de modelos até configuração de segurança, ajudando você a construir fluxos de trabalho multi-agente robustos.

Compreendendo Subagentes

O Que São Subagentes?

Subagentes são instâncias de agente independentes que operam sob a direção de um agente planejador. Cada subagente pode ter seu próprio:

• Modelo: Diferentes modelos de IA para diferentes tipos de tarefas
• Escopo: Acesso restrito a arquivos e diretórios
• Limites de segurança: Restrições sobre quais ações podem realizar
• Contexto: Janela de contexto isolada para evitar interferência

O agente planejador decompõe uma tarefa complexa, atribui subtarefas aos subagentes, coleta seus resultados e sintetiza uma saída final. Esta arquitetura espelha como equipes humanas dividem o trabalho entre especialistas.

Quando Usar Subagentes

Subagentes brilham em cenários onde um único agente teria dificuldade com a amplitude ou complexidade de uma tarefa:

• Grande refatoração abrangendo múltiplos módulos
• Implementação de um recurso que requer mudanças tanto no frontend quanto no backend
• Executar testes, corrigir bugs e atualizar documentação simultaneamente
• Revisão de código em múltiplos repositórios
• Gerar e validar mudanças de código em paralelo

dica

Para tarefas simples de arquivo único, uma arquitetura de subagentes adiciona sobrecarga sem benefício. Use subagentes quando a tarefa se divide naturalmente em subtarefas independentes ou semi-independentes. Se você consegue descrever a tarefa em uma frase, você provavelmente não precisa de subagentes.

Seleção de Modelos

Escolhendo Modelos para Planejador vs. Subagentes

Uma das decisões mais importantes em uma configuração de subagentes é qual modelo atribuir ao planejador e qual atribuir aos subagentes. Diferentes modelos têm diferentes pontos fortes, custos e características de velocidade.

Modelos Disponíveis

Modelo	Pontos Forttes	Velocidade	Custo	Ideal Para
cursor-pro	Raciocínio e velocidade equilibrados	Médio	Médio	Planejador, tarefas gerais
cursor-fast	Iteração rápida, tarefas simples	Rápido	Baixo	Subagentes simples
cursor-max	Raciocínio profundo, lógica complexa	Lento	Alto	Subagentes complexos
cursor-think	Raciocínio estendido, arquitetura	Mais lento	Mais alto	Planejador para tarefas complexas

Configuração

Configure as atribuições de modelos nas configurações do Cursor ou na configuração do projeto:

// Em settings.json
{
  "cursor.subagents.enabled": true,
  "cursor.subagents.plannerModel": "cursor-pro",
  "cursor.subagents.defaultModel": "cursor-fast",
  "cursor.subagents.maxConcurrent": 4,
  "cursor.subagents.timeout": 300000
}

Configuração de Modelo por Subagente

Você pode atribuir diferentes modelos a diferentes subagentes com base em sua tarefa:

# .cursor/subagents/config.yaml
planner:
  model: cursor-pro
  description: "Orchestrates the overall task and synthesizes results"
  maxSubagents: 5

subagents:
  - name: "frontend-agent"
    model: cursor-max
    description: "Handles React component changes"
    scope:
      files: ["src/components/**", "src/pages/**"]
    tools: ["read", "write", "edit"]

  - name: "backend-agent"
    model: cursor-max
    description: "Handles API and server logic"
    scope:
      files: ["src/api/**", "src/server/**", "src/models/**"]
    tools: ["read", "write", "edit", "terminal"]

  - name: "test-agent"
    model: cursor-fast
    description: "Writes and runs tests"
    scope:
      files: ["test/**", "src/**/*.test.*"]
    tools: ["read", "write", "terminal"]

  - name: "docs-agent"
    model: cursor-fast
    description: "Updates documentation"
    scope:
      files: ["docs/**", "README.md", "CHANGELOG.md"]
    tools: ["read", "write"]

dica

Use um modelo poderoso como cursor-max para subagentes que lidam com lógica complexa ou caminhos de código críticos. Use cursor-fast para tarefas mais simples como formatação, documentação ou execução de comandos predefinidos. Isso equilibra custo e qualidade de forma eficaz.

Melhores Práticas de Seleção de Modelos

Ao decidir sobre atribuições de modelos, considere estas diretrizes:

1. O planejador precisa de raciocínio forte: O planejador deve compreender a tarefa completa, decompô-la e sintetizar resultados. Use cursor-pro ou cursor-think para o planejador.
2. Corresponder modelo à complexidade: Edições de arquivo simples não precisam de cursor-max. Reserve modelos caros para tarefas que exigem compreensão profunda.
3. Considerar janela de contexto: Subtarefas complexas podem precisar de janelas de contexto maiores. cursor-max suporta mais contexto que cursor-fast.
4. Escalamento com consciência de custo: Executar quatro subagentes cursor-fast é mais barato que um agente cursor-max. Mas se a qualidade importa, invista em modelos melhores para subtarefas críticas.

// Configuração otimizada para custo
{
  "cursor.subagents.plannerModel": "cursor-pro",
  "cursor.subagents.models": {
    "frontend-agent": "cursor-fast",
    "backend-agent": "cursor-max",
    "test-agent": "cursor-fast",
    "docs-agent": "cursor-fast"
  }
}

// Configuração otimizada para qualidade
{
  "cursor.subagents.plannerModel": "cursor-think",
  "cursor.subagents.models": {
    "frontend-agent": "cursor-max",
    "backend-agent": "cursor-max",
    "test-agent": "cursor-max",
    "docs-agent": "cursor-fast"
  }
}

aviso

Usar modelos caros para todos os subagentes pode consumir rapidamente o orçamento de tokens do seu plano. Monitore seu uso com o comando Cursor: Show Token Usage. Se você se aproximar do limite, reduza subagentes não críticos para cursor-fast.

Controle de Escopo

Restrições de Acesso a Arquivos

O controle de escopo determina quais arquivos e diretórios cada subagente pode acessar. Isso é tanto uma medida de segurança quanto uma melhoria de qualidade, pois evita que subagentes façam mudanças não intencionais.

Configurando Escopos de Arquivo

# .cursor/subagents/scopes.yaml
subagents:
  - name: "auth-module-agent"
    scope:
      # Arquivos que este agente pode ler e modificar
      files:
        include:
          - "src/auth/**"
          - "src/middleware/auth.ts"
          - "config/auth.json"
        exclude:
          - "src/auth/legacy/**"
      # Diretórios que este agente pode listar e explorar
      directories:
        - "src/auth"
        - "src/middleware"
      # Se o agente pode acessar arquivos fora de seu escopo
      strictMode: true

Quando strictMode é true, o subagente não pode ler, listar ou modificar quaisquer arquivos fora de seu escopo declarado. Esta é a configuração recomendada para a maioria dos casos de uso.

aviso

Usuários relataram que agentes às vezes exploram arquivos fora do diretório aberto, mesmo quando restrições de escopo estão configuradas. Isso tipicamente acontece quando:

1. A configuração strictMode não está explicitamente definida como true (o padrão é false)
2. O subagente usa comandos de terminal para acessar arquivos (burlando verificações de escopo de arquivo)
3. A configuração de escopo usa caminhos relativos que são resolvidos de forma diferente do esperado
4. O subagente herda o escopo mais amplo do planejador

Para evitar isso, sempre defina strictMode: true e também restrinja o acesso a ferramentas de terminal. Veja a seção Limites de Segurança abaixo.

Padrões de Escopo Comuns

Escopo Baseado em Módulo: Restringir um agente a um módulo específico:

- name: "user-module-agent"
  scope:
    files:
      include: ["src/modules/user/**"]
    strictMode: true

Escopo Baseado em Camada: Restringir um agente a uma camada arquitetural específica:

- name: "api-layer-agent"
  scope:
    files:
      include:
        - "src/api/routes/**"
        - "src/api/controllers/**"
        - "src/api/middleware/**"
    strictMode: true

Escopo Somente Leitura: Permitir leitura mas não modificação de arquivos:

- name: "code-review-agent"
  scope:
    files:
      include: ["src/**"]
    tools: ["read"]  # Sem ferramentas de escrita ou edição
    strictMode: true

Escopo de Arquivo Compartilhado: Múltiplos agentes podem acessar arquivos de configuração compartilhados:

- name: "config-aware-agent"
  scope:
    files:
      include:
        - "src/features/feature-a/**"
        - "src/shared/config.ts"  # Arquivo de configuração compartilhado
        - "src/shared/types.ts"   # Definições de tipo compartilhadas
    strictMode: true

Limites de Segurança

Restrições de Ferramentas

Cada subagente pode ser restrito a ferramentas específicas. Isso evita que subagentes realizem ações que não deveriam poder fazer.

# .cursor/subagents/security.yaml
subagents:
  - name: "read-only-analyzer"
    description: "Analyzes code without modifying anything"
    tools:
      - read
    # Sem ferramentas de escrita, edição ou terminal
    scope:
      files:
        include: ["src/**"]
      strictMode: true

  - name: "test-runner"
    description: "Runs tests and reports results"
    tools:
      - read
      - terminal
    scope:
      files:
        include: ["test/**", "src/**"]
      strictMode: true
    terminal:
      allowedCommands:
        - "npm test"
        - "npm run test:unit"
        - "npm run test:integration"
      blockedCommands:
        - "rm"
        - "git push"
        - "npm publish"

  - name: "file-editor"
    description: "Edits source files only"
    tools:
      - read
      - write
      - edit
    # Sem acesso ao terminal
    scope:
      files:
        include: ["src/**"]
      strictMode: true

dica

As configurações allowedCommands e blockedCommands para acesso ao terminal fornecem uma camada dupla de segurança. Mesmo se um subagente de alguma forma obtiver acesso ao terminal, ele só pode executar comandos explicitamente aprovados. Isso é especialmente importante ao executar agentes em pipelines de CI/CD ou ambientes automatizados.

Prevenindo Interferência Entre Subagentes

Subagentes devem operar independentemente. Para evitar que interfiram uns com os outros:

1. Escopos de arquivo não sobrepostos: Garantir que subagentes não tenham acesso de escrita sobreposto aos mesmos arquivos
2. Branches separados: Considerar fazer cada subagente trabalhar em um branch Git separado
3. Execução em etapas: Usar execução sequencial quando subagentes dependem da saída uns dos outros

# Exemplo: Execução sequencial com dependência
execution:
  strategy: sequential
  steps:
    - agent: "schema-agent"
      description: "Generate database schema first"
      scope:
        files:
          include: ["src/models/**", "migrations/**"]
      tools: ["read", "write", "edit"]

    - agent: "api-agent"
      description: "Build API endpoints based on schema"
      dependsOn: "schema-agent"
      scope:
        files:
          include: ["src/api/**"]
      tools: ["read", "write", "edit"]

    - agent: "test-agent"
      description: "Write tests for the new API"
      dependsOn: "api-agent"
      scope:
        files:
          include: ["test/**"]
      tools: ["read", "write", "terminal"]

aviso

Se dois subagentes escreverem no mesmo arquivo simultaneamente, você terá conflitos de mesclagem que o planejador não pode resolver automaticamente. Sempre verifique se os escopos de arquivo não se sobrepõem para subagentes com capacidade de escrita. Use o comando Cursor: Validate Subagent Scopes para verificar sobreposições antes da execução.

Acesso a Variáveis de Ambiente

Controle quais variáveis de ambiente cada subagente pode acessar:

- name: "deploy-agent"
  scope:
    env:
      allow:
        - "DEPLOY_TARGET"
        - "CI_COMMIT_SHA"
      deny:
        - "AWS_SECRET_ACCESS_KEY"
        - "DATABASE_PASSWORD"

Isso garante que segredos sensíveis não sejam expostos a subagentes que não precisam deles.

Execução Paralela de Agentes

Configurando Execução Paralela

A execução paralela permite que múltiplos subagentes rodem simultaneamente, reduzindo significativamente o tempo total de conclusão da tarefa.

// Em settings.json
{
  "cursor.subagents.execution": {
    "strategy": "parallel",
    "maxConcurrent": 4,
    "staggerDelay": 1000
  }
}

• maxConcurrent: Número máximo de subagentes rodando ao mesmo tempo
• staggerDelay: Milissegundos de espera entre o início de cada subagente (evita picos de recursos)

Exemplo de Execução Paralela

# .cursor/subagents/parallel-config.yaml
planner:
  model: cursor-pro
  description: "Refactor the authentication system across frontend and backend"

execution:
  strategy: parallel

subagents:
  - name: "frontend-auth"
    model: cursor-max
    description: "Refactor React authentication components to use new auth context"
    scope:
      files:
        include: ["src/components/auth/**", "src/contexts/AuthContext.tsx"]
      strictMode: true
    tools: ["read", "write", "edit"]

  - name: "backend-auth"
    model: cursor-max
    description: "Refactor backend authentication middleware and JWT handling"
    scope:
      files:
        include: ["src/api/middleware/auth.ts", "src/utils/jwt.ts"]
      strictMode: true
    tools: ["read", "write", "edit"]

  - name: "auth-tests"
    model: cursor-fast
    description: "Update authentication tests for the new structure"
    scope:
      files:
        include: ["test/auth/**"]
      strictMode: true
    tools: ["read", "write", "terminal"]

  - name: "auth-docs"
    model: cursor-fast
    description: "Update authentication documentation"
    scope:
      files:
        include: ["docs/auth/**", "README.md"]
      strictMode: true
    tools: ["read", "write"]

Nesta configuração, todos os quatro subagentes iniciam simultaneamente (com um escalonamento de 1 segundo) e trabalham em suas respectivas áreas em paralelo.

Tratando Resultados de Execução Paralela

O planejador coleta resultados de todos os subagentes paralelos e os sintetiza:

// Configuração de síntese do planejador
{
  "cursor.subagents.planner": {
    "synthesisStrategy": "merge",
    "conflictResolution": "planner-decides",
    "generateSummary": true,
    "summaryFormat": "markdown"
  }
}

dica

Se subagentes paralelos produzirem mudanças conflitantes, o planejador pode resolvê-las escolhendo uma abordagem sobre outra. Ative generateSummary para que o planejador explique suas decisões de resolução de conflitos em um formato legível por humanos. Revise este resumo antes de aceitar as mudanças.

Orquestração de Subagentes

Estratégias de Orquestração

O planejador pode usar diferentes estratégias para orquestrar subagentes:

Estratégia 1: Fan-Out / Fan-In

O planejador decompõe a tarefa, atribui subtarefas a subagentes paralelos, coleta todos os resultados e os sintetiza.

execution:
  strategy: parallel
  synthesis:
    type: "merge"
    order: "completion"  # Coletar resultados conforme forem concluídos

Estratégia 2: Pipeline

Subagentes executam em sequência, cada um consumindo a saída do anterior.

execution:
  strategy: sequential
  pipeline:
    - agent: "schema-generator"
      output: "schema_result"
    - agent: "api-builder"
      input: "schema_result"
      output: "api_result"
    - agent: "test-writer"
      input: "api_result"
      output: "test_result"

Estratégia 3: Adaptativa

O planejador decide dinamicamente se deve executar subagentes em paralelo ou sequencialmente com base nas dependências da tarefa.

execution:
  strategy: adaptive
  rules:
    - condition: "no_dependencies"
      action: "parallel"
    - condition: "has_dependencies"
      action: "sequential"
    - condition: "partial_dependencies"
      action: "mixed"

Criação Dinâmica de Subagentes

O planejador pode criar subagentes dinamicamente com base no que descobre durante a execução da tarefa:

// Em settings.json
{
  "cursor.subagents.dynamicCreation": true,
  "cursor.subagents.dynamicMaxAgents": 8,
  "cursor.subagents.dynamicTemplate": {
    "model": "cursor-fast",
    "tools": ["read", "write", "edit"],
    "scope": {
      "strictMode": true
    }
  }
}

Com a criação dinâmica ativada, o planejador pode gerar novos subagentes conforme necessário. Por exemplo, se o planejador descobrir que a tarefa envolve tanto arquivos Python quanto TypeScript, ele pode criar um subagente específico para Python e um subagente específico para TypeScript dinamicamente.

aviso

A criação dinâmica de subagentes pode levar a proliferação descontrolada de agentes se o planejador superestimar a necessidade de paralelismo. Sempre defina dynamicMaxAgents para um limite razoável (4-8) e monitore o uso total de tokens. Se o planejador criar muitos subagentes, pode esgotar o orçamento de tokens antes que a tarefa seja concluída.

Orquestração com Pontos de Verificação

Adicione pontos de verificação entre execuções de subagentes para permitir revisão humana ou validação automatizada:

execution:
  strategy: sequential
  checkpoints:
    - after: "schema-generator"
      action: "validate"
      validator: "npm run typecheck"
      onFail: "retry"
      maxRetries: 2

    - after: "api-builder"
      action: "review"
      reviewer: "human"
      timeout: 300000
      onTimeout: "proceed"

dica

Pontos de verificação são especialmente valiosos em integrações de CI/CD onde você deseja validar resultados intermediários antes de prosseguir. Um ponto de verificação validate executa um comando e só prossegue se ele terminar com sucesso, enquanto um ponto de verificação review pausa para entrada humana.

Monitoramento e Depuração

Visualizando Status de Subagentes

Monitore todos os subagentes em execução pela barra lateral do Cursor:

# Paleta de Comandos: Cursor: Show Subagent Dashboard

O painel mostra:

Subagent Dashboard
==================
Planner: [running] cursor-pro
  Task: "Refactor authentication system"
  Steps: 3/5

Subagents:
  [completed] frontend-auth (cursor-max)
    Files changed: 4
    Tokens used: 12,400

  [running] backend-auth (cursor-max)
    Current file: src/api/middleware/auth.ts
    Tokens used: 8,200

  [running] auth-tests (cursor-fast)
    Current file: test/auth/login.test.ts
    Tokens used: 3,100

  [queued] auth-docs (cursor-fast)
    Waiting for: backend-auth to complete

Total tokens: 23,700 / 100,000

Depurando Violações de Escopo

Se um subagente tentar acessar arquivos fora de seu escopo, a tentativa é registrada:

# Ver log de violações de escopo
# Paleta de Comandos: Cursor: Show Subagent Logs

[WARN] Subagent "frontend-auth" attempted to read src/api/routes.ts
       Access denied: file is outside the agent's scope
       Scope includes: src/components/auth/**, src/contexts/AuthContext.tsx

[WARN] Subagent "backend-auth" attempted to run terminal command: npm install
       Command blocked: not in allowedCommands list
       Allowed commands: npm test, npx tsc, git status

dica

Se você vir violações de escopo repetidas do mesmo subagente, seu escopo pode ser muito restritivo. Revise a tarefa e considere expandir o escopo para incluir os arquivos que ele continua tentando acessar. Um subagente frustrado que não pode acessar arquivos necessários desperdiçará tokens em tentativas falhadas.

Melhores Práticas

• Use cursor-pro ou superior para o planejador, modelos mais baratos para subagentes simples
• Sempre defina strictMode: true para escopos de arquivo para evitar acesso indesejado
• Configure allowedCommands para qualquer subagente com acesso ao terminal
• Garanta que escopos de escrita não se sobreponham entre subagentes paralelos
• Defina um limite maxConcurrent para controlar o uso de recursos
• Use pontos de verificação para tarefas críticas que exigem validação
• Monitore o uso de tokens em todos os subagentes para evitar esgotamento do orçamento
• Comece com execução sequencial e mude para paralela depois de verificar escopos
• Revise o resumo de síntese do planejador antes de aceitar resultados paralelos
• Controle de versão da configuração de subagentes para consistência da equipe

aviso

Subagentes herdam o prompt do sistema do planejador por padrão. Se seu prompt do sistema contém informações sensíveis, considere usar prompts específicos de subagente que excluem contexto desnecessário. Configure isso com a configuração cursor.subagents.inheritPlannerPrompt definida como false.

Conclusão

Subagentes no Cursor fornecem uma maneira poderosa de decompor tarefas complexas em unidades especializadas e gerenciáveis. Ao selecionar cuidadosamente modelos, configurar escopos de arquivo estritos, definir limites de segurança e escolher a estratégia de orquestração certa, você pode construir fluxos de trabalho multi-agente que são tanto eficientes quanto seguros.

As considerações mais importantes são: corresponder o modelo à complexidade da tarefa, usar aplicação estrita de escopo para evitar problemas de acesso a arquivos e começar com execução sequencial antes de mudar para paralela. Com essas práticas, subagentes tornam-se uma ferramenta confiável para lidar com tarefas de desenvolvimento em grande escala que seriam esmagadoras para um único agente.