Subagentes

Subagentes são assistentes de IA especializados aos quais o agente do Cherri Code pode delegar tarefas. Cada subagente opera em sua própria janela de contexto, realiza tipos específicos de trabalho e retorna o resultado ao agente pai. Use subagentes para dividir tarefas complexas, trabalhar em paralelo e preservar o contexto na conversa principal.

Você pode usar subagentes no Editor, na CLI e em Cloud Agents.

Como os subagentes funcionam

Quando o agente encontra uma tarefa complexa, ele pode iniciar um subagente automaticamente. O subagente recebe um prompt com todo o contexto necessário, trabalha de forma autônoma e retorna uma mensagem final com os resultados.

Os subagentes começam com um contexto limpo. O agente pai inclui informações relevantes no prompt, pois os subagentes não têm acesso ao histórico da conversa anterior.

Primeiro plano vs. segundo plano

Os subagentes são executados em um destes dois modos:

Subagentes integrados

O Cherri Code inclui três subagentes integrados que lidam automaticamente com operações que exigem muito contexto. Esses subagentes foram projetados com base na análise de conversas com agentes que atingiram os limites da janela de contexto.

Por que esses subagentes existem

Essas três operações têm características em comum: geram saídas intermediárias com muito ruído, se beneficiam de prompts e ferramentas especializados e podem consumir bastante contexto. Executá-las como subagentes resolve vários problemas:

• Isolamento de contexto — A saída intermediária fica no subagente. O agente principal vê apenas o resumo final.
• Flexibilidade de modelo — O subagente de exploração usa um modelo mais rápido por padrão. Isso permite executar 10 buscas paralelas no tempo que uma única busca do agente principal levaria.
• Configuração especializada — Cada subagente tem prompts e acesso a ferramentas ajustados para sua tarefa específica.
• Eficiência de custo — Modelos mais rápidos custam menos. Isolar trabalhos que consomem muitos tokens em subagentes com escolhas de modelo adequadas reduz o custo geral.

Você não precisa configurar esses subagentes. O agente os usa automaticamente quando apropriado.

Quando usar subagentes

Início rápido

O agente usa subagentes automaticamente quando necessário. Você também pode criar um subagente personalizado pedindo ao agente:

Para ter mais controle, crie subagentes personalizados manualmente no diretório do projeto ou do usuário.

Subagentes personalizados

Defina subagentes personalizados para incorporar conhecimento especializado, aplicar padrões da equipe ou automatizar fluxos de trabalho repetitivos.

Localizações de arquivos

Os subagentes do projeto têm precedência em caso de conflito de nomes. Quando várias localizações contêm subagentes com o mesmo nome, .cursor/ tem precedência sobre .claude/ e .codex/.

Formato do arquivo

Cada subagente é um arquivo markdown com frontmatter YAML:

---name: security-auditordescription: Security specialist. Use when implementing auth, payments, or handling sensitive data.model: inheritreadonly: true---You are a security expert auditing code for vulnerabilities.When invoked:1. Identify security-sensitive code paths2. Check for common vulnerabilities (injection, XSS, auth bypass)3. Verify secrets are not hardcoded4. Review input validation and sanitizationReport findings by severity:- Critical (must fix before deploy)- High (fix soon)- Medium (address when possible)

Campos de configuração

Configuração de modelo

O campo model determina qual modelo um subagente usa. Há duas opções:

Escolha inherit quando o subagente precisar da mesma capacidade de raciocínio do agente pai. Use um ID de modelo específico quando precisar dos recursos de um modelo específico, independentemente do modelo usado pelo agente pai.

Parâmetros do modelo

Adicione colchetes a um ID de modelo para definir opções específicas, como velocidade, esforço de raciocínio e janela de contexto. Especifique as opções como pares id=value e separe várias opções por vírgulas.

As opções disponíveis dependem do modelo e usam os mesmos pares id=value dos parâmetros do modelo do SDK.

---name: plannerdescription: Plans complex changes before implementation.model: claude-opus-5[effort=high]---Break the task into a clear, ordered implementation plan.

Quando o modelo configurado não é usado

O Cherri Code respeita o campo model no frontmatter do seu subagente, exceto quando uma destas condições se aplica:

• Restrições do administrador da equipe — O administrador da sua organização bloqueou o modelo especificado.
• Configuração legada do Max Mode — Em um plano legado de precificação por solicitação, o modelo exige o Max Mode e ele não está habilitado.
• Limitações do plano — O modelo não está disponível no seu plano atual.

Nesses casos, o Cherri Code usa um modelo compatível como alternativa. Se o comportamento do modelo não for o esperado, verifique seu plano e as configurações do modelo.

---name: code-reviewerdescription: Reviews code for correctness and style.model: inherit---Review the code changes for bugs, style issues, and edge cases.

---name: search-agentdescription: Searches the codebase for relevant files and symbols.model: inherit---Search the codebase and return relevant file paths and code snippets.

---name: reasoning-agentdescription: Handles complex architectural decisions.model: gpt-5.6-sol---Analyze the architecture and recommend changes with detailed reasoning.

Como usar subagentes

Delegação automática

O agente delega tarefas proativamente com base em:

• A complexidade e o escopo da tarefa
• Descrições personalizadas de subagentes no seu projeto
• O contexto atual e as ferramentas disponíveis

Inclua frases como "usar proativamente" ou "sempre usar para" no campo de descrição para incentivar a delegação automática.

Invocação explícita

Solicite um subagente específico usando a sintaxe /name no prompt:

> /verifier confirm the auth flow is complete> /debugger investigate this error> /security-auditor review the payment module

Também é possível invocar subagentes mencionando-os naturalmente:

> Use o subagente verifier para confirmar que o fluxo de autenticação está completo> Peça ao subagente debugger para investigar este erro> Execute o subagente security-auditor no módulo de pagamento

Execução paralela

Inicie vários subagentes simultaneamente para maximizar a produtividade:

> Revise as alterações na API e atualize a documentação em paralelo

O agente envia várias chamadas à ferramenta Task em uma única mensagem, fazendo com que os subagentes sejam executados simultaneamente.

Cópias isoladas do projeto

Por padrão, os subagentes compartilham o checkout do agente pai. Quando vários subagentes editam arquivos ao mesmo tempo, podem sobrescrever as alterações uns dos outros. Solicite isolamento para que cada subagente seja executado em sua própria cópia do projeto:

> Execute um enxame de subagentes para corrigir esses cinco testes instáveis, cada um em seu próprio ambiente

Cada subagente recebe seu próprio ambiente e sua própria branch: uma worktree isolada do Git com um diretório de trabalho separado na mesma máquina ou um ambiente na nuvem próprio, com uma VM dedicada e um clone do repositório. As alterações de cada subagente permanecem em sua própria branch até que o agente pai faça mergear dos resultados.

Esse é o isolamento no nível de subagente dentro de uma única sessão. Para isolar um agente inteiro, execute-o em um worktree ou atribua a tarefa a um subagente na nuvem.

Subagentes na nuvem

Em uma sessão de agente local, você pode delegar trabalho a um subagente na nuvem, executado em sua própria VM e branch. Seu espaço de trabalho local permanece limpo e responsivo enquanto tarefas de longa duração ou paralelas são executadas na nuvem. O agente pai continua em execução localmente ou na nuvem, sem interrupções. Os subagentes na nuvem são executados pela Janela de Agentes no Cherri Code desktop.

Inicie um subagente na nuvem com /in-cloud

Digite /in-cloud e a próxima tarefa enviada será executada como um subagente na nuvem. Ele cria sua própria VM e branch para trabalhar na tarefa.

Isso é útil para isolar trabalhos de longa duração ou em paralelo, como corrigir a CI, investigar uma issue ou explorar uma base de código enquanto você continua trabalhando localmente.

Coloque uma PR no piloto automático com /autopilot

Peça a um subagente na nuvem para assumir uma pull request com /autopilot ou clicando no botão de ação rápida. O agente na nuvem trabalha remotamente para preparar a PR para merge sem ocupar sua sessão local.

Os subagentes na nuvem usam o ambiente configurado para seu repositório e seguem as mesmas regras de modelo e recursos que outros Cloud Agents. Como são executados em uma VM na nuvem, seus servidores MCP vêm da configuração da sua equipe em cursor.com/agents, e não da sua sessão local.

Retomando subagentes

É possível retomar subagentes para dar continuidade a conversas anteriores. Isso é útil para tarefas de longa duração que se estendem por várias invocações.

Cada execução de subagente retorna um ID de agente. Passe esse ID para retomar o subagente com todo o contexto preservado:

> Retome o agente abc123 e analise as falhas de teste restantes

Padrões comuns

Agente de verificação

Um agente de verificação valida de forma independente se o trabalho declarado foi realmente concluído. Isso aborda um problema comum em que a IA marca tarefas como concluídas, mas as implementações estão incompletas ou com falhas.

---name: verifierdescription: Valida trabalhos concluídos. Use depois que as tarefas forem marcadas como concluídas para confirmar que as implementações estão funcionais.---Você é um validador cético. Seu trabalho é verificar se aquilo que foi dado como concluído realmente funciona.Quando acionado:1. Identifique o que foi dado como concluído2. Verifique se a implementação existe e está funcional3. Execute os testes ou as etapas de verificação relevantes4. Procure casos de borda que possam ter passado despercebidosSeja minucioso e cético. Relate:- O que foi verificado e aprovado- O que foi dado como pronto, mas está incompleto ou quebrado- Problemas específicos que precisam ser resolvidosNão aceite as afirmações como verdade absoluta. Teste tudo.

Esse padrão é útil para:

• Validar se as funcionalidades funcionam de ponta a ponta antes de marcar os Tickets como concluídos
• Detectar funcionalidades parcialmente implementadas
• Garantir que os testes realmente passam (não apenas que os arquivos de teste existem)

Padrão de orquestração

Para fluxos de trabalho complexos, um agente principal pode coordenar vários subagentes especializados em sequência:

1. Planejador analisa os requisitos e cria um plano técnico
2. Implementador desenvolve a funcionalidade com base no plano
3. Verificador confirma que a implementação atende aos requisitos

Cada etapa de transferência inclui uma saída estruturada para que o próximo agente tenha um contexto claro.

Exemplos de subagentes

Depurador

---name: debuggerdescription: Especialista em depuração de erros e falhas de teste. Use ao encontrar problemas.---You are an expert debugger specializing in root cause analysis.When invoked:1. Capture error message and stack trace2. Identify reproduction steps3. Isolate the failure location4. Implement minimal fix5. Verify solution worksFor each issue, provide:- Root cause explanation- Evidence supporting the diagnosis- Specific code fix- Testing approachFocus on fixing the underlying issue, not symptoms.

Executor de testes

---name: test-runnerdescription: Test automation expert. Use proactively to run tests and fix failures.---You are a test automation expert.When you see code changes, proactively run appropriate tests.If tests fail:1. Analyze the failure output2. Identify the root cause3. Fix the issue while preserving test intent4. Re-run to verifyReport test results with:- Number of tests passed/failed- Summary of any failures- Changes made to fix issues

Melhores práticas

• Crie subagentes específicos — Cada subagente deve ter uma única responsabilidade clara. Evite agentes "auxiliares" genéricos.
• Invista nas descrições — O campo description determina quando o agente delega tarefas ao seu subagente. Dedique tempo para refiná-lo. Teste criando prompts e verificando se o subagente correto é acionado.
• Mantenha os prompts concisos — Prompts longos e prolixos dispersam o foco. Seja específico e direto.
• Adicione subagentes ao controle de versão — Inclua .cursor/agents/ no seu repositório para que toda a equipe se beneficie.
• Comece com agentes gerados pelo agente — Deixe o agente ajudar você a criar a configuração inicial e depois personalize-a.
• Use hooks para gerar arquivos de saída — Se precisar que os subagentes produzam arquivos de saída estruturados, considere usar hooks para processar e salvar os resultados de maneira consistente.

Antipadrões a evitar

• Descrições vagas — "Usar para tarefas gerais" não informa ao agente quando delegar. Seja específico: "Usar ao implementar fluxos de autenticação com provedores OAuth."
• Prompts longos demais — Um prompt de 2.000 palavras não torna um subagente mais inteligente. Apenas o torna mais lento e difícil de manter.
• Duplicar comandos slash — Se uma tarefa tem uma única finalidade e não precisa de isolamento de contexto, use uma skill ou um comando.
• Subagentes demais — Comece com 2 a 3 subagentes focados. Adicione mais apenas quando tiver casos de uso claros e distintos.

Gerenciar subagentes

Criar subagentes

A maneira mais fácil de criar um subagente é pedir ao agente para criar um para você:

Você também pode criar subagentes manualmente adicionando arquivos Markdown a .cursor/agents/ (projeto) ou ~/.cursor/agents/ (usuário).

Como visualizar subagentes

O agente inclui todos os subagentes personalizados entre as ferramentas disponíveis. Para ver quais subagentes estão configurados, verifique o diretório .cursor/agents/ no seu projeto.

Desempenho e custo

Os subagentes envolvem algumas concessões. Entendê-las ajuda você a decidir quando usá-los.

Considerações sobre tokens e custos

• Os subagentes consomem tokens de forma independente — Cada subagente tem sua própria janela de contexto e seu próprio uso de tokens. Executar cinco subagentes em paralelo consome cerca de cinco vezes mais tokens que um único agente.
• Avalie a sobrecarga — Para tarefas rápidas e simples, o agente principal costuma ser mais rápido. Os subagentes se destacam em tarefas complexas, de longa duração ou paralelas.
• Os subagentes podem ser mais lentos — O benefício é o isolamento de contexto, não a velocidade. Um subagente que executa uma tarefa simples pode ser mais lento que o agente principal porque começa sem contexto.

Perguntas frequentes