Introducción a Ruflo: un motor de orquestación multiagente que se autoevoluciona

Descripción del proyecto

Ruflo es una capa de orquestación multiagente pensada para Claude Code. Lo que hace, en una frase, es: convertir a Claude Code desde un «asistente de preguntas y respuestas» en un equipo de IA que colabora, recuerda y se autoevoluciona.

Ruflo se llamó inicialmente Claude Flow y fue desarrollado por RuvNet (el fundador tiene formación en Rust; el nombre combina las imágenes de Ruv + flow). El núcleo WASM escrito en Rust gestiona el motor de políticas, los embeddings vectoriales y el sistema de pruebas para garantizar alto rendimiento. La versión estable más reciente [email protected] ya es un producto completo de nivel empresarial:

• 300+ herramientas MCP inyectadas directamente en Claude Code
• 60+ tipos de roles de Agent (coder, tester, architect, security-architect……)
• Memoria de autoaprendizaje: AgentDB + índice vectorial HNSW; la búsqueda es 150x a 12.500x más rápida que el método de fuerza bruta
• Colaboración federada entre máquinas: Agent Federation con comunicación de confianza cero basada en mTLS + ed25519
• Capacidad de autoevolución: módulo neuronal SONA, que extrae patrones de trayectorias históricas y optimiza de forma continua
• 32 plugins que cubren seguridad, seguimiento de costes, automatización del navegador e integración con GitHub, entre otros

Su filosofía de diseño es muy interesante: una vez instalado, no necesitas aprender 300 herramientas MCP. La capa de rutas de Hooks envía automáticamente la tarea al Agent adecuado. Tú sigues escribiendo código y Ruflo coordina todo en segundo plano.

Dificultad / Duración / Beneficios

• Dificultad: ★★☆☆☆ (se pone en marcha en 5 minutos con la instalación)
• Duración: aprox. 20 minutos
• Beneficios: dominar la topología de swarm y la gestión del ciclo de vida; entender cómo funciona la memoria vectorial HNSW; aprender a hacer que los Agents se comuniquen entre sí mediante SendMessage

Perfil de lectores objetivo

• Desarrolladores con 1 a 5 años de experiencia
• Quieren transformar la IA de un «herramienta de chat» en un «equipo que se pone a trabajar»
• Desarrolladores individuales o equipos pequeños que ya usan (o planean usar) Claude Code para el desarrollo

Dependencias principales y entorno

Estructura completa del proyecto

ruflo/
├── bin/
│   ├── cli.js              # Entrada CLI (comando ruflo)
│   └── mcp-server.js       # Servidor de MCP
│
├── v3/@claude-flow/        # Paquete de módulo núcleo
│   ├── cli/                # 26 comandos de nivel superior (140+ subcomandos)
│   ├── memory/             # AgentDB + búsqueda vectorial HNSW
│   ├── swarm/              # Coordinador unificado (malla jerárquica de 15 agents)
│   ├── security/           # Reparación de CVE, validación de entradas, seguridad de rutas
│   ├── neural/             # Módulo autoaprendiente SONA
│   ├── hooks/              # 17 Hooks + 12 workers en segundo plano
│   ├── guidance/           # Plano de control de gobernanza (compile/enforce/prove/evolve)
│   └── shared/             # Tipos, eventos e interfaces núcleo
│
├── plugins/                # 32 plugins oficiales
│   ├── ruflo-core/         # Base (servidor, health check, descubrimiento de plugins)
│   ├── ruflo-swarm/        # Coordinación de equipos multiagente
│   ├── ruflo-federation/   # Colaboración segura entre máquinas
│   ├── ruflo-agentdb/      # Memoria en base de datos vectorial
│   ├── ruflo-intelligence/ # Patrones neuronales de autoaprendizaje
│   └── ...                 # Los 27 plugins restantes
│
├── .claude/                # Configuración de Claude Code (servidor MCP, settings.json)
├── .agents/                # Definición de habilidades del Agent ($skill-name)
└── mcp/                    # Definiciones de herramientas MCP (agent-tools.ts, memory-tools.ts, etc.)

Práctica paso a paso

Paso 1: instalación con un solo comando

Con un único comando se realiza la inicialización, con un asistente de configuración guiado:

npx ruflo@latest init --wizard

Este comando hace, en orden:

1. Genera CLAUDE.md en el directorio actual e introduce reglas de enrutado para Hooks
2. Registra el servidor MCP en la configuración de Claude Code
3. En .claude-flow/ escribe configuración predeterminada y un archivo semilla para la memoria

Si es tu primera instalación, elige la opción de instalación «full» para el archivo de configuración y así instalar todos los módulos opcionales.

---

Paso 2: registrar el servicio MCP

Si el paso anterior no registra MCP automáticamente, añádelo manualmente:

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

Verifica que se registró correctamente:

claude mcp list
# Se espera ver una salida similar:
# Name    Command                          Args  Status
# ruflo   npx -y @claude-flow/cli@latest  mcp  enabled

---

Paso 3: inicializar el primer Swarm (hierarchical + 5 Agents)

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

---

Paso 4: hacer que los Agents se comuniquen mediante SendMessage

Este es el diseño más esencial de Ruflo: la comunicación en tiempo real entre Agents nombrados mediante SendMessage; no necesitas hacer polling ni compartir un pool de memoria:

// En la herramienta Task de Claude Code:
Task({
  prompt: "Diseñar una propuesta de REST API. Cuando esté lista, envía SendMessage a 'coder-1' y pásale la propuesta.",
  subagent_type: "system-architect",
  name: "arch-1",
  run_in_background: true
})

Task({
  prompt: "Esperar el diseño enviado por arch-1. Al implementarlo, enviar SendMessage a 'tester-1' para reportar la ruta del código.",
  subagent_type: "coder",
  name: "coder-1",
  run_in_background: true
})

Task({
  prompt: "Esperar el código enviado por coder-1. Escribir pruebas de integración. Al finalizar, enviar SendMessage a 'reviewer-1' para reportar el resultado.",
  subagent_type: "tester",
  name: "tester-1",
  run_in_background: true
})

// Iniciar el pipeline: enviar mensaje al primer Agent
SendMessage({
  to: "arch-1",
  summary: "Empezar el diseño de la API",
  message: "Diseñar un conjunto de CRUD REST API para gestión de usuarios, incluyendo creación, borrado, actualización y consulta. Cuando esté listo, envíalo a coder-1."
})

Dirección del flujo: arch-1 → coder-1 → tester-1 → reviewer-1; cada Agent sabe a quién debe enviar el siguiente paso.

---

Paso 5: almacenar el primer recuerdo (AgentDB + HNSW)

npx ruflo memory store \
  --key "pattern-auth-service" \
  --value "Autenticación JWT: Bearer Token; express-jwt como middleware; refresh token guardado en Redis; caduca en 6 horas" \
  --namespace patterns

El contenido almacenado generará automáticamente embeddings vectoriales, y se guardará en AgentDB para búsquedas semánticas posteriores.

---

Paso 6: verificar la memoria con búsqueda semántica

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

La salida mostrará las entradas que coinciden y su puntuación de similitud (0-1, cuanto más alta, más relevante). Una puntuación > 0.7 indica una coincidencia muy fuerte y se puede usar directamente.

---

Paso 7: iniciar el Daemon en segundo plano + ejecutar diagnósticos de salud

# Iniciar el proceso demonio en segundo plano (12 workers automáticos comienzan a ejecutarse)
npx ruflo daemon start

# Diagnóstico de un clic (verificar versión de Node, API Key, conexión a MCP, espacio en disco)
npx ruflo doctor --fix

doctor --fix reparará automáticamente los problemas que pueda corregir (por ejemplo, dependencias faltantes) y mostrará un informe completo de salud en la terminal.

---

Paso 8: instalar plugins (según necesidad)

Instalar plugins es muy fácil: elige la funcionalidad que necesitas.

# Añadir el marketplace de plugins
/plugin marketplace add ruvnet/ruflo

# Instalar el plugin de colaboración federada (comunicación de Agents entre máquinas)
/plugin install ruflo-federation@ruflo

# Instalar el plugin de autoaprendizaje (patrones neuronales SONA)
/plugin install ruflo-intelligence@ruflo

# Instalar el plugin de auditoría de seguridad
/plugin install ruflo-security-audit@ruflo

# Instalar el plugin de seguimiento de costes
/plugin install ruflo-cost-tracker@ruflo

O mediante CLI:

npx ruflo plugins install ruflo-federation
npx ruflo plugins list  # Ver todos los plugins disponibles

---

Paso 9: avanzado — llamar a la capacidad de autoevolución (SONA)

# Hacer que SONA extraiga patrones a partir de casos de éxito recientes y entrene
npx ruflo hooks post-task --task-id "abc-123" --success true --train-neural true

# Ver los patrones que se están aprendiendo
npx ruflo neural patterns

# Hacer que la capa de enrutado use enrutado inteligente (89% de precisión)
npx ruflo hooks route --task "Escribir un middleware de API"

SONA ejecutará en segundo plano un pipeline de 4 pasos: RETRIEVE (HNSW) → JUDGE (juicio éxito/fracaso) → DISTILL (destilación LoRA) → CONSOLIDATE (EWC++ para prevenir el olvido catastrófico).

---

Solución de problemas frecuentes

1. Fallo en la conexión de MCP: en claude mcp list, ruflo aparece como disabled

Normalmente se debe a la versión de Node o a que el puerto está ocupado:

# Comprobar versión de Node
node -v  # debe ser ≥20.0.0

# Reiniciar manualmente el servicio MCP
claude mcp remove ruflo
claude mcp add ruflo -- npx -y @claude-flow/cli@latest mcp start

# Confirmar uso del puerto
lsof -i :3000  # macOS
netstat -tlnp | grep 3000  # Linux

---

2. La API Key no está configurada: error ANTHROPIC_API_KEY is not set

Ruflo necesita al menos una API Key de un proveedor de LLM:

# Configuración temporal (válida para la sesión actual)
export ANTHROPIC_API_KEY=sk-ant-xxxx

# Guardar permanentemente en ~/.bashrc o ~/.zshrc
echo 'export ANTHROPIC_API_KEY=sk-ant-xxxx' >> ~/.zshrc

# O bien mediante archivo de configuración (init --wizard te guía para escribir en .env)
# Admite múltiples providers: Claude / GPT / Gemini / Ollama
npx ruflo providers add anthropic --key sk-ant-xxxx
npx ruflo providers test anthropic  # Probar la conexión

---

3. La versión de Node no cumple: ruflo: requires Node.js >=20.0.0

# Opción uno: actualizar con nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install 20
nvm use 20

# Opción dos: en Windows con nvm-windows
# Descargar: https://github.com/coreybutler/nvm-windows/releases
nvm install 20
nvm use 20

# Verificar
node -v  # debería mostrar v20.x.x

---

4. memory search no encuentra resultados

Puede ser que el namespace esté escrito mal o que la memoria aún no se haya guardado:

# Ver todos los namespaces actuales
npx ruflo memory list --namespace

# Listar todas las claves dentro de patterns
npx ruflo memory list --namespace patterns

# Recuperar una clave conocida directamente
npx ruflo memory retrieve --key "pattern-auth-service"

# Si es un almacén vacío, prueba guardando primero una entrada
npx ruflo memory store --key "test-entry" --value "hello world" --namespace patterns
npx ruflo memory search --query "test" --namespace patterns

---

5. Tras iniciar el swarm, todos los Agents están en idle

Esto indica que aún no se han enviado tareas. Revisa estos puntos:

# Ver el estado de todos los Agents
npx ruflo agent list

# Comprobar si el swarm se inicializó
npx ruflo swarm status

# Si lo inicias con la herramienta Task de Claude Code, confirma que enviaste el mensaje de inicio:
# SendMessage({ to: "arch-1", message: "Empezar a trabajar" })
# Sin SendMessage, el primer Agent no se iniciará automáticamente

---

6. ruflo doctor informa MongoDB not running

Al arrancar con Docker Compose (ruflo/src/ruvocal/) se necesita MongoDB:

# Opción uno: usar Docker para levantar todas las dependencias
cd ruflo/src/ruvocal
docker compose up -d

# Opción dos: usar el modo de una sola máquina integrado en ruflo (sin MongoDB)
npx ruflo start --mode standalone
# El modo standalone usa sql.js (WASM) en lugar de MongoDB y es 100% utilizable sin conexión

---

Lectura adicional / Direcciones de mejora

1. Agent Federation — colaboración de confianza cero entre máquinas

Una de las funciones más impresionantes. Permite que Agents en distintas máquinas colaboren; el PII se filtra automáticamente antes de enviarse:

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 "Analizar patrones de transacciones"

Detalles de arquitectura: cada mensaje saliente pasa por un detector de PII de 14 tipos → políticas en cuatro niveles (BLOCK / REDACT / HASH / PASS) → verificación de identidad mediante firmas mTLS + ed25519. Las conductas maliciosas activan automáticamente la degradación de la confianza sin intervención humana.

2. Principio de búsqueda vectorial RuVector HNSW

No es un simple emparejamiento por palabras clave: se codifica el texto en vectores de 384 dimensiones y, dentro del espacio vectorial, se usa el algoritmo HNSW (Hierarchical Navigable Small World) para encontrar vecinos cercanos. Cada memory store genera embeddings automáticamente, y cada memory search ordena los resultados mediante similitud coseno.

3. Guía rápida del ecosistema de 32 plugins

4. Experiencia en línea (sin instalar)

• Interfaz de chat con múltiples modelos: https://flo.ruv.io/ — admite Qwen 3.6 Max / Claude Sonnet / Gemini 2.5 Pro y llama en paralelo a herramientas MCP en línea
• Interfaz de planificación de objetivos: https://goal.ruv.io/ — convierte lo que dices, por ejemplo «hacer que el Auth se reestructure y escribir pruebas», en una ruta GOAP con A*
• Panel en vivo de Live Agent: https://goal.ruv.io/agents — ver en tiempo real el estado de cada Agent, los namespaces de memoria y el presupuesto de tokens

5. Índice de documentación oficial

6. Comunidad de Discord

¿Te encuentras con problemas o quieres compartir las Skills que hiciste? En Agentics Foundation Discord, RuvNet mantiene una comunidad activa:

https://discord.com/invite/dfxmpwkG2D

Hay muchas Skills hechas por usuarios con el formato $skill-name, listas para reutilizar.