Você pede para a Verboo Code revisar um PR e, no meio da conversa sobre a feature, o agente de programação enche o contexto com 40 arquivos lidos. Um subagente resolve isso: ele roda a tarefa num contexto próprio, com as ferramentas que você liberou e as instruções que você escreveu, e devolve só o resultado para a conversa principal. Neste tutorial você cria um, do arquivo ao uso.
O que é um subagente na Verboo Code?
É um agente especializado que a sessão principal chama pela ferramenta Agent. Cada subagente é um arquivo Markdown: o frontmatter diz nome, quando usar e quais ferramentas ele tem; o corpo do arquivo vira o prompt de sistema dele.
A Verboo Code já traz alguns de fábrica, como o general-purpose e o statusline-setup. Os seus entram na mesma lista.
Como criar um subagente pelo /agents?
Dentro da sessão:
/agentsAbre o menu de agentes, com os de fábrica e os seus. Para criar um novo, o assistente pergunta:
- Onde salvar:
Project (.verboo/agents/), que vai para o repositório, ouPersonal (~/.verboo/agents), que vale para você em todos os projetos. - Como criar: gerar a partir de uma descrição sua (opção marcada como recommended) ou
Manual configuration. - Depois: ferramentas, modelo, cor e memória.
No fim, o /agents grava um arquivo .md na pasta escolhida. Você pode criar esse mesmo arquivo na mão, que é o que a próxima seção mostra.
Como escrever o arquivo do subagente na mão?
mkdir -p .verboo/agentsE o arquivo .verboo/agents/revisor.md, um revisor que só lê e nunca edita:
---
name: revisor
description: Revisa o diff atual procurando bug, falta de teste e quebra de contrato. Use proactively depois de qualquer mudança em src/.
tools: Read, Grep, Glob, Bash
model: inherit
---
Você é um revisor de código sênior. Não edite nenhum arquivo.
1. Rode git diff para ver o que mudou.
2. Para cada arquivo alterado, procure: bug de lógica, caso de borda sem teste, mudança de assinatura pública.
3. Responda com uma lista curta, do problema mais grave ao menos grave, com arquivo e linha.
4. Se não achar nada, diga isso em uma linha.Rode /agents de novo e o revisor aparece na lista. Se você criou o arquivo com a sessão aberta e ele não apareceu, abra uma sessão nova.
Armadilha: arquivo sem name no frontmatter é ignorado em silêncio. A Verboo Code trata como documentação solta na pasta e não avisa. Com name mas sem description, o arquivo dá erro de leitura e o subagente também não carrega. Os dois campos são obrigatórios.
Quais campos o frontmatter aceita?
| Campo | O que faz | Se você não preencher |
|---|---|---|
name | Identificador do subagente | Arquivo ignorado |
description | Quando usar. É o que o agente principal lê para decidir delegar | Erro, não carrega |
tools | Lista separada por vírgula, ex.: Read, Grep, Glob, Bash | Todas as ferramentas da sessão |
disallowedTools | Ferramentas bloqueadas, mesmo que a lista libere | Nenhuma bloqueada |
model | inherit ou um dos apelidos do menu (sonnet, opus, haiku) | inherit: mesmo modelo da conversa |
effort | Nível de raciocínio do subagente | Padrão da sessão |
permissionMode | Modo de permissão próprio | Modo da sessão |
maxTurns | Limite de turnos antes de parar (inteiro positivo) | Sem limite próprio |
memory | Memória persistente: user, project ou local | Sem memória |
background | true faz rodar sempre em segundo plano | Roda em primeiro plano |
isolation | worktree roda numa worktree git isolada | Roda na pasta atual |
color | Cor do subagente na interface | Sem cor |
Atenção ao tools: omitir o campo libera tudo, mas escrever tools: vazio deixa o subagente sem nenhuma ferramenta. E se você ligar memory com uma lista de tools, a Verboo Code acrescenta Read, Write e Edit sozinha, porque o subagente precisa delas para ler e gravar a própria memória.
Como fazer a Verboo Code usar o subagente?
Dois jeitos. O direto é pedir pelo nome:
use o subagente revisor no que eu mudei hojeO agente principal chama a ferramenta Agent com o revisor, que lê o diff no contexto dele e devolve só a lista de problemas.
O outro é deixar o agente principal decidir. Ele escolhe pela description, então ela precisa dizer quando usar, não só o papel. "Revisor de código" é vago. "Use proactively depois de qualquer mudança em src/" é um gatilho: o prompt da ferramenta Agent instrui o modelo a usar sem você pedir quando a description diz que o subagente deve ser usado de forma proativa.
Onde a Verboo Code procura os subagentes?
| Pasta | Escopo |
|---|---|
~/.verboo/agents/ | Seus, em todos os projetos |
.verboo/agents/ ou .claude/agents/ | Do projeto. Vale da pasta atual subindo até a raiz do repositório git |
Subagentes que você já tinha em .claude/agents/ no projeto funcionam sem copiar. A pasta do usuário é só ~/.verboo/agents/; se você mudou a configuração com VERBOO_CONFIG_DIR, ela passa a ser $VERBOO_CONFIG_DIR/agents/.
Mesmo name em dois lugares? Ganha o mais específico, nesta ordem crescente: de fábrica, plugin, seu, do projeto, da flag --agents e, por último, o gerenciado pela empresa. Um general-purpose.md no projeto substitui o de fábrica para quem trabalha nele.
Dá para definir um subagente só para uma execução?
Dá, com a flag --agents, que recebe um JSON. Útil em script e CI, sem criar arquivo:
verboo --agents '{"revisor": {"description": "Revisa o diff atual", "prompt": "Você é um revisor de código. Não edite arquivos.", "tools": ["Read", "Grep", "Glob", "Bash"]}}'No JSON, description e prompt são obrigatórios, e tools é uma lista. O subagente existe só naquela sessão. Já a flag --agent <nome>, no singular, é outra coisa: escolhe o agente da própria sessão principal.
Subagente, skill ou AGENTS.md: qual usar?
| Subagente | Skill | AGENTS.md | |
|---|---|---|---|
| Contexto | Próprio, separado da conversa | O da conversa | O da conversa |
| Ferramentas | Só as que você listar | As da sessão | As da sessão |
| Bom para | Tarefa que lê muito e devolve pouco: revisão, busca, triagem | Procedimento repetível que você chama por nome | Regra permanente do projeto |
Se a tarefa precisa do que já está na conversa, use uma skill. Se é regra que vale sempre, vai no AGENTS.md, como no tutorial de instruções permanentes com /memory. Subagente é para isolar o trabalho pesado do contexto principal, o que combina com acompanhar o espaço pelo /context.
Cada subagente abre o próprio contexto e lê os arquivos de novo, então delegar gasta mais tokens que fazer tudo na conversa principal. Na Verboo Code os tokens são ilimitados, e você pode delegar sem fazer conta.
Comportamento verificado no código-fonte da Verboo Code (verbeux-ai/code, v0.15.41) em 05/11/2026: src/commands/agents, src/tools/AgentTool/loadAgentsDir.ts, src/tools/AgentTool/prompt.ts, src/components/agents, src/utils/model/agent.ts, src/utils/markdownConfigLoader.ts e src/main.tsx.
