💬 Comms-first vs polling
Coordenação por shared memory força agentes a ficar verificando estado o tempo todo. SendMessage inverte: o agente recebe a notificação no momento em que precisa agir. É a diferença entre push e pull, e isso muda completamente a latência do swarm.
🎯Por que comms-first ganha
- •Latência real-time vs intervalo de polling
- •Sem race conditions em estado compartilhado
- •Mensagem carrega contexto — não precisa re-ler memória
- •Mais barato em tokens (sem polling reads desnecessários)
✓ Use SendMessage para
- ✓Pipeline handoff (architect→coder)
- ✓Redirecionamento de prioridade
- ✓Compartilhar resultado de outro agente
- ✓Shutdown gracioso
✗ Use memory para
- ✗Persistir entre sessões
- ✗Buscar padrões históricos
- ✗Estado consultado por muitos agentes
- ✗Trajetórias para SONA/ReasoningBank
👥 Named agents
Cada agente precisa de um nome para ser endereçável. Sem nome, ele é uma thread anônima e ninguém consegue mensagear. Use papéis claros: architect, coder, tester, reviewer.
🏷️Convenção de nomes
- Papel-curto: architect, coder, tester, reviewer, security
- Pluralizar quando houver múltiplos: coder-1, coder-2 (raro, mas válido)
- Evite nomes genéricos: agent1, helper, worker — não dizem nada
- Use kebab-case: security-auditor, perf-engineer
📝Exemplo correto de spawn
Task({
prompt: "Design a auth API. SendMessage to 'coder' when done.",
subagent_type: "system-architect",
name: "architect",
run_in_background: true
})💡Dica prática
Mantenha lista de nomes consistente entre projetos. Se você sempre usa architect / coder / tester / reviewer, cada agente fica com vocabulário familiar e os prompts ficam mais curtos.
🔁 Pipeline pattern (A→B→C)
O padrão mais comum: cada agente sabe quem mensagear depois. Você instrui no prompt: "quando terminar, SendMessage para X". Resultado: encadeamento natural, sem o lead servindo de roteador.
Architect
"Design and SendMessage to coder"
Cria o design, manda direto para o próximo no pipeline.
Coder
"Wait for design. Implement. SendMessage to tester"
Espera passivo, recebe mensagem, executa, encaminha.
Tester
"Wait for code. Test. SendMessage to reviewer"
Continua a corrente até o final do pipeline.
🚀Kickoff — só uma mensagem inicial
SendMessage({ to: "architect", summary: "Start API design", message: "[task]" })A partir daí, o pipeline anda sozinho.
📡 Fan-out / Fan-in
Para tarefas paralelizáveis (research em 3 áreas, audit de 5 módulos), spawne todos com run_in_background: true. Cada um termina, manda resultado de volta. Lead sintetiza no final.
🌐Topologia visual
┌→ researcher-1 ──→┐
lead ────┼→ researcher-2 ──→├──→ lead synthesizes
└→ researcher-3 ──→┘✓ Quando usar fan-out
- ✓Research em múltiplas fontes
- ✓Audit em vários módulos
- ✓Geração paralela (testes, docs)
- ✓Comparar abordagens (A vs B vs C)
✗ Evite fan-out quando
- ✗Tarefa tem dependências em série
- ✗Workers compartilham mesmo arquivo
- ✗Apenas 2 itens (overhead não compensa)
- ✗Síntese final é inviável (resultados muito divergentes)
👨💼 Supervisor / Worker
Padrão central: lead atribui tarefas via SendMessage, workers reportam de volta. Diferente do pipeline, aqui o lead é roteador ativo — útil quando a próxima tarefa depende do resultado da anterior.
🔄Fluxo Supervisor
lead ←──SendMessage──→ worker-1
lead ←──SendMessage──→ worker-2
lead ←──SendMessage──→ worker-3Lead orquestra centralizadamente — workers só executam.
📋Padrões de mensagem do lead
- Atribuição inicial: "Implemente OAuth2 flow..."
- Redirecionar prioridade: "Pause X, foque em Y primeiro"
- Repassar contexto: "O architect decidiu A. Use isso..."
- Pedido de status: "Como está o progresso?"
💡Dica prática
Use Supervisor quando você precisa tomar decisões a cada etapa. Use Pipeline quando o fluxo é determinístico e os agentes podem se virar sozinhos.
🛑 Graceful shutdown
Antes de chamar TeamDelete, mande {type: 'shutdown_request'} para cada agente. Isso permite que ele finalize trabalho em curso, salve estado e libere recursos. Matar abruptamente custa retrabalho.
📤Sintaxe do shutdown
SendMessage({
to: "developer",
message: { type: "shutdown_request" }
})⚠️Atenção
Nunca chame TeamDelete sem antes drenar agentes. Trabalho perdido + estado sujo na memória + telemetria incompleta. Esses 50ms de espera economizam horas depois.
📋Checklist de shutdown
- •Enviar shutdown_request a TODOS agentes
- •Aguardar confirmação ou timeout (10-30s)
- •Verificar se memória foi consolidada
- •Aí sim chamar TeamDelete
📋Resumo do Módulo
Próximo Módulo:
2.2 - Templates de Colaboração: 4 templates pré-built para feature, security, refactor e bugfix