swarma – bucle de experimentación de crecimiento para equipos de agentes

Cuándo usar esta habilidad

Usa swarma cuando el usuario quiera:

Ejecutar experimentos de crecimiento (hooks, páginas de aterrizaje, outreach, precios, activación, retención)
Construir equipos de agentes que aprendan y mejoren mediante pruebas A/B, no solo ejecuten una vez
Obtener un manual de juego validado sobre lo que realmente funciona para su audiencia/producto específico
Probar ideas a escala (50+ experimentos/semana en lugar de 2-5)
Reemplazar "lo intentamos, no funcionó" por datos de experimentos registrados, analizados y buscables

Frases desencadenantes: "prueba qué funciona", "optimiza mi embudo", "encuentra los mejores hooks", "ejecuta experimentos", "prueba A/B", "qué está funcionando", "construye un manual", "experimentos de crecimiento", "mejora la conversión"

NO usar cuando: el usuario quiere automatización de flujos de trabajo (usa n8n/Make), memoria de conversación (usa honcho) o pipelines de agentes de un solo uso (usa CrewAI/AutoGen). swarma es específicamente para bucles de experimentación que mejoran con el tiempo.

Referencia rápida

Comandos de un vistazo

Comando	Qué hace	Cuándo usarlo
`swarma init`	Crear instancia + equipo inicial	Configuración inicial
`swarma cycle <equipo>`	Ejecutar un ciclo de experimento	Pruebas, ejecuciones manuales
`swarma cycle <equipo> --topic "..."`	Ejecutar ciclo con un tema específico	Experimentos ad-hoc
`swarma team create <nombre> --from-goal "..."`	Generar equipo a partir de un objetivo	Iniciar una nueva área de experimentación
`swarma team show <nombre>`	Inspeccionar la configuración de un equipo	Revisar lo generado
`swarma team list`	Mostrar todos los equipos	Visión general
`swarma status`	Costos, ejecuciones recientes, experimentos	Comprobación de estado
`swarma metric log <equipo> <agente> <valor>`	Registrar métrica externa	Alimentar datos reales del mundo
`swarma metric import <equipo> <csv>`	Importar métricas por lotes	Ingesta masiva de datos
`swarma metric show <equipo>`	Ver métricas registradas	Revisar rendimiento
`swarma serve --port 8282`	Iniciar API REST	Integraciones externas
`swarma serve --mcp`	Iniciar servidor MCP	Integración con Claude Code / Hermes
`swarma run`	Iniciar motor programado	Operación continua
`swarma expert list`	Explorar lentes de razonamiento	Explorar marcos de expertos

Decisión: ¿Qué plantilla de escuadrón?

El usuario quiere mejorar...	Usa este escuadrón	Etapa AARRR
Líneas de apertura / hooks	`hook-lab`	Adquisición
Texto de página de aterrizaje	`landing-lab`	Adquisición
Ranking SEO	`seo-engine`	Adquisición
Tasas de respuesta en outreach en frío	`cold-outbound`	Adquisición
Contenido multiplataforma	`channel-mix`	Adquisición
Incorporación de registro a valor	`activation-flow`	Activación
Precios y empaquetado	`pricing-lab`	Ingresos
Abandono y retención	`retention-squad`	Retención
Bucles virales y referidos	`referral-engine`	Referido
Posicionamiento de mercado	`competitive-intel`	--
Pipeline de video corto	`faceless-factory`	Adquisición
Pruebas de creatividades publicitarias	`ad-creative-lab`	Adquisición
Simulación de contenido UGC	`ugc-factory`	Adquisición
SEO programático	`programmatic-seo`	Adquisición
Crecimiento de boletines	`newsletter-engine`	Retención
Bucles de pago + orgánico	`acquisition-squad`	Adquisición
Crecimiento impulsado por la comunidad	`community-engine`	Retención
Optimización de comercio con IA	`agentic-storefront`	Ingresos

Decisión: ¿Generar vs Plantilla?

Situación	Enfoque
El usuario tiene un objetivo específico y bien definido	`swarma team create --from-goal` (deja que la IA diseñe el equipo)
El objetivo coincide con una plantilla de escuadrón existente	Copiar la plantilla y personalizar
El usuario quiere experimentar de forma amplia	Empezar con `hook-lab` (el más general)
El usuario no sabe por dónde empezar	Preguntar por su cuello de botella en el embudo, luego elegir

El bucle GROWS (Concepto central)

Cada ciclo de experimento sigue cinco pasos:

  Generar        Ejecutar       Observar      Evaluar       Apilar
 hipótesis --> experimento --> señal --> veredicto --> manual
     ^                                                  |
     └──────────────────────────────────────────────────┘

Paso	Qué sucede	Dónde en el código
G -- Generar	El agente lee `strategy.md`, propone una hipótesis	`core/cycle.py`
R -- Ejecutar	El agente ejecuta con la hipótesis activa, produce salida	`flow/executor.py`
O -- Observar	Un LLM económico separado puntúa la salida (1-10, decimales forzados)	`core/agent.py`
E -- Evaluar	Tras 5 ciclos, compara el promedio con la línea base. >20% = mantener/descartar	`core/experiment.py`
A -- Apilar	Los patrones validados se escriben en `strategy.md` + manual	`core/agent.py`

Números clave:

Umbral de veredicto: mejora del 20% para mantener, empeoramiento del 20% para descartar
min_sample_size por defecto: 5 ciclos antes del veredicto
Puntuación: escala 1-10 con decimales forzados (7.3, no 7)

Guía de configuración

Plataforma: Claude Code / Claude Desktop

pip install swarma
swarma init

Añadir a .mcp.json:

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

Importante: OPENROUTER_API_KEY debe estar en el bloque env de MCP. El archivo .env de la instancia no se hereda en los subprocesos.

Plataforma: Hermes (vía terminal)

Hermes tiene acceso al terminal; puede ejecutar comandos CLI de swarma directamente. No se requiere MCP.

pip install swarma
swarma init

Luego dile a Hermes: "ejecuta swarma cycle hook-lab --topic 'Los agentes de IA están sobrevalorados'"

Hermes lee la salida del terminal y actúa según los resultados. Para acceso estructurado, añade 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

Configúralo como herramienta MCP o usa acceso al terminal según tu configuración de OpenClaw.

Plataforma: CLI (independiente)

pip install swarma
swarma init                                        # crea instancia + equipo inicial
swarma cycle starter --topic "¿por qué fracasan las startups?"   # ejecuta un ciclo
swarma status                                      # comprueba costos, ejecuciones, experimentos

Desde el código fuente

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

Configuración del entorno

Después de swarma init, añade tu clave API:

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

Obtén una clave en openrouter.ai/keys.

Opcional (para conocimiento entre equipos):

# Solo necesario al ejecutar 3+ equipos
echo "QMD_ENDPOINT=http://localhost:8181/mcp" >> ~/.swarma/instances/default/.env

Flujo de incorporación

Cuando un usuario quiera configurar swarma, sigue esta secuencia. El generador de equipos es la ruta más rápida: no hagas que los usuarios configuren agentes manualmente.

Paso 1: Entender el objetivo

Pregunta:

"¿Qué quieres mejorar?" (conversión, engagement, tasa de respuesta de outreach, rankings SEO, etc.)
"¿Quién es tu audiencia?" (usuarios B2B SaaS, comunidad crypto, compradores empresariales, etc.)
"¿Cómo se ve el éxito?" (más registros, mayor CTR, mejores tasas de respuesta, etc.)

Paso 2: Instalar

pip install swarma
swarma init --yes

Paso 3: Generar el equipo

Este es el paso clave. Usa el generador de equipos en lugar de elegir plantillas.

swarma team create growth-lab \
  --from-goal "optimizar la conversión de la página de aterrizaje para nuestro SaaS B2B" \
  --context "empresa de herramientas para desarrolladores, 500 usuarios gratuitos, 2% de conversión a pago" \
  --budget 30

El generador:

Diseña el equipo (2-5 agentes con roles específicos)
Elige modelos que se ajusten a cada rol
Escribe instrucciones para los agentes y patrones de experimento
Crea una primera hipótesis de experimento lista para ejecutar

Revisa lo que generó:

swarma team show growth-lab

Paso 4: Ejecutar el primer ciclo

swarma cycle growth-lab

Salida esperada:

Ejecutando ciclo: growth-lab
  flujo: researcher -> copywriter -> judge
  agentes: ['researcher', 'copywriter', 'judge']

                              Ciclo: growth-lab
  Agente       Modelo               Costo       Vista previa de salida
  researcher  sonar-pro          $0.000384  **Tema:** El 52% de los ejecutivos...
  copywriter  qwen3.5-plus-02-15 $0.000746  [A] Enviamos 4,382 correos en frío...
  judge       mistral-nemo       $0.000416  **Variaciones de hook:** A: "Hicieron...

  duración: 43.9s | costo total: $0.001546 | agentes: 3

Paso 5: Ejecutar más ciclos y revisar

swarma cycle growth-lab                    # ejecutar otro ciclo
swarma cycle growth-lab --topic "ángulo específico"  # con un tema
swarma status                              # comprobar progreso

Después de 5 ciclos, el motor de experimentos emite su primer veredicto. El archivo de estrategia evoluciona automáticamente.

Uso diario

Ejecutar experimentos

# Ciclo único
swarma cycle hook-lab

# Con un tema específico
swarma cycle hook-lab --topic "Los agentes de IA se están mercantilizando"

# Continuo (los equipos con programación cron se ejecutan automáticamente)
swarma run

# Continuo con servidor API
swarma run --port 8282

Alimentar métricas reales

La autoevaluación del LLM es un proxy inicial. Para producción, retroalimenta señales del mundo real:

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

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

# Añadir una nota
swarma metric log hook-lab copywriter 5.1 --metric ctr_pct --note "desde linkedin analytics"

# Importación masiva desde CSV
swarma metric import hook-lab metrics.csv

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

Formato CSV: agente,valor,nombre_métrica,nota

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

Usar plantillas de escuadrón

# Copiar una plantilla a tu instancia
cp -r "$(python -c "import swarma; print(swarma.__path__[0])")/examples/hook-lab" \
  ~/.swarma/instances/default/teams/hook-lab

# O si clonaste el repositorio
cp -r examples/hook-lab ~/.swarma/instances/default/teams/hook-lab

# Ejecutarla
swarma cycle hook-lab --topic "por qué fracasan la mayoría de las startups"

Comprobar el estado

swarma status

Muestra: todos los equipos, ejecuciones recientes, costos (hoy + este mes), planes pendientes, estadísticas de cola.

Referencia de herramientas MCP

Cuando está conectado vía MCP, estas 16 herramientas están disponibles:

Herramienta	Descripción	Parámetros
`swarma_health`	Verificar si swarma está funcionando	--
`swarma_list_teams`	Listar todos los equipos configurados	--
`swarma_get_team`	Obtener detalles del equipo (agentes, flujo, programación)	`team_id`
`swarma_list_agents`	Listar agentes en un equipo	`team_id`
`swarma_run_agent`	Ejecutar un solo agente con contexto opcional	`team_id`, `agent_id`, `context?`
`swarma_run_cycle`	Ejecutar un ciclo completo para un equipo	`team_id`, `topic?`
`swarma_status`	Estado de la instancia (costos, ejecuciones, experimentos)	--
`swarma_costs`	Desglose de costos (hoy, este mes)	--
`swarma_list_plans`	Mostrar planes de experimento pendientes	`team_id?`
`swarma_approve_plan`	Aprobar un plan de experimento pendiente	`plan_id`
`swarma_reject_plan`	Rechazar un plan pendiente	`plan_id`, `reason?`
`swarma_get_outputs`	Salidas recientes de los agentes	`team_id?`, `agent_id?`, `limit?`
`swarma_list_tools`	Listar herramientas de agente disponibles	--
`swarma_list_experts`	Explorar lentes de razonamiento de expertos	--
`swarma_get_expert`	Obtener detalles de un experto por ID	`expert_id`
`swarma_generate_team`	Generar un nuevo equipo a partir de un objetivo	`name`, `goal`, `context?`, `budget?`

Flujos de trabajo MCP comunes

"¿Qué ha estado pasando?"

swarma_status -- visión general
swarma_get_outputs -- salidas recientes de agentes
swarma_list_plans -- experimentos pendientes

"Ejecutar un experimento"

swarma_run_cycle con team_id y tema opcional
swarma_get_outputs para revisar resultados

"Iniciar una nueva área de experimentación"

swarma_generate_team con objetivo y contexto
swarma_get_team para revisar lo generado
swarma_run_cycle para ponerlo en marcha

"¿Qué está funcionando?"

swarma_get_outputs para resultados recientes
Leer el strategy.md del equipo para patrones validados

Referencia de configuración del equipo

Un equipo es una carpeta. No se requiere código.

teams/mi-escuadron/
├── team.yaml          # objetivo, flujo, programación, presupuesto
├── program.md         # contexto y restricciones del equipo
└── agents/
    ├── researcher.yaml
    ├── writer.yaml
    └── strategy.md    # conocimiento de crecimiento inicial (evoluciona automáticamente)

team.yaml

name: mi-escuadron
goal: encontrar lo que funciona.
flow: "researcher -> writer"        # secuencial
# flow: "researcher -> [writer, analyst]"  # paralelo
schedule: "0 8 * * 1-5"            # opcional: días laborables a las 8am
budget: 30                          # opcional: presupuesto mensual en $

agent.yaml

id: writer
name: Escritor
instructions: |
  convierte la investigación en una publicación. máximo 200 palabras.
  hook en la primera línea. voz de profesional.
model: qwen/qwen3.5-plus-02-15     # opcional: anular el enrutamiento predeterminado
metric:
  name: content_quality
  target: 8.0
experiment_config:
  min_sample_size: 5
  auto_propose: true

strategy.md (evoluciona automáticamente)

Comienza con conocimiento inicial y crece con cada experimento validado:

### Patrones validados

**La especificidad gana**
- Los hooks con números específicos superan a las afirmaciones vagas en 2-3x en guardados
- "El 47% de las startups" > "la mayoría de las startups"

### Antipatrones (Descartados)
- Aperturas inspiradoras genéricas: -23% vs línea base. Descartar.

### Patrones para probar
- [ ] Confesión en primera persona vs estudio de caso en tercera persona
- [ ] Hooks anclados en el tiempo ("En 2024...") vs hooks atemporales

DSL de flujo

# Secuencial: a se ejecuta, la salida pasa a b
flow: "researcher -> writer"

# Paralelo: a se ejecuta, luego b y c se ejecutan concurrentemente
flow: "researcher -> [writer, analyst]"

# Mixto:

Preguntar en tu IA favorita

Documentación