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.

Perfis de subagente

Cada subagente usa um perfil específico que determina suas capacidades. Há dois perfis nativos:

Perfil	Descrição	Acesso às ferramentas
`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)
`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)

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.

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.

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 do subagente	Substitui o modelo usado por este subagente
`allowed-tools`	lista	todas as ferramentas	Restringe quais ferramentas o subagente pode usar
`permissions`	objeto	herdado	Overrides 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

Documentation Index

​Como os subagentes funcionam

Primeiro plano

Segundo plano

​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

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