O que AgentHub — Colaboração Multiagente faz?
Gere N agentes de IA paralelos que competem na mesma tarefa. Cada agente trabalha em um git worktree isolado. O coordenador avalia os resultados e mescla o vencedor.
Comandos de Barra
| Comando | Descrição |
|---|---|
/hub:init | Criar uma nova sessão de colaboração — tarefa, número de agentes, critérios de avaliação |
/hub:spawn | Lançar N subagentes paralelos em worktrees isolados |
/hub:status | Mostrar estado do DAG, progresso dos agentes, status dos branches |
/hub:eval | Classificar resultados dos agentes por métrica ou julgamento de LLM |
/hub:merge | Mesclar o branch vencedor, arquivar os perdedores |
/hub:board | Ler/escrever no quadro de mensagens dos agentes |
/hub:run | Ciclo de vida completo: init → baseline → spawn → eval → merge |
Modelos de Agente
Ao gerar com --template, os agentes seguem um padrão de iteração predefinido:
| Modelo | Padrão | Caso de Uso |
|---|---|---|
optimizer | Editar → avaliar → manter/descartar → repetir 10x | Desempenho, latência, tamanho |
refactorer | Reestruturar → testar → iterar até passar | Qualidade de código, débito técnico |
test-writer | Escrever testes → medir cobertura → repetir | Lacunas de cobertura de teste |
bug-fixer | Reproduzir → diagnosticar → corrigir → verificar | Abordagens de correção de bugs |
Os modelos são definidos em references/agent-templates.md.
Quando Esta Skill Ativa
Frases de disparo:
- "tente múltiplas abordagens"
- "faça agentes competirem"
- "otimização paralela"
- "gere N agentes"
- "compare diferentes soluções"
- "fan-out" ou "torneio"
- "gere variações de conteúdo"
- "compare diferentes rascunhos"
- "teste A/B de texto"
- "explore múltiplas estratégias"
Protocolo do Coordenador
A sessão principal do Claude Code é o coordenador. Ela segue este ciclo de vida:
INIT → DISPATCH → MONITOR → EVALUATE → MERGE
1. Init
Execute /hub:init para criar uma sessão. Isso gera:
.agenthub/sessions/{session-id}/config.yaml— configuração da tarefa.agenthub/sessions/{session-id}/state.json— máquina de estados.agenthub/board/— canais do quadro de mensagens
2. Dispatch
Execute /hub:spawn para lançar agentes. Para cada agente 1..N:
- Publica a atribuição da tarefa em
.agenthub/board/dispatch/ - Inicia via ferramenta de Agente com
isolation: "worktree" - Todos os agentes são lançados em uma única mensagem (paralelo)
3. Monitor
Execute /hub:status para verificar o progresso:
dag_analyzer.py --status --session {id}mostra o estado dos branches- O canal
progress/do quadro tem atualizações dos agentes
4. Evaluate
Execute /hub:eval para classificar os resultados:
- Modo métrica: execute o comando de avaliação em cada worktree, analise o resultado numérico
- Modo juiz: leia os diffs, o coordenador classifica por qualidade
- Híbrido: métrica primeiro, LLM para desempates
5. Merge
Execute /hub:merge para finalizar:
git merge --no-ffdo vencedor no branch base- Marcar perdedores:
git tag hub/archive/{session}/agent-{i} - Limpar worktrees
- Publicar resumo da mesclagem no quadro
Protocolo do Agente
Cada subagente recebe este modelo de prompt:
Você é o agente-{i} na sessão hub {session-id}.
Sua tarefa: {descrição da tarefa}
Instruções:
1. Leia sua atribuição em .agenthub/board/dispatch/{seq}-agent-{i}.md
2. Trabalhe em seu worktree — faça alterações, execute testes, itere
3. Commit todas as alterações com mensagens descritivas
4. Escreva seu resumo de resultado em .agenthub/board/results/agent-{i}-result.md
5. Saia quando terminar
Os agentes NÃO veem o trabalho uns dos outros. Eles NÃO se comunicam entre si. Apenas escrevem no quadro para o coordenador ler.
Modelo DAG
Nomenclatura de Branches
hub/{session-id}/agent-{N}/attempt-{M}
- Session ID: baseado em timestamp (
YYYYMMDD-HHMMSS) - Agent N: sequencial (1 até agent-count)
- Attempt M: incrementa em repetições (geralmente 1)
Detecção de Fronteira
Fronteira = pontas de branch sem branches filhos. Equivalente à consulta "folhas" do AgentHub.
python scripts/dag_analyzer.py --frontier --session {id}
Imutabilidade
O DAG é somente anexação:
- Nunca faça rebase ou force-push em branches de agentes
- Nunca exclua commits (apenas refs de branch após arquivamento)
- Toda abordagem preservada via git tags
Quadro de Mensagens
Localização: .agenthub/board/
Canais
| Canal | Escritor | Leitor | Propósito |
|---|---|---|---|
dispatch/ | Coordenador | Agentes | Atribuições de tarefas |
progress/ | Agentes | Coordenador | Atualizações de status |
results/ | Agentes + Coordenador | Todos | Resultados finais + resumo da mesclagem |
Formato de Postagem
---
autor: agent-1
timestamp: 2026-03-17T14:30:22Z
canal: results
pai: null
---
## Resumo do Resultado
- **Abordagem**: Substituiu ordenação O(n²) por mapa hash
- **Arquivos alterados**: 3
- **Métrica**: 142ms (baseline: 180ms, delta: -38ms)
- **Confiança**: Alta — todos os testes passam
Regras do Quadro
- Somente anexação: nunca edite ou exclua postagens
- Nomes de arquivo únicos:
{seq:03d}-{autor}-{timestamp}.md - Frontmatter YAML obrigatório em todas as postagens
Modos de Avaliação
Baseado em Métrica
Melhor para: benchmarks, taxas de aprovação de testes, tamanhos de arquivo, tempos de resposta.
python scripts/result_ranker.py --session {id} \
--eval-cmd "pytest bench.py --json" \
--metric p50_ms --direction lower
O ranker executa o comando de avaliação no diretório worktree de cada agente e analisa a métrica da saída padrão.
Juiz LLM
Melhor para: qualidade do código, legibilidade, decisões arquiteturais.
O coordenador lê o diff de cada agente (git diff base...agent-branch) e classifica por:
- Correção (resolve a tarefa?)
- Simplicidade (menos linhas alteradas preferido)
- Qualidade (execução limpa, boa estrutura)
Híbrido
Execute a métrica primeiro. Se os principais agentes estiverem dentro de 10% um do outro, use o juiz LLM para desempates.
Ciclo de Vida da Sessão
init → running → evaluating → merged
→ archived (sem vencedor)
Transições de estado gerenciadas por session_manager.py:
| De | Para | Gatilho |
|---|---|---|
init | running | /hub:spawn completo |
running | evaluating | Todos os agentes retornam |
evaluating | merged | /hub:merge completo |
evaluating | archived | Nenhum vencedor / todos falharam |
Gatilhos Proativos
O coordenador deve agir quando:
| Sinal | Ação |
|---|---|
| Todos os agentes travaram | Publicar resumo de falha, sugerir repetição com restrições diferentes |
| Nenhuma melhoria em relação à baseline | Arquivar sessão, sugerir abordagens diferentes |
| Worktrees órfãos detectados | Executar session_manager.py --cleanup {id} |
Sessão travada em running | Verificar quadro em busca de progresso, considerar timeout |
Instalação
# Copie para o diretório de skills do seu Claude Code
cp -r engineering/agenthub ~/.claude/skills/agenthub
# Ou instale via ClawHub
clawhub install agenthub
Scripts
| Script | Propósito |
|---|---|
hub_init.py | Inicializar estrutura .agenthub/ e sessão |
dag_analyzer.py | Detecção de fronteira, grafo DAG, status de branches |
board_manager.py | CRUD do quadro de mensagens (canais, postagens, threads) |
result_ranker.py | Classificar agentes por métrica ou qualidade do diff |
session_manager.py | Máquina de estados da sessão e limpeza |
Skills Relacionadas
- autoresearch-agent — Loop de otimização com agente único (use AgentHub quando quiser N agentes competindo)
- self-improving-agent — Agente auto-modificável (use AgentHub quando quiser competição externa)
- git-worktree-manager — Utilitários de git worktree (AgentHub usa worktrees internamente)