Início com Ruflo: um motor multiagente que se autoevolui

Apresentação do projeto

Ruflo é uma camada de orquestração multiagente para o Claude Code. Em uma frase, ele faz isto: transformar o Claude Code de um “assistente de perguntas e respostas” em uma equipe de IA que colabora, lembra e se autoevolui.

O Ruflo originalmente se chamava Claude Flow, desenvolvido pela RuvNet (o fundador tem background em Rust; o nome combina as imagens de Ruv + flow). O núcleo WASM escrito em Rust executa o motor de estratégia, embeddings vetoriais e o sistema de provas, garantindo alto desempenho. A versão estável mais recente, [email protected], já é um produto completo de nível corporativo:

• 300+ ferramentas MCP injetadas diretamente no Claude Code
• 60+ tipos de agentes profissionais (coder, tester, architect, security-architect……)
• Memória de autoaprendizado: AgentDB + índice vetorial HNSW; busca é 150× a 12.500× mais rápida que a abordagem “força bruta”
• Colaboração federada entre máquinas: Agent Federation, comunicação segura de confiança zero baseada em mTLS + ed25519
• Capacidade de autoevolução: módulo neural de aprendizagem SONA, extraindo padrões de trajetórias históricas e otimizando continuamente
• 32 plugins que cobrem segurança, rastreamento de custos, automação de navegador, integração com GitHub etc.

A filosofia de design é bem interessante — depois de instalar, você não precisa aprender 300 ferramentas MCP: a camada de roteamento de Hooks distribui automaticamente as tarefas para o agente mais adequado. Você continua a escrever código; o Ruflo coordena tudo nos bastidores.

Dificuldade / Duração / O que você ganha

• Dificuldade: ★★☆☆☆ (leva cerca de 5 minutos para subir e rodar)
• Duração: cerca de 20 minutos
• O que você ganha: dominar a topologia do swarm e o gerenciamento do ciclo de vida, entender o princípio das memórias vetoriais HNSW e aprender a fazer agentes se comunicarem via SendMessage

Perfil do público-alvo

• Desenvolvedores com 1 a 5 anos de experiência
• Querem transformar IA de um “ferramenta de conversa” em uma “equipe que faz o trabalho”
• Desenvolvedores individuais ou pequenas equipes que já usam (ou planejam usar) o Claude Code para desenvolver

Dependências e ambiente essenciais

Estrutura completa da árvore do projeto

ruflo/
├── bin/
│   ├── cli.js              # Entrada da CLI (comando ruflo)
│   └── mcp-server.js       # Serviço MCP
│
├── v3/@claude-flow/        # Pacote de módulos centrais
│   ├── cli/                # 26 comandos de nível superior (140+ subcomandos)
│   ├── memory/             # AgentDB + busca vetorial HNSW
│   ├── swarm/              # Coordenador unificado (mesh hierárquico de 15 agentes)
│   ├── security/           # Correção de CVEs, validação de entrada, segurança de caminho
│   ├── neural/             # Módulo de autoaprendizado SONA
│   ├── hooks/              # 17 Hooks + 12 Workers em segundo plano
│   ├── guidance/           # Plano de governança (compile/enforce/prove/evolve)
│   └── shared/             # Tipos, eventos e interfaces centrais
│
├── plugins/                # 32 plugins oficiais
│   ├── ruflo-core/         # Básico (servidor, health check, descoberta de plugins)
│   ├── ruflo-swarm/        # Coordenação de equipes multiagente
│   ├── ruflo-federation/   # Colaboração segura entre máquinas
│   ├── ruflo-agentdb/      # Memória de banco vetorial
│   ├── ruflo-intelligence/ # Padrões neurais de autoaprendizado
│   └── ...                 # Outros 27 plugins
│
├── .claude/                # Configuração do Claude Code (servidor MCP, settings.json)
├── .agents/                # Definições de habilidades dos agentes ($skill-name)
└── mcp/                    # Definições de ferramentas MCP (agent-tools.ts, memory-tools.ts etc.)

Prática passo a passo

Etapa 1: instalação com um clique

Um único comando para inicializar, com assistente de configuração guiado:

npx ruflo@latest init --wizard

Esse comando faz, em sequência:

1. Gera CLAUDE.md no diretório atual e grava as regras de roteamento dos Hooks
2. Registra o servidor MCP na configuração do Claude Code
3. Em .claude-flow/, grava a configuração padrão e os arquivos-semente de memória

Se for sua primeira instalação, escolha a opção “full” no arquivo de configuração para instalar todos os módulos opcionais.

---

Etapa 2: registrar o serviço MCP

Se a etapa anterior não registrou o MCP automaticamente, faça manualmente:

claude mcp add ruflo -- npx -y @claude-flow/cli@latest mcp start

Verifique se o registro foi concluído:

claude mcp list
# Espera-se ver uma saída semelhante a:
# Name    Command                          Args  Status
# ruflo   npx -y @claude-flow/cli@latest  mcp  enabled

---

Etapa 3: inicializar o primeiro Swarm (hierarchical + 5 agentes)

npx ruflo swarm init --topology hierarchical --max-agents 8
npx ruflo agent spawn --type architect --name arch-1
npx ruflo agent spawn --type coder --name coder-1
npx ruflo agent spawn --type coder --name coder-2
npx ruflo agent spawn --type tester --name tester-1
npx ruflo agent spawn --type reviewer --name reviewer-1

---

Etapa 4: fazer os agentes conversarem via SendMessage

Este é o design mais central do Ruflo — agentes nomeados comunicam-se em tempo real via SendMessage, sem precisar de polling nem de um pool compartilhado de memória:

// No Task tool do Claude Code:
Task({
  prompt: "Desenhar uma proposta de REST API. Ao finalizar, envie SendMessage para 'coder-1' com a proposta.",
  subagent_type: "system-architect",
  name: "arch-1",
  run_in_background: true
})

Task({
  prompt: "Aguardar a proposta enviada por arch-1. Depois de implementar, enviar SendMessage para 'tester-1' reportando o caminho do código.",
  subagent_type: "coder",
  name: "coder-1",
  run_in_background: true
})

Task({
  prompt: "Aguardar o código enviado pelo coder-1. Escrever testes de integração. Ao finalizar, enviar SendMessage para 'reviewer-1' reportando o resultado.",
  subagent_type: "tester",
  name: "tester-1",
  run_in_background: true
})

// Iniciar o pipeline — enviar mensagem para o primeiro agente
SendMessage({
  to: "arch-1",
  summary: "Iniciar desenho da API",
  message: "Desenhar um conjunto de CRUD REST API de gestão de usuários, com operações de criar, excluir, atualizar e consultar. Depois de desenhar, enviar para coder-1."
})

Fluxo do pipeline: arch-1 → coder-1 → tester-1 → reviewer-1. Cada agente sabe exatamente para quem encaminhar a próxima etapa.

---

Etapa 5: gravar a primeira memória (AgentDB + HNSW)

npx ruflo memory store \
  --key "pattern-auth-service" \
  --value "Autenticação JWT: Bearer Token; usar express-jwt como middleware; token de refresh no Redis com expiração de 6 horas" \
  --namespace patterns

O conteúdo gravado gera automaticamente embeddings vetoriais e é armazenado no AgentDB para buscas semânticas posteriores.

---

Etapa 6: validar a memória com busca semântica

npx ruflo memory search --query "authentication patterns" --namespace patterns

A saída exibirá itens correspondentes e uma pontuação de similaridade (0-1; quanto maior, mais relevante). Pontuação > 0.7 indica uma correspondência forte, pronta para uso.

---

Etapa 7: iniciar o Daemon em segundo plano + executar diagnóstico de saúde

# Iniciar o daemon em segundo plano (12 Workers automáticos começam a rodar)
npx ruflo daemon start

# Diagnóstico com um clique (verifica versão do Node, API Key, conexão MCP e espaço em disco)
npx ruflo doctor --fix

doctor --fix repara automaticamente os problemas que ele consegue corrigir (por exemplo, dependências ausentes) e imprime um relatório completo de saúde no terminal.

---

Etapa 8: instalar plugins (conforme necessidade)

Instalar plugins é bem simples: escolha as funcionalidades de que você precisa:

# Adicionar o marketplace de plugins
/plugin marketplace add ruvnet/ruflo

# Instalar o plugin de colaboração federada (comunicação de agentes entre máquinas)
/plugin install ruflo-federation@ruflo

# Instalar plugin de autoaprendizado (SONA)
/plugin install ruflo-intelligence@ruflo

# Instalar plugin de auditoria de segurança
/plugin install ruflo-security-audit@ruflo

# Instalar plugin de rastreamento de custos
/plugin install ruflo-cost-tracker@ruflo

Ou via CLI:

npx ruflo plugins install ruflo-federation
npx ruflo plugins list  # Ver todos os plugins disponíveis

---

Etapa 9: avançado — chamar a capacidade de autoevolução (SONA)

# Pedir para o SONA extrair padrões a partir dos casos de sucesso mais recentes e treinar
npx ruflo hooks post-task --task-id "abc-123" --success true --train-neural true

# Ver os padrões aprendidos no momento
npx ruflo neural patterns

# Fazer a camada de roteamento usar roteamento inteligente (89% de acurácia)
npx ruflo hooks route --task "Escrever um middleware de API"

O SONA roda em 4 pipelines no background: RETRIEVE (HNSW) → JUDGE (julgamento de sucesso/fracasso) → DISTILL (destilação LoRA) → CONSOLIDATE (EWC++ para prevenir esquecimento catastrófico).

---

Solução de problemas comuns

1. Falha na conexão MCP: em claude mcp list, o ruflo aparece como disabled

Geralmente é problema de versão do Node ou porta em uso:

# Verificar a versão do Node
node -v  # deve ser ≥20.0.0

# Reiniciar manualmente o serviço MCP
claude mcp remove ruflo
claude mcp add ruflo -- npx -y @claude-flow/cli@latest mcp start

# Confirmar a porta em uso
lsof -i :3000  # macOS
netstat -tlnp | grep 3000  # Linux

---

2. A API Key não está configurada; erro: ANTHROPIC_API_KEY is not set

O Ruflo precisa de pelo menos uma chave de API de provedor de LLM:

# Configurar temporariamente (válido apenas na sessão atual)
export ANTHROPIC_API_KEY=sk-ant-xxxx

# Salvar permanentemente em ~/.bashrc ou ~/.zshrc
echo 'export ANTHROPIC_API_KEY=sk-ant-xxxx' >> ~/.zshrc

# Ou via arquivo de configuração (init --wizard vai te orientar a escrever .env)
# Suporte para múltiplos providers: Claude / GPT / Gemini / Ollama
npx ruflo providers add anthropic --key sk-ant-xxxx
npx ruflo providers test anthropic  # testar conexão

---

3. Versão do Node não atende: ruflo: requires Node.js >=20.0.0

# Método 1: usar nvm para atualizar
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install 20
nvm use 20

# Método 2: no Windows, usar nvm-windows
# Baixar o instalador: https://github.com/coreybutler/nvm-windows/releases
nvm install 20
nvm use 20

# Verificar
node -v  # deve mostrar v20.x.x

---

4. A busca por memória (memory search) não encontra resultados

Pode ser que o namespace esteja escrito errado, ou que a memória ainda não tenha sido salva:

# Ver todos os namespaces atuais
npx ruflo memory list --namespace

# Listar todas as chaves dentro de patterns
npx ruflo memory list --namespace patterns

# Buscar diretamente uma chave conhecida
npx ruflo memory retrieve --key "pattern-auth-service"

# Se a base estiver vazia, tente primeiro salvar uma entrada
npx ruflo memory store --key "test-entry" --value "hello world" --namespace patterns
npx ruflo memory search --query "test" --namespace patterns

---

5. Após iniciar o swarm, todos os agentes estão idle

Isso indica que a tarefa ainda não foi enviada. Verifique alguns pontos:

# Ver o status de todos os agentes
npx ruflo agent list

# Verificar se o swarm foi inicializado
npx ruflo swarm status

# Se você iniciou pelo Task tool do Claude Code, confirme que enviou a mensagem de início:
# SendMessage({ to: "arch-1", message: "Começar a trabalhar" })
# Sem SendMessage, o primeiro agente não inicia automaticamente

---

6. ruflo doctor reporta MongoDB not running

Ao iniciar via Docker Compose (ruflo/src/ruvocal/) é necessário MongoDB:

# Método 1: iniciar dependências completas com Docker
cd ruflo/src/ruvocal
docker compose up -d

# Método 2: usar o modo standalone embutido (não precisa de MongoDB)
npx ruflo start --mode standalone
# No standalone, o sql.js (WASM) substitui o MongoDB; funciona totalmente offline

---

Leitura adicional / Direções avançadas

1. Agent Federation — colaboração zero trust entre máquinas

Uma das funcionalidades mais legais. Faça agentes em máquinas diferentes cooperarem; PII é filtrada automaticamente antes de ser enviada:

npx ruflo federation init
npx ruflo federation join wss://other-team.example.com:8443
npx ruflo federation send --to team-b --type task-request --message "Analisar padrões de transações"

Detalhes de arquitetura: cada mensagem de saída passa por detecção de PII em 14 tipos → políticas em 4 níveis (BLOCK / REDACT / HASH / PASS) → validação de identidade do destinatário por mTLS + assinatura ed25519. Comportamentos maliciosos disparam automaticamente uma redução do nível de confiança, sem necessidade de intervenção manual.

2. Princípio de busca vetorial com RuVector HNSW

Não é uma simples correspondência por palavras-chave: o texto é codificado em vetores de 384 dimensões. No espaço vetorial, o HNSW (Hierarchical Navigable Small World) encontra os vizinhos mais próximos. Cada memory store gera embeddings automaticamente; cada memory search ordena os resultados usando similaridade cosseno.

3. Consulta rápida do ecossistema de 32 plugins

4. Experiência online (sem instalar)

• UI de chat com múltiplos modelos: https://flo.ruv.io/ — suporta Qwen 3.6 Max / Claude Sonnet / Gemini 2.5 Pro e chamadas paralelas de ferramentas MCP
• UI de planejamento de objetivos: https://goal.ruv.io/ — transforma o que você descreveu (“fazer a reconstrução do Auth rodar e escrever testes”) em um caminho GOAP A*
• Painel de Live Agent: https://goal.ruv.io/agents — visualizar em tempo real o status de cada agente, namespaces de memória e orçamento de tokens

5. Índice de documentação oficial

6. Comunidade Discord

Está com algum problema ou quer compartilhar as Skills que você fez? A RuvNet mantém uma comunidade ativa no Discord do Agentics Foundation:

https://discord.com/invite/dfxmpwkG2D

Lá há muitas Skills criadas pelos usuários com $skill-name, que você pode usar diretamente.