> ## 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 no Devin CLI que rodam em primeiro ou em segundo plano, com seus próprios perfis e permissões

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 principal, mas opera em sua própria linha de conversa -- ele não herda o histórico de conversa do agente principal. 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:

> [card] Primeiro plano
>
> É 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.

> [card] Segundo plano
>
> É 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.

> [!NOTE]
>
> 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.

> [!NOTE]
>
> 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](https://docs.devin.ai/pt-BR/cli/subagents.md#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** — escolhido pelo roteador de subagentes no momento em que o subagente é criado, a menos que um administrador fixe um modelo; não é a seleção do seu seletor de modelos | Depende do modelo padrão de subagente, não da 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 |

> [!WARNING]
>
> `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 servidor 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**, o roteador escolhe o primeiro modelo elegível de uma lista ordenada, então o modelo resultante pode variar conforme o nível do seu plano, a disponibilidade de modelos e a política de modelos da sua organização. A lista de roteamento pode mudar ao longo do tempo, então não conte com o fato de um subagente sempre usar um modelo específico.

> [!NOTE]
>
> 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 três 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 do subagente, em vez do modelo selecionado. 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 principal. Uma [skill](https://docs.devin.ai/pt-BR/cli/extensibility/skills) executada em um subagente também pode definir `model:` no frontmatter para aplicar override ao modelo do perfil.
3. **Defina seu próprio modelo padrão de subagente.** `agent.subagent_model` no seu [arquivo de configuração](https://docs.devin.ai/pt-BR/cli/reference/configuration/config-file.md#agent) substitui o modelo padrão de subagente nas suas sessões. Essa configuração tem precedência tanto sobre o roteador de subagentes quanto sobre um modelo que um administrador tenha fixado como padrão da equipe, mas não reativa os subagentes quando a configuração do administrador está definida como **Nenhum**:

   ```json theme={null}
   // ~/.config/devin/config.json
   {
     "agent": {
       "subagent_model": "swe-1-6-fast"
     }
   }
   ```

   Ela se aplica ao `subagent_explore` e aos subagentes personalizados que não fixam um `model:`; o `subagent_general` continua seguindo o modelo do agente principal. O modelo precisa ser permitido pela sua organização; caso contrário, a configuração é ignorada e o padrão da equipe é usado. A alteração vale para novas sessões.

### 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](https://mintcdn.com/cognitionai/d7_AE5155dfGCsnK/images/cli/default-subagent-model-setting.png?fit=max\&auto=format\&n=d7_AE5155dfGCsnK\&q=85\&s=e924249f64bf6ac6e0ffcf59b289aeb3)

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 servidor no momento da criação. O modelo selecionado depende do nível do seu plano, da disponibilidade de modelos e dos modelos permitidos pela sua organização. |
| **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](https://docs.devin.ai/pt-BR/cli/reference/configuration/config-file.md#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.

> [!NOTE]
>
> 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 (selecionado pelo roteador, a menos que um administrador fixe um) |
| `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 |

> [!NOTE]
>
> 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.

> [!TIP]
>
> 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 <kbd>↓</kbd> no campo de entrada e, em seguida, <kbd>Enter</kbd> 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 <kbd>Ctrl</kbd>+<kbd>B</kbd> 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 <kbd>f</kbd> em um subagente em segundo plano que esteja em execução. A saída do subagente será exibida inline.

> [!NOTE]
>
> 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 <kbd>x</kbd> no subagente em execução.
2. **Subagente em primeiro plano:** Pressione <kbd>Ctrl</kbd>+<kbd>C</kbd> com o campo de entrada vazio, ou <kbd>Esc</kbd> duas vezes, para cancelar o subagente em primeiro plano que está em execução. Se houver um rascunho em andamento, <kbd>Ctrl</kbd>+<kbd>C</kbd> primeiro limpa o rascunho.

***

## 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)
```

> [!WARNING]
>
> 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

> [!WARNING]
>
> 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/<name>.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/<name>/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.

> [tab] Específico do projeto
>
> ```text theme={null}
> .devin/agents/
> ├── reviewer.md
> └── researcher/
>     └── AGENT.md
> ```
>
> Também compatível:
>
> ```text theme={null}
> .agents/agents/
> ├── reviewer.md
> └── researcher/
>     └── AGENT.md
> ```

> [tab] Global
>
> ```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 (selecionado pelo roteador, a menos que um administrador faça pin em um) — **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. O alias `tools` também é aceito. |
| `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.

### 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
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.