Módulo 2.4 — Sub-agents e custom agents | DeerFlow 2.0

💡 Por que tanta gente confunde

Porque os dois "rodam LLM com tools" e os dois "retornam um resultado ao pai". A diferença é topológica: sub-agent é anônimo e efêmero; custom agent é nomeado e persistente. Esse módulo fixa a distinção e mostra quando cada um vence.

🆚 Sub-agent vs. custom agent

Vale começar pelo grid comparativo. Ele resume em uma tela a diferença que a maior parte das dúvidas de arquitetura não consegue articular.

🔹 Sub-agent

•Anônimo — sem nome no registry, spawn inline.
•Efêmero — vive só para a sub-task, morre depois.
•Herda tools do agente pai (menos as bloqueadas).
•Sem SOUL — recebe só a task e o prompt de isolamento.
•Uso típico: ler 50 artigos e resumir, rodar análise grande numa sessão.
•Observabilidade: aparece como span dentro do trace pai.

🔸 Custom agent

•Nomeado — security-auditor, legal-reviewer.
•Persistente — vive no registry, versionado, reusável.
•Tools próprias — subset controlado, política por agente.
•SOUL — identidade, tom, regras invariantes.
•Uso típico: personas com responsabilidade de domínio, canal IM dedicado.
•Observabilidade: trace separado com nome do agente.

💡 Regra prática de 10 segundos

"Vou precisar chamar isso com o mesmo nome, em múltiplas conversas, com personalidade consistente?" — se sim, custom agent. Se for só para isolar contexto num turno, sub-agent.

💽 SOUL de um custom agent

SOUL no DeerFlow é um acrônimo e, ao mesmo tempo, uma metáfora deliberada. É o que dá identidade a um custom agent. Sem SOUL, qualquer agente é só mais um wrapper de LLM. Com SOUL, você tem uma persona consistente que sobrevive a mudanças de modelo e a upgrades de harness.

🎯 Conceito Central

SOUL = Scope, Objectives, Unbreakable rules, Language/tone. Quatro blocos que, juntos, formam a identidade injetada no system prompt do agente antes de qualquer instrução específica.

•Scope — o que o agente cobre, o que delega, o que recusa.
•Objectives — em cada turno, o que ele tenta otimizar (precisão? velocidade? cobertura?).
•Unbreakable — regras de compliance, privacidade, safety. Viram guardrails pinados.
•Language/tone — como fala, quanto formaliza, se usa emoji, em que idioma.

💡 SOUL vai no YAML, não no corpo

Coloque SOUL no frontmatter estruturado do agente, não diluído no prompt em prosa. Isso permite que o harness injete como bloco invariante e valide por schema — atributos faltando viram erro de boot, não bug em runtime.

📄 RFC rfc-create-deerflow-agent

Existe uma RFC no repositório chamada rfc-create-deerflow-agent que é leitura obrigatória antes de criar o seu primeiro custom agent. Ela define o layout de diretórios, o contrato do registry e as políticas de nomeação. Ler antes evita retrabalho garantido.

Layout do diretório

app/agents/<name>/AGENT.md (frontmatter + body), agent.py (entry point), tools/ (restritas), evals/. A RFC proíbe imports cruzados entre agentes.

Contrato do registry

Todo agente deve expor uma função register() que devolve um objeto AgentSpec com name, soul, tools e middleware. O harness descobre agentes scanning app/agents/*/agent.py.

Política de nomeação

Kebab-case, sufixo semântico (-auditor, -reviewer, -bot proibido), sem números. Rename quebra todos os dispatches em andamento.

Lifecycle hooks

A RFC define on_activate, on_task_start, on_task_end, on_error. É onde ficam métricas, auditoria e integração com sistemas externos.

Eval obrigatório

Nenhum agente entra no registry de produção sem um eval mínimo checado em CI. É a tranca contra regressão de comportamento em upgrades.

🤔 Skill nova ou custom agent?

Depois de aprender skills no módulo 2.3 e custom agents aqui, a tentação é criar tudo como agente. Resista. Agente tem custo maior de manutenção, de review e de deploy. A decisão correta depende de quatro perguntas.

📊 Checklist de decisão

Precisa de personalidade consistente? Não → skill. Sim → agente.
Tem canal próprio? (ex: Slack channel dedicado) Não → skill. Sim → agente.
Precisa de tools restritas, não compartilhadas? Não → skill. Sim → agente.
Vai aparecer em relatórios de compliance separado? Não → skill. Sim → agente.

Regra: 3+ "sim" = custom agent. 0-2 = skill.

💡 Dica: comece sempre como skill

Mesmo que você "vá precisar de agente no final". Skill é 5x mais barata de criar e iterar. Se o projeto evoluir, promover skill → agente é trivial (é basicamente adicionar o AGENT.md e o register). Fazer o caminho contrário dói.

Exemplos por categoria

Quase sempre skill

• Gerar um PPT a partir de um outline
• Traduzir um trecho técnico
• Calcular análise estatística de CSV
• Consultar API pública de clima

Quase sempre custom agent

• Auditor de segurança num canal Slack dedicado
• Revisor legal de contratos com compliance próprio
• Suporte N1 em um produto específico
• Orquestrador de incidentes com runbooks

🧪 Lab: custom agent security-auditor no Slack

Construir um agente chamado security-auditor que só vive num canal Slack dedicado. Quando o time posta uma mensagem lá, o agente audita (secrets expostos, configs sensíveis, links suspeitos) e responde com parecer estruturado.

Passos do lab

1.
Criar o diretório: app/agents/security-auditor/ com AGENT.md, agent.py e tools/. Seguindo a RFC.
2.
Escrever SOUL no frontmatter do AGENT.md: scope = "auditoria leve de mensagens postadas em canais configurados"; objectives = "precisão sobre velocidade"; unbreakable = "nunca expor o conteúdo auditado fora do Slack, nunca tentar correção automática"; tone = "técnico, direto, em PT-BR".
3.
Implementar agent.py com register() retornando AgentSpec. Tools restritas: scan_for_secrets, classify_link, check_pii. Sem acesso ao filesystem nem ao search externo.
4.
Plugar no canal Slack: em app/channels/slack.py, adicione um roteamento: mensagens em #sec-audit vão direto ao security-auditor, bypassando o lead_agent. Isso é o que torna o agente "vivo num canal".
5.
Escrever eval: 10 mensagens golden (5 com issue, 5 limpas) e verificar que o agente chega no veredito certo. Rode com uv run python evals/security_auditor.py.
6.
Teste live: postar no #sec-audit uma mensagem contendo uma API key fake (sk-aaa...). O agente deve responder em até 30s com o parecer estruturado e recomendação de revogar.
7.
Validar no LangSmith: trace do agente aparece separado, com nome próprio. Confirme que nenhuma tool fora do whitelist foi chamada.

🚨 Cuidado com credenciais reais

No teste use sempre uma fake key. Nunca poste uma credencial real para testar o auditor — o log do próprio Slack mantém o texto original. Fake strings no formato certo enganam o scanner sem risco.

💡 Entregável

Diretório do agente commitado + log do Slack mostrando uma detecção real (fake key) + trace do LangSmith. Se o eval do passo 5 retornou 10/10 e o live test respondeu em <30s, o lab cumpriu o objetivo. Bônus: rodar o security-auditor também como dispatch do lead_agent em outro canal, só para validar que ele continua funcionando em modo "cidadão do catálogo".

📝 Resumo do Módulo

✓

Sub-agent = anônimo + efêmero — isolamento de contexto dentro de um turno.

✓

Custom agent = nomeado + persistente — identidade consistente, tools restritas, canal próprio.

✓

SOUL = Scope + Objectives + Unbreakable + Language — quatro blocos injetados no topo do prompt e validados por schema.

✓

RFC rfc-create-deerflow-agent é obrigatória — layout, registry, nomeação, lifecycle, eval.

✓

Comece como skill, promova a agente se necessário — o caminho contrário dói.

✓

security-auditor em canal Slack é o lab template — mostra persona + tools restritas + roteamento de canal em um único fluxo.

✓

Agent tem eval obrigatório em CI — garante que comportamento não regride em upgrade de harness.

Próximo Módulo:

2.5 — 🔧 Tools customizadas, MCP e grep/glob

Expor serviço como MCP, OAuth flows, LangChain tools e lab de API interna como MCP server.

← Módulo Anterior Voltar para Trilha Próximo Módulo →