swarma — ciclo de experimentos de crescimento para equipes de agentes

Quando usar esta skill

Use swarma quando o usuário quiser:

Executar experimentos de crescimento (hooks, landing pages, outreach, preços, ativação, retenção)
Construir equipes de agentes que aprendem e melhoram através de testes A/B, não apenas executam uma vez
Obter um playbook validado do que realmente funciona para seu público/produto específico
Testar ideias em escala (50+ experimentos/semana em vez de 2-5)
Substituir "já tentamos, não funcionou" por dados de experimento registrados, analisados e pesquisáveis

Frases de gatilho: "testar o que funciona", "otimizar meu funil", "encontrar os melhores hooks", "executar experimentos", "teste A/B", "o que está funcionando", "construir um playbook", "experimentos de crescimento", "melhorar conversão"

NÃO usar quando: o usuário quer automação de fluxo de trabalho (use n8n/Make), memória de conversa (use honcho) ou pipelines de agente único (use CrewAI/AutoGen). swarma é especificamente para loops de experimentos que melhoram ao longo do tempo.

Referência rápida

Comandos de relance

Comando	O que faz	Quando usar
`swarma init`	Criar instância + equipe inicial	Configuração inicial
`swarma cycle <equipe>`	Executar um ciclo de experimento	Testes, execuções manuais
`swarma cycle <equipe> --topic "..."`	Executar ciclo com um tópico específico	Experimentos ad-hoc
`swarma team create <nome> --from-goal "..."`	Gerar equipe a partir de uma meta	Iniciar uma nova área de experimento
`swarma team show <nome>`	Inspecionar a configuração de uma equipe	Revisar o que foi gerado
`swarma team list`	Mostrar todas as equipes	Visão geral
`swarma status`	Custos, execuções recentes, experimentos	Verificação de saúde
`swarma metric log <equipe> <agente> <valor>`	Registrar métrica externa	Alimentar dados do mundo real
`swarma metric import <equipe> <csv>`	Importar métricas em lote	Ingestão de dados em massa
`swarma metric show <equipe>`	Visualizar métricas registradas	Revisar desempenho
`swarma serve --port 8282`	Iniciar API REST	Integrações externas
`swarma serve --mcp`	Iniciar servidor MCP	Integração com Claude Code / Hermes
`swarma run`	Iniciar motor agendado	Operação contínua
`swarma expert list`	Navegar pelas lentes de raciocínio	Explorar frameworks de especialistas

Decisão: Qual template de equipe?

Usuário quer melhorar...	Use esta equipe	Etapa AARRR
Linhas de abertura / hooks	`hook-lab`	Aquisição
Cópia de landing page	`landing-lab`	Aquisição
Rankings SEO	`seo-engine`	Aquisição
Taxas de resposta em outreach frio	`cold-outbound`	Aquisição
Conteúdo multiplataforma	`channel-mix`	Aquisição
Onboarding signup-para-valor	`activation-flow`	Ativação
Preços e pacotes	`pricing-lab`	Receita
Churn e retenção	`retention-squad`	Retenção
Loops virais e indicações	`referral-engine`	Indicação
Posicionamento de mercado	`competitive-intel`	--
Pipeline de vídeo curto	`faceless-factory`	Aquisição
Teste de criativos de anúncio	`ad-creative-lab`	Aquisição
Simulação de conteúdo UGC	`ugc-factory`	Aquisição
SEO programático	`programmatic-seo`	Aquisição
Crescimento de newsletter	`newsletter-engine`	Retenção
Loops pagos + orgânicos	`acquisition-squad`	Aquisição
Crescimento liderado por comunidade	`community-engine`	Retenção
Otimização de comércio com IA	`agentic-storefront`	Receita

Decisão: Gerar vs Template?

Situação	Abordagem
Usuário tem uma meta específica e bem definida	`swarma team create --from-goal` (deixe a IA desenhar a equipe)
Meta corresponde a um template de equipe existente	Copiar template, depois personalizar
Usuário quer experimentar amplamente	Comece com `hook-lab` (mais geral)
Usuário não sabe por onde começar	Pergunte sobre o gargalo do funil dele, depois escolha

O Loop GROWS (Conceito Central)

Cada ciclo de experimento segue cinco etapas:

  Gerar          Executar        Observar      Avaliar       Empilhar
 hipótese --> experimento --> sinal --> veredito --> playbook
     ^                                                  |
     └──────────────────────────────────────────────────┘

Etapa	O que acontece	Onde no código
G -- Gerar	Agente lê `strategy.md`, propõe uma hipótese	`core/cycle.py`
R -- Executar	Agente executa com hipótese ativa, produz saída	`flow/executor.py`
O -- Observar	LLM barato separado pontua a saída (1-10, decimais forçados)	`core/agent.py`
A -- Avaliar	Após 5 ciclos, comparar média vs linha de base. >20% = manter/descartar	`core/experiment.py`
E -- Empilhar	Padrões validados escritos em `strategy.md` + playbook	`core/agent.py`

Números-chave:

Limiar de veredito: 20% de melhoria para manter, 20% de declínio para descartar
Padrão min_sample_size: 5 ciclos antes do veredito
Pontuação: escala 1-10 com decimais forçados (7.3, não 7)

Guia de configuração

Plataforma: Claude Code / Claude Desktop

pip install swarma
swarma init

Adicione ao .mcp.json:

{
  "mcpServers": {
    "swarma": {
      "command": "swarma",
      "args": ["serve", "--mcp"],
      "env": { "OPENROUTER_API_KEY": "sk-or-..." }
    }
  }
}

Importante: OPENROUTER_API_KEY deve estar no bloco env do MCP. O .env da instância não é herdado por subprocessos.

Plataforma: Hermes (via terminal)

Hermes tem acesso ao terminal — pode executar comandos CLI do swarma diretamente. MCP não é necessário.

pip install swarma
swarma init

Depois diga ao Hermes: "execute swarma cycle hook-lab --topic 'IA é superestimada'"

Hermes lê a saída do terminal e age sobre os resultados. Para acesso estruturado, adicione MCP:

# hermes config.yaml
mcp_servers:
  swarma:
    transport: stdio
    command: swarma
    args: ["serve", "--mcp"]
    env:
      OPENROUTER_API_KEY: "sk-or-..."

Plataforma: OpenClaw

pip install swarma
swarma init

Configure como ferramenta MCP ou use acesso ao terminal dependendo da sua configuração OpenClaw.

Plataforma: CLI (standalone)

pip install swarma
swarma init                                        # cria instância + equipe inicial
swarma cycle starter --topic "por que startups falham?"   # executa um ciclo
swarma status                                      # verifica custos, execuções, experimentos

A partir do código fonte

git clone https://github.com/glitch-rabin/swarma.git
cd swarma && pip install -e .
swarma init

Configuração de ambiente

Após swarma init, adicione sua chave de API:

echo "OPENROUTER_API_KEY=sk-or-..." >> ~/.swarma/instances/default/.env

Obtenha uma chave em openrouter.ai/keys.

Opcional (para conhecimento entre equipes):

# Necessário apenas ao executar 3+ equipes
echo "QMD_ENDPOINT=http://localhost:8181/mcp" >> ~/.swarma/instances/default/.env

Fluxo de integração

Quando um usuário quiser configurar o swarma, siga esta sequência. O gerador de equipe é o caminho mais rápido — não faça os usuários configurarem agentes manualmente.

Etapa 1: Entender a meta

Pergunte:

"O que você quer melhorar?" (conversão, engajamento, taxa de resposta de outreach, rankings SEO, etc.)
"Quem é seu público?" (usuários B2B SaaS, comunidade cripto, compradores corporativos, etc.)
"Como é o sucesso?" (mais inscrições, CTR maior, melhores taxas de resposta, etc.)

Etapa 2: Instalar

pip install swarma
swarma init --yes

Etapa 3: Gerar a equipe

Este é o passo principal. Use o gerador de equipe em vez de escolher templates.

swarma team create growth-lab \
  --from-goal "otimizar conversão de landing page para nosso SaaS B2B" \
  --context "empresa de ferramentas para desenvolvedores, 500 usuários gratuitos, 2% de conversão para pago" \
  --budget 30

O gerador:

Projeta a equipe (2-5 agentes com papéis específicos)
Escolhe modelos que se ajustam a cada papel
Escreve instruções dos agentes e padrões de experimento
Cria uma primeira hipótese de experimento pronta para executar

Revise o que foi gerado:

swarma team show growth-lab

Etapa 4: Executar o primeiro ciclo

swarma cycle growth-lab

Saída esperada:

Executando ciclo: growth-lab
  fluxo: researcher -> copywriter -> judge
  agentes: ['researcher', 'copywriter', 'judge']

                              Ciclo: growth-lab
  Agente      Modelo             Custo       Prévia da Saída
  researcher sonar-pro          $0.000384  **Tópico:** 52% dos executivos...
  copywriter qwen3.5-plus-02-15 $0.000746  [A] Enviamos 4.382 e-mails frios...
  judge      mistral-nemo       $0.000416  **Variações de Hook:** A: "Você...

  duração: 43.9s | custo total: $0.001546 | agentes: 3

Etapa 5: Executar mais ciclos e revisar

swarma cycle growth-lab                    # executar outro ciclo
swarma cycle growth-lab --topic "ângulo específico"  # com um tópico
swarma status                              # verificar progresso

Após 5 ciclos, o motor de experimento emite seu primeiro veredito. O arquivo de estratégia evolui automaticamente.

Uso diário

Executando experimentos

# Ciclo único
swarma cycle hook-lab

# Com um tópico específico
swarma cycle hook-lab --topic "Agentes de IA estão se tornando commodity"

# Contínuo (equipes com cron executam automaticamente)
swarma run

# Contínuo com servidor API
swarma run --port 8282

Alimentando métricas reais

A autoavaliação do LLM é um proxy inicial. Para produção, alimente sinais do mundo real:

# Registrar uma única métrica
swarma metric log hook-lab copywriter 4.2 --metric ctr_pct

# Anexar a um experimento específico
swarma metric log hook-lab copywriter 127 --metric impressions --exp 3

# Adicionar uma nota
swarma metric log hook-lab copywriter 5.1 --metric ctr_pct --note "do analytics do linkedin"

# Importar em lote de CSV
swarma metric import hook-lab metrics.csv

# Visualizar métricas registradas
swarma metric show hook-lab

Formato CSV: agente,valor,nome_da_metrica,nota

copywriter,4.2,ctr_pct,semana 1
copywriter,5.1,ctr_pct,semana 2
researcher,7.8,relevance_score,

Usando templates de equipe

# Copiar um template para sua instância
cp -r "$(python -c "import swarma; print(swarma.__path__[0])")/examples/hook-lab" \
  ~/.swarma/instances/default/teams/hook-lab

# Ou se você clonou o repositório
cp -r examples/hook-lab ~/.swarma/instances/default/teams/hook-lab

# Executar
swarma cycle hook-lab --topic "por que a maioria das startups falha"

Verificando status

swarma status

Mostra: todas as equipes, execuções recentes, custos (hoje + este mês), planos pendentes, estatísticas da fila.

Referência de Ferramentas MCP

Quando conectado via MCP, estas 16 ferramentas estão disponíveis:

Ferramenta	Descrição	Parâmetros
`swarma_health`	Verificar se swarma está funcionando	--
`swarma_list_teams`	Listar todas as equipes configuradas	--
`swarma_get_team`	Obter detalhes da equipe (agentes, fluxo, cronograma)	`team_id`
`swarma_list_agents`	Listar agentes em uma equipe	`team_id`
`swarma_run_agent`	Executar um único agente com contexto opcional	`team_id`, `agent_id`, `context?`
`swarma_run_cycle`	Executar um ciclo completo para uma equipe	`team_id`, `topic?`
`swarma_status`	Status da instância (custos, execuções, experimentos)	--
`swarma_costs`	Detalhamento de custos (hoje, este mês)	--
`swarma_list_plans`	Mostrar planos de experimento pendentes	`team_id?`
`swarma_approve_plan`	Aprovar um plano de experimento pendente	`plan_id`
`swarma_reject_plan`	Rejeitar um plano pendente	`plan_id`, `reason?`
`swarma_get_outputs`	Saídas recentes dos agentes	`team_id?`, `agent_id?`, `limit?`
`swarma_list_tools`	Listar ferramentas de agente disponíveis	--
`swarma_list_experts`	Navegar pelas lentes de raciocínio de especialistas	--
`swarma_get_expert`	Obter detalhes do especialista por ID	`expert_id`
`swarma_generate_team`	Gerar uma nova equipe a partir de uma meta	`name`, `goal`, `context?`, `budget?`

Fluxos de Trabalho MCP Comuns

"O que está acontecendo?"

swarma_status — visão geral
swarma_get_outputs — saídas recentes dos agentes
swarma_list_plans — experimentos pendentes

"Executar um experimento"

swarma_run_cycle com team_id e tópico opcional
swarma_get_outputs para revisar resultados

"Iniciar uma nova área de experimento"

swarma_generate_team com meta e contexto
swarma_get_team para revisar o que foi gerado
swarma_run_cycle para iniciar

"O que está funcionando?"

swarma_get_outputs para resultados recentes
Leia o strategy.md da equipe para padrões validados

Referência de Configuração de Equipe

Uma equipe é uma pasta. Nenhum código necessário.

teams/my-squad/
├── team.yaml          # meta, fluxo, cronograma, orçamento
├── program.md         # contexto e restrições da equipe
└── agents/
    ├── researcher.yaml
    ├── writer.yaml
    └── strategy.md    # conhecimento de crescimento pré-semeador (evolui automaticamente)

team.yaml

name: my-squad
goal: encontrar o que funciona.
flow: "researcher -> writer"        # sequencial
# flow: "researcher -> [writer, analyst]"  # paralelo
schedule: "0 8 * * 1-5"            # opcional: dias úteis às 8h
budget: 30                          # opcional: orçamento mensal em $

agent.yaml

id: writer
name: Escritor
instructions: |
  transforme pesquisa em um post. máx. 200 palavras.
  hook na primeira linha. voz de profissional.
model: qwen/qwen3.5-plus-02-15     # opcional: substituir roteamento padrão
metric:
  name: quality_content
  target: 8.0
experiment_config:
  min_sample_size: 5
  auto_propose: true

strategy.md (evolui automaticamente)

Começa com conhecimento semeador, cresce com cada experimento validado:

### Padrões Validados

**Especificidade vence**
- Hooks com números específicos superam alegações vagas em 2-3x em salvamentos
- "47% das startups" > "a maioria das startups"

### Antipadrões (Descartados)
- Aberturas inspiracionais genéricas: -23% vs linha de base. Descartar.

### Padrões para Testar
- [ ] Confissão em primeira pessoa vs estudo de caso em terceira pessoa
- [ ] Hooks ancorados no tempo ("Em 2024...") vs hooks atemporais

DSL de Fluxo

# Sequencial: a executa, saída passa para b
flow: "researcher -> writer"

# Paralelo: a executa, depois b e c executam concorrentemente
flow: "researcher -> [writer, analyst]"

# Misto:
...

Perguntar na sua IA favorita

Documentação