> ## Documentation Index > Fetch the complete documentation index at: https://docs.devin.ai/llms.txt > Use this file to discover all available pages before exploring further. # Subagentes > Delegue tarefas a subagentes independentes que trabalham em primeiro ou em segundo plano Os subagentes permitem que o agente principal crie agentes independentes para lidar com subtarefas. Um subagente compartilha as ferramentas e o contexto da base de código com o agente pai, mas opera em sua própria linha de conversa -- ele não herda o histórico de conversa do agente pai. Isso é útil para tarefas que se beneficiam de um trabalho focado e independente -- como explorar uma base de código, executar testes ou implementar uma funcionalidade em paralelo. Você pode pedir explicitamente ao agente para usar subagentes (por exemplo, "pesquise como a autenticação funciona em um subagente"), ou o agente pode decidir delegar por conta própria quando determinar que uma tarefa se beneficiaria de trabalho independente. Em nossas medições, **subagentes** **tanto** **melhoram o desempenho geral na programação** **quanto** **reduzem o custo**. ***
## Como os subagentes funcionam
Quando o agente cria um subagente, ele seleciona um dos **perfis de subagente** disponíveis e escolhe se o subagente deve ser executado em primeiro plano ou em segundo plano. Os subagentes podem ser executados em dois modos: É executado inline na sua sessão. O agente principal pausa e espera o subagente terminar antes de continuar. Você pode aprovar ou negar chamadas de ferramenta à medida que elas aparecem. É executado em paralelo enquanto o agente principal continua trabalhando. O agente principal é notificado automaticamente quando o subagente é concluído. Chamadas de ferramenta não aprovadas são negadas automaticamente. Você não vê diretamente a saída bruta do subagente. Quando um subagente termina, o agente principal lê o resultado e resume para você os principais resultados e ações.
### Custo dos subagentes
Os subagentes funcionam como suas próprias sessões de agente, cada um com sua própria janela de contexto e chamadas de inferência, portanto geram custos independentemente do agente principal. O gasto do agente principal cobre apenas o próprio trabalho; cada subagente que ele cria adiciona seu próprio uso além disso. Nos planos baseados em prompt, cada subagente consome créditos adicionais, assim como uma mensagem do usuário. O número de créditos depende do modelo que o subagente utiliza, portanto tarefas que geram vários subagentes (ou os [aninham](/pt-BR/cli/subagents#nesting-depth)) consomem mais créditos. Como o custo aumenta com o número de subagentes, tarefas que se desdobram em muitos subagentes (ou os [aninham](#nesting-depth)) custam mais. Use subagentes de forma intencional quando o paralelismo ou um contexto mais focado justificarem o gasto adicional. ***
## Qual modelo um subagente usa?
Os subagentes não executam todos no modelo que você escolheu no seletor de modelos. Cada perfil define de onde vem seu modelo: | Perfil | Modelo usado | Efeito na cota / créditos | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `subagent_explore` | O **modelo padrão de subagente** — um modelo rápido e barato (SWE-1.6 por padrão) | Barato: o uso do SWE-1.6 é cobrado pelas tarifas do SWE, não pela tarifa do seu modelo principal | | `subagent_general` | **O mesmo modelo do agente principal** — aquele que você selecionou no seletor de modelos (por exemplo, Claude Opus, GPT-5) | Mesma tarifa do agente principal: um subagente geral custa como uma sessão extra completa no modelo selecionado | | Subagentes personalizados | O campo `model` no arquivo de definição, se definido; caso contrário, o **modelo padrão de subagente** | Depende do modelo que você fixar | `subagent_general` herda o modelo do agente principal. Se você estiver executando um modelo premium, cada subagente geral também será executado nesse modelo premium, com sua própria janela de contexto e chamadas de inferência — portanto, uma tarefa que se divide em vários subagentes gerais multiplica seus custos. Peça um subagente de exploração (ou um [subagente personalizado](#custom-subagents) com um `model:` mais barato fixado) quando o trabalho for de pesquisa, e não de alterações de código. O **modelo padrão de subagente** não é um nome de modelo fixo — ele é resolvido por um roteador no momento em que o subagente é criado, e um administrador pode aplicar um override (veja abaixo). Com a configuração padrão do **roteador de subagentes**, ele é resolvido para SWE-1.6 (uma variante mais rápida ou mais lenta do SWE-1.6, dependendo do nível do seu plano). No momento, a CLI não indica no painel de subagentes qual modelo um subagente em execução está usando.
### Influenciando o modelo
Não há como especificar um modelo para um subagente em um prompt — a ferramenta `run_subagent` aceita um *perfil*, não um modelo. Você tem duas opções: 1. **Peça um perfil em linguagem natural.** Solicitar um subagente de exploração ("pesquise como a autenticação funciona em um subagente de exploração") mantém o trabalho no modelo padrão barato do subagente. Pedir alterações no código direciona você para `subagent_general`, que é executado no modelo selecionado. 2. **Fixe um modelo em um perfil de [subagente personalizado](#custom-subagents).** `model:` no arquivo de definição é a única forma de executar um subagente *com capacidade de escrita* em um modelo diferente do agente pai. Uma [skill](/pt-BR/cli/extensibility/skills) executada em um subagente também pode definir `model:` no frontmatter para aplicar override ao modelo do perfil.
### Controles do Enterprise
Os administradores podem controlar qual modelo os subagentes usam — e se os subagentes serão executados ou não — por meio da configuração **Modelo padrão de subagente** nas configurações da org/do Enterprise. Essa configuração controla o modelo de `subagent_explore` e de subagentes personalizados que não fixam um `model:` — ela não altera `subagent_general`, que sempre segue o modelo do agente principal. Configuração de modelo padrão de subagente Ela tem três opções: | Opção | Comportamento | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **roteador de subagentes (padrão)** | O modelo padrão de subagente é escolhido por um roteador no momento da criação. Hoje, ele resolve para SWE-1.6 (a variante exata depende do nível do seu plano). | | **Um modelo específico** | Fixa o modelo padrão de subagente no modelo selecionado para todo subagente que não é executado no modelo do agente principal. | | **Nenhum** | Desativa totalmente os subagentes — o Devin não criará nenhum subagente. | ***
## Ativar e desativar subagentes
Os subagentes vêm ativados por padrão. Defina `subagents_enabled` como `false` no seu [arquivo de configuração](/pt-BR/cli/reference/configuration/config-file#subagents_enabled) para remover as ferramentas `run_subagent` e `read_subagent`, fazendo com que o agente execute tudo por conta própria: ```json theme={null} // ~/.config/devin/config.json { "subagents_enabled": false } ``` A alteração é aplicada imediatamente — uma sessão em execução a adota sem precisar reiniciar. No Devin Desktop, o mesmo recurso é o controle **Subagents (Preview)** nas configurações. A política da organização prevalece: se um administrador definiu **modelo padrão de subagente** como **Nenhum**, os subagentes permanecem desativados, independentemente do que esta configuração indique. ***
## Perfis de subagente
Cada subagente usa um perfil específico que determina suas capacidades. Há dois perfis nativos: | Perfil | Descrição | Acesso às ferramentas | Modelo | | ------------------ | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | `subagent_explore` | Exploração e pesquisa da base de código em modo somente leitura | Ferramentas da base de código em modo somente leitura, além de pesquisa na web; não pode editar arquivos nem acessar URLs arbitrárias (independentemente de estar em primeiro plano ou em segundo plano) | Modelo padrão de subagente (SWE-1.6 por padrão) | | `subagent_general` | Tarefas de uso geral, incluindo alterações no código | Acesso total às ferramentas (primeiro plano) ou apenas às ferramentas pré-aprovadas (segundo plano) | Mesmo modelo do agente principal | O agente escolhe automaticamente o perfil adequado com base na tarefa. Os subagentes de exploração são ideais para pesquisa e compreensão, enquanto os subagentes gerais podem fazer alterações. Veja [Qual modelo um subagente usa?](#which-model-does-a-subagent-use) para saber como cada perfil escolhe seu modelo — os dois perfis **não** usam o mesmo modelo. Você também pode definir seus próprios perfis personalizados de subagente — veja [Subagentes personalizados](#custom-subagents) abaixo. ***
## Permissões de ferramentas
O funcionamento das permissões de ferramentas depende de o subagente estar sendo executado em primeiro plano ou em segundo plano: * **Subagentes em primeiro plano** se comportam como o agente principal -- você recebe solicitações para aprovar ou negar chamadas de ferramentas, como de costume. A solicitação identifica o subagente que requisitou a ação, para que você saiba quem está solicitando. * **Subagentes em segundo plano** herdam todas as permissões de ferramentas que você já concedeu durante a sessão atual. Qualquer ferramenta que não tenha sido pré-aprovada é negada automaticamente. Subagentes em segundo plano não podem solicitar novas permissões. Se um subagente em segundo plano falhar porque uma ferramenta obrigatória foi negada, você pode retomá-lo em primeiro plano para aprovar as permissões necessárias. Veja [Retomando subagentes](#resuming-subagents) abaixo. ***
## Monitoramento de subagentes
### Indicador de subagente
Quando houver subagentes em segundo plano em execução, um indicador aparecerá abaixo do campo de entrada mostrando o status deles. Você pode ir até o indicador pressionando ↓ no campo de entrada e, em seguida, Enter para abrir o painel de subagentes. Quando um subagente em primeiro plano estiver em execução, o indicador giratório exibirá **"Subagente em execução · Ctrl+B para executar em segundo plano"**.
### Painel de subagentes
O painel de subagentes permite visualizar e gerenciar todos os subagentes ativos e concluídos. Ele mostra o perfil, o título, o status, o tempo transcorrido e o número de chamadas de ferramenta de cada subagente. A atividade dos subagentes persiste após o recarregamento da sessão, portanto o painel continua refletindo seus subagentes após a retomada. ***
## Alternar entre primeiro plano e segundo plano
Você pode mover subagentes entre primeiro plano e segundo plano enquanto eles estão em execução: * **Mover um subagente em primeiro plano para segundo plano:** Pressione Ctrl+B enquanto um subagente em primeiro plano estiver em execução. O subagente continua trabalhando em segundo plano, e o agente pai é retomado. * **Trazer um subagente em segundo plano para primeiro plano:** Abra o painel de subagentes e pressione f em um subagente em segundo plano que esteja em execução. A saída do subagente será exibida inline. Quando você move um subagente para segundo plano, a chamada de ferramenta do agente pai já retornou, então o agente pai continua de forma independente. O resultado do subagente não volta para o pipeline atual do agente pai, mas você será notificado quando ele for concluído. ***
## Interrompendo um turno
Interromper o agente não encerra seus subagentes. Os subagentes em execução **ficam em espera** com seu estado intacto e são retomados na próxima mensagem. Assim, interromper o agente principal para redirecioná-lo não descarta o trabalho em andamento. ***
## Cancelando subagentes
Você pode cancelar um subagente em execução de duas maneiras: 1. **No painel de subagentes:** Abra o painel e pressione x no subagente em execução. 2. **Subagente em primeiro plano:** Pressione Ctrl+C ou Esc para cancelar o subagente em primeiro plano que está em execução. ***
## Retomando subagentes
Subagentes cancelados, que falharam ou já concluídos podem ser retomados com um novo prompt. Você pode pedir ao agente para retomar um subagente, e ele continuará de onde parou. Subagentes retomados sempre são executados em **primeiro plano**, para que você possa aprovar quaisquer chamadas de ferramentas que tenham sido negadas anteriormente. Isso é especialmente útil quando: * Um subagente em segundo plano falhou porque o uso de uma ferramenta obrigatória foi negado — retome-o em primeiro plano para conceder as permissões necessárias. * Um subagente foi concluído, mas você quer que ele faça um trabalho complementar com base em seus resultados. * Um subagente foi cancelado prematuramente e você quer que ele continue. ***
## Profundidade de aninhamento
Por padrão, subagentes não podem criar seus próprios subagentes — apenas o agente raiz pode. As ferramentas de subagente (`run_subagent` e `read_subagent`) ficam desativadas dentro de um subagente para evitar aninhamento sem limites. No entanto, **perfis personalizados de subagente** podem optar por permitir criação aninhada definindo o campo `max-nesting` no frontmatter. Esse valor faz override da profundidade máxima padrão, permitindo que subagentes criem filhos desde que a árvore permaneça dentro desse limite. Por exemplo, `max-nesting: 3` permite a seguinte cadeia: ``` Root agent (depth 0) └── Custom subagent (depth 1) — pode criar filhos └── Child subagent (depth 2) — pode criar filhos └── Grandchild subagent (depth 3) — não pode criar filhos (limite de profundidade atingido) ``` Subagentes aninhados podem aumentar significativamente o custo. Cada nível de aninhamento gera agentes adicionais com suas próprias janelas de contexto e chamadas de inferência. Use esse recurso com critério. ***
## Subagentes personalizados
Os subagentes personalizados são **experimentais**. O formato, o comportamento e as opções de configuração podem mudar em versões futuras. Além dos perfis nativos `subagent_explore` e `subagent_general`, você pode definir seus próprios perfis de subagente personalizados. Os subagentes personalizados permitem criar agentes especializados com seus próprios prompts de sistema, restrições de ferramentas e overrides de modelo — adaptados a tarefas específicas no seu fluxo de trabalho. Esta também é a forma de obter um subagente com capacidade de escrita que **não** roda no seu modelo principal (possivelmente caro): atribua a ele um `model:` e as ferramentas de que precisa.
### Criando um subagente personalizado
Subagentes personalizados são definidos como arquivos Markdown em `agents/`, usando um destes formatos: * **Arquivo simples** — `agents/.md` (a mesma convenção usada por Claude Code, Cursor e outras ferramentas). O nome do arquivo (sem `.md`) se torna o identificador do perfil. * **Diretório** — `agents//AGENT.md`. O nome do diretório se torna o identificador do perfil. `AGENTS.md`, `agent.md` e `agents.md` também são aceitos como nome de arquivo (se houver vários, `AGENT.md` tem precedência, seguido por `AGENTS.md`, `agent.md` e `agents.md`). Em ambos os formatos, um `name:` no frontmatter substitui o identificador derivado do caminho. ```text theme={null} .devin/agents/ ├── reviewer.md └── researcher/ └── AGENT.md ``` Também compatível: ```text theme={null} .agents/agents/ ├── reviewer.md └── researcher/ └── AGENT.md ``` ```text theme={null} # Linux/macOS ~/.config/devin/agents/ ├── reviewer.md └── researcher/ └── AGENT.md # Windows %APPDATA%\devin\agents\ ├── reviewer.md └── researcher\ └── AGENT.md ```
### Formato do Arquivo de Definição
Um arquivo de definição de subagente usa o mesmo frontmatter YAML das skills, seguido do prompt de sistema do subagente: ```markdown theme={null} --- name: reviewer description: Reviews code changes for correctness and style model: sonnet allowed-tools: - read - grep - glob - exec --- You are a code review subagent. Your job is to review code changes thoroughly and report findings back to the parent agent. Focus on: 1. Correctness — logic errors, edge cases, off-by-one mistakes 2. Security — potential vulnerabilities 3. Style — consistency with the rest of the codebase 4. Performance — obvious inefficiencies Always cite specific file paths and line numbers in your findings. ```
### Campos do frontmatter
| Campo | Tipo | Padrão | Descrição | | --------------- | ------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `name` | string | nome do arquivo ou diretório | Identificador do perfil (não deve entrar em conflito com perfis nativos) | | `description` | string | nenhum | Exibido ao agente ao selecionar um perfil | | `model` | string | modelo padrão de subagente (SWE-1.6 por padrão) — **não** o modelo do agente principal | Override o modelo usado por este subagente | | `allowed-tools` | lista | todas as ferramentas | Restringe quais ferramentas o subagente pode usar. Não pode conceder `ask_user_question`, que é sempre negado a subagentes. | | `max-nesting` | inteiro | nenhum | Override a profundidade máxima de aninhamento, permitindo que este subagente crie seus próprios subagentes |
### Como os subagentes personalizados são usados
Depois de definidos, os perfis de subagente personalizados aparecem ao lado dos perfis nativos. O agente vê uma descrição de cada perfil disponível e escolhe o mais apropriado ao iniciar um subagente. Você também pode pedir ao agente para usar um perfil específico pelo nome (por exemplo, "faça a revisão deste código usando o subagente reviewer"). Perfis de subagente personalizados que entram em conflito com o nome de um perfil nativo (por exemplo, `subagent_explore`, `subagent_general`) são ignorados, com um aviso.
### Importação de Outras Ferramentas
Subagentes personalizados também podem ser importados do formato de agente do Claude Code: | Origem | Padrão de arquivo | | --------------------- | -------------------------------------------------- | | `.claude/agents/*.md` | Cada arquivo `.md` se torna um perfil de subagente | Os arquivos de agente do Claude Code usam `tools` em vez de `allowed-tools` no frontmatter. Ambos os formatos têm suporte automático.
### Exemplos
#### Agente de Pesquisa em Modo Somente Leitura
```markdown theme={null} --- name: researcher description: Deep codebase research and architecture analysis model: sonnet allowed-tools: - read - grep - glob --- You are a research subagent specializing in codebase exploration. Your job is to thoroughly investigate a topic and report back with: - Relevant files and their purposes - Architecture patterns and dependencies - Code flow traces with specific line references Be exhaustive — search broadly and follow references. ```
#### Agente de execução de testes
```markdown theme={null} --- name: test-runner description: Runs tests and reports results allowed-tools: - read - grep - glob - exec --- Você é um subagente executor de testes. Execute os conjuntos de testes relevantes e reporte: - Quais testes passaram e falharam - Mensagens de falha e rastreamentos de pilha - Sugestões para corrigir as falhas ```