Subagentes - Devin Docs

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:

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.

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.

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) consomem mais créditos.

Como o custo aumenta com o número de subagentes, tarefas que se desdobram em muitos subagentes (ou os aninham) 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` em `AGENT.md`, 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 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:

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.
Fixe um modelo em um perfil de subagente personalizado. model: em AGENT.md é a única forma de executar um subagente com capacidade de escrita em um modelo diferente do agente pai. Uma skill 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.

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

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.

Cancelando subagentes

Você pode cancelar um subagente em execução de duas maneiras:

No painel de subagentes: Abra o painel e pressione x no subagente em execução.
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, overrides de modelo e permissões — 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 AGENT.md dentro de um diretório nomeado em agents/. O nome do diretório se torna o identificador do perfil.

Específico do projeto
Global

.devin/agents/
└── reviewer/
    └── AGENT.md

Também é compatível com:

.agents/agents/
└── reviewer/
    └── AGENT.md

# Linux/macOS
~/.config/devin/agents/
└── reviewer/
    └── AGENT.md

# Windows
%APPDATA%\devin\agents\
└── reviewer\
    └── AGENT.md

Formato do AGENT.md

Um arquivo AGENT.md usa o mesmo frontmatter YAML das skills, seguido do prompt de sistema do subagente:

---
name: reviewer
description: Reviews code changes for correctness and style
model: sonnet
allowed-tools:
  - read
  - grep
  - glob
  - exec
permissions:
  allow:
    - Exec(git diff)
    - Exec(git log)
  deny:
    - write
    - edit
---

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 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	Substitui 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.
`permissions`	objeto	herdado	override de permissão (`allow`, `deny`, `ask`)
`max-nesting`	inteiro	nenhum	Substitui 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

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

---
name: test-runner
description: Runs tests and reports results
allowed-tools:
  - read
  - grep
  - glob
  - exec
permissions:
  allow:
    - Exec(npm run test)
    - Exec(cargo nextest)
    - Exec(pytest)
---

You are a test runner subagent. Run the relevant test suites and report:
- Which tests passed and failed
- Failure messages and stack traces
- Suggestions for fixing failures

​Como os subagentes funcionam

Primeiro plano

Segundo plano

​Custo dos subagentes

​Qual modelo um subagente usa?

​Influenciando o modelo

​Controles do Enterprise

​Perfis de subagente

​Permissões de ferramentas

​Monitoramento de subagentes

​Indicador de subagente

​Painel de subagentes

​Alternar entre primeiro plano e segundo plano

​Cancelando subagentes

​Retomando subagentes

​Profundidade de aninhamento

​Subagentes personalizados

​Criando um subagente personalizado

​Formato do AGENT.md

​Campos do frontmatter

​Como os subagentes personalizados são usados

​Importação de Outras Ferramentas

​Exemplos

​Agente de Pesquisa em Modo Somente Leitura

​Agente de execução de testes

Como os subagentes funcionam

Custo dos subagentes

Qual modelo um subagente usa?

Influenciando o modelo

Controles do Enterprise

Perfis de subagente

Permissões de ferramentas

Monitoramento de subagentes

Indicador de subagente

Painel de subagentes

Alternar entre primeiro plano e segundo plano

Cancelando subagentes

Retomando subagentes

Profundidade de aninhamento

Subagentes personalizados

Criando um subagente personalizado

Formato do AGENT.md

Campos do frontmatter

Como os subagentes personalizados são usados

Importação de Outras Ferramentas

Exemplos

Agente de Pesquisa em Modo Somente Leitura

Agente de execução de testes