Imagine o Claude Code como um consultor com uma pequena equipa. Fala apenas com o consultor. Ele encaminha as subtarefas para especialistas e, no fim, comunica-lhe o resultado.
É exatamente isso que são os sub-agents. Não é hype, é uma ferramenta prática de divisão do trabalho. Este artigo mostra quando compensam — e quando não.
O que é um sub-agent
A sessão principal é o orquestrador. É a instância com quem fala. É ela que arranca sub-agents autónomos e lhes atribui tarefas.
Cada sub-agent trabalha num contexto próprio e novo. Devolve apenas um resultado compacto. Os sub-agents falam com a sessão principal, nunca entre si.
Porque compensam
Há quatro razões que tornam os sub-agents úteis.
- Contexto limpo. A pesquisa, os registos longos e os relatórios extensos ficam fora do chat principal.
- Trabalho em paralelo. Muitas tarefas independentes correm ao mesmo tempo em vez de umas atrás das outras.
- Modelos baratos. O trabalho de rotina fica a cargo de um modelo pequeno, a direção a cargo de um modelo forte.
- Revisões honestas. Um agente novo não está condicionado a concordar consigo.
Integrados ou construídos por si
O Claude Code traz sub-agents genéricos. Além disso, pode construir agentes próprios e especializados. Um sub-agent não é mais do que um ficheiro Markdown.
No topo está o frontmatter YAML: nome, descrição, modelo e ferramentas permitidas. A descrição é a alavanca mais importante. É ela que decide se o agente serve para a tarefa.
Um erro frequente na prática é uma aspa esquecida. A estrutura parte-se e o agente nunca chega a arrancar.
Ao nível do projeto ou global
Os agentes ligados ao projeto ficam no repositório e viajam com ele. Os agentes globais ficam na sua pasta de utilizador e pertencem apenas a si.
Regra prática: se a equipa o vai usar, pertence ao projeto. Movê-lo é trivial, afinal é apenas um ficheiro.
Quando usar um sub-agent — e quando não
Nem todas as tarefas precisam de um sub-agent. Demasiados conduzem muitas vezes a piores resultados. Uma pergunta simples ajuda.
Isto vai despejar já uma montanha de informação no meu chat que nunca mais volto a ler? Se sim, delegue. Se não, fica na sessão principal.
Use sub-agents quando forem lidos muitos ficheiros, quando houver tarefas a correr em paralelo ou quando quiser uma revisão imparcial.
Prescinda deles em alterações pequenas, em passos que dependem uns dos outros ou quando o agente teria de fazer uma pergunta de esclarecimento.
Fluxos de trabalho dinâmicos e «ultra code»
Desde o Opus 4.8 existem fluxos de trabalho dinâmicos. A sessão principal arranca então automaticamente muitos sub-agents em paralelo. É poderoso, mas consome depressa o seu limite de sessão.
Foi por isso que a palavra-gatilho mudou de «workflow» para «ultra code». Assim, nenhum fluxo de trabalho grande arranca por engano. Use a ferramenta de forma consciente.
Levar as permissões a sério
Se um agente pode ler ou alterar dados, tem de partir do princípio de que um dia o fará. Por isso, liberte apenas as ferramentas de que ele realmente precisa.
Para agentes de pesquisa e de verificação isso significa, na maior parte dos casos: só leitura. Em ficheiros de agentes de origem externa, verifique previamente possíveis prompt injections.
A minha promessa
Os sub-agents não são um fim em si mesmos. São uma ferramenta de divisão do trabalho. O ganho é menos ruído no chat, custos mais baixos e um olhar imparcial sobre o seu trabalho.
A minha promessa: só recomendo sub-agents onde ajudem de forma mensurável. A automatização é mais do que hype de IA.
Nota: este artigo resume as ideias centrais de um vídeo do YouTube em inglês sobre os sub-agents do Claude Code e enquadra-as numa perspetiva de consultoria. Fonte: youtube.com/watch?v=e18sdZLwP7o.