🤖 O que é um agente
Um agente é uma instância especializada de IA com prompt sistêmico, papel definido, ferramentas específicas e memória própria. Pense em um colega de time: o tester só pensa em testes, o architect só desenha sistemas. Cada um cumpre seu pedaço bem feito.
🧬Anatomia de um agente
- •Role/Type — coder, tester, reviewer, architect, etc.
- •Name — identificador único para SendMessage
- •System prompt — instruções de comportamento
- •Tools — Read/Write/Bash conforme necessidade
- •Memory namespace — onde lê/escreve estado
💡Dica
Sempre dê name ao agente: name: "architect". Sem nome, ele não recebe mensagens via SendMessage e sua coordenação quebra.
👥 60+ tipos disponíveis
Ruflo traz 60+ tipos pré-prontos agrupados em categorias. Você raramente precisa criar um do zero — combine os existentes.
📚Categorias principais
- Core Dev — coder, reviewer, tester, planner, researcher
- Especializados — security-architect, security-auditor, perf-engineer, memory-specialist
- Coordenação — hierarchical-coordinator, mesh-coordinator, adaptive-coordinator
- GitHub — pr-manager, code-review-swarm, issue-tracker, release-manager
- SPARC — sparc-coord, specification, pseudocode, architecture, refinement
- Testing — tdd-london-swarm, production-validator
📊Distribuição por uso
- 5 agentes core resolvem 80% das tarefas de coding
- 15 especializados cobrem casos como security, perf, ML
- 10 GitHub automatizam workflow de PRs e issues
- 30+ outros para SPARC, consenso, validação e teste
👑 Topologia hierarchical
Topologia hierarchical é o default anti-drift. Uma rainha (coordinator) controla os workers diretamente. Decisões centralizadas, comunicação previsível, ideal para 6-8 agentes em coding diário.
👑Quando hierarchical brilha
- •Time pequeno (4-8 agentes) com papéis claros
- •Tarefas que pedem ordem (architect → coder → tester)
- •Quando consistência importa mais que paralelismo total
- •Anti-drift: rainha mantém contexto autoritativo
✓ Vantagens
- ✓Anti-drift garantido
- ✓Debug fácil (uma fonte de verdade)
- ✓Consenso Raft tolera f < n/2
- ✓Latência previsível
✗ Limitações
- ✗Rainha vira gargalo se sobrecarregada
- ✗Workers não trocam ideias entre si
- ✗Ruim para brainstorming aberto
- ✗Falha da rainha exige re-eleição
🕸️ Topologia mesh
Em mesh, todos falam com todos — peer-to-peer fully connected. Boa para brainstorming, pesquisa colaborativa e quando agentes precisam negociar entre si. Mas escala mal: 10 agentes geram até 45 conexões.
🕸️Quando mesh faz sentido
- •Pesquisa colaborativa (researchers debatendo achados)
- •Times pequenos (3-5 agentes)
- •Necessidade de consenso byzantino
- •Documentação coletiva
⚠️Cuidado
Não use mesh com 8+ agentes em tarefas de coding. O número de mensagens cresce O(n²) e a coordenação degrada. Drift acontece quando ninguém é a fonte da verdade.
⚖️ Hybrid e adaptive
Hybrid mistura: rainha controla núcleo, workers em mesh entre si. Adaptive muda topologia em tempo real conforme carga, latência e taxa de sucesso. São opções poderosas para casos avançados.
⚖️Casos reais
- •Hybrid — feature complexa: rainha decide arquitetura, coders trocam ideias entre si
- •Adaptive — workload imprevisível, escala dinamicamente
- •Hybrid-mesh — recomendação oficial para hive-mind production
💡Dica
Comece sempre com hierarchical. Só vá para hybrid/adaptive se identificar gargalo real na rainha ou variação grande de carga. Otimização prematura aqui custa caro.
🎯 Quando escolher cada uma
Heurística decisória rápida: olhe o tamanho do time, o tipo de tarefa e a tolerância a drift. Não há topologia certa universal — há a certa para cada contexto.
Coding diário (4-8 agentes)
→ hierarchical com consenso raft. Anti-drift garantido.
Pesquisa colaborativa (3-5 agentes)
→ mesh com gossip ou byzantine. Debate aberto entre peers.
Hive-mind enterprise (8+ agentes)
→ hybrid-mesh com byzantine. Rainha + peer-to-peer interno.
Workload imprevisível (variável)
→ adaptive. Topologia muda conforme métricas em tempo real.
📋Resumo do Módulo
Próximo Módulo:
1.4 - Memória Semântica: AgentDB+HNSW e busca vetorial