Que fait swarma — boucle d'expérimentation pour équipes d'agents ?

Quand utiliser cette compétence

Utilisez swarma lorsque l'utilisateur souhaite :

Mener des expériences de croissance (hooks, pages de vente, prospection, tarification, activation, rétention)
Construire des équipes d'agents qui apprennent et s'améliorent grâce à des tests A/B, et non pas simplement exécutent une tâche unique
Obtenir un manuel de jeu validé de ce qui fonctionne réellement pour leur audience/produit spécifique
Tester des idées à grande échelle (50+ expériences/semaine au lieu de 2-5)
Remplacer "on a essayé, ça n'a pas marché" par des données d'expériences enregistrées, analysées et recherchables

Phrases déclencheuses : "teste ce qui marche", "optimise mon entonnoir", "trouve les meilleurs hooks", "lance des expériences", "test A/B", "qu'est-ce qui marche", "construis un manuel", "expériences de croissance", "améliore la conversion"

Ne PAS utiliser quand : l'utilisateur souhaite de l'automatisation de workflows (utilisez n8n/Make), une mémoire de conversation (utilisez honcho), ou des pipelines d'agents à usage unique (utilisez CrewAI/AutoGen). swarma est spécifiquement conçu pour des boucles d'expérimentation qui s'améliorent avec le temps.

Référence rapide

Commandes en un coup d'œil

Commande	Action	Quand l'utiliser
`swarma init`	Créer une instance + équipe de démarrage	Première configuration
`swarma cycle <team>`	Exécuter un cycle d'expérience	Tests, exécutions manuelles
`swarma cycle <team> --topic "..."`	Exécuter un cycle avec un sujet spécifique	Expériences ad-hoc
`swarma team create <nom> --from-goal "..."`	Générer une équipe à partir d'un objectif	Démarrer un nouveau domaine d'expérimentation
`swarma team show <nom>`	Inspecter la configuration d'une équipe	Vérifier ce qui a été généré
`swarma team list`	Afficher toutes les équipes	Vue d'ensemble
`swarma status`	Coûts, exécutions récentes, expériences	Vérification d'état
`swarma metric log <team> <agent> <valeur>`	Enregistrer une métrique externe	Alimenter des données réelles
`swarma metric import <team> <csv>`	Importer des métriques en masse	Ingestion de données par lot
`swarma metric show <team>`	Afficher les métriques enregistrées	Examen des performances
`swarma serve --port 8282`	Démarrer l'API REST	Intégrations externes
`swarma serve --mcp`	Démarrer le serveur MCP	Intégration Claude Code / Hermes
`swarma run`	Démarrer le moteur programmé	Fonctionnement continu
`swarma expert list`	Parcourir les prismes de raisonnement	Explorer les frameworks experts

Décision : Quel modèle d'équipe ?

L'utilisateur souhaite améliorer...	Utilisez cette équipe	Étape AARRR
Lignes d'ouverture / hooks	`hook-lab`	Acquisition
Texte de page de vente	`landing-lab`	Acquisition
Classements SEO	`seo-engine`	Acquisition
Taux de réponse des emails de prospection	`cold-outbound`	Acquisition
Contenu multi-plateforme	`channel-mix`	Acquisition
Parcours d'onboarding inscription-à-valeur	`activation-flow`	Activation
Tarification et packaging	`pricing-lab`	Revenue
Churn et rétention	`retention-squad`	Retention
Boucles virales et parrainages	`referral-engine`	Referral
Positionnement sur le marché	`competitive-intel`	--
Pipeline vidéo courte	`faceless-factory`	Acquisition
Test de créations publicitaires	`ad-creative-lab`	Acquisition
Simulation de contenu UGC	`ugc-factory`	Acquisition
SEO programmatique	`programmatic-seo`	Acquisition
Croissance de newsletter	`newsletter-engine`	Retention
Boucles payantes + organiques	`acquisition-squad`	Acquisition
Croissance portée par la communauté	`community-engine`	Retention
Optimisation du commerce IA	`agentic-storefront`	Revenue

Décision : Générer vs Modèle ?

Situation	Approche
L'utilisateur a un objectif spécifique et bien défini	`swarma team create --from-goal` (laisser l'IA concevoir l'équipe)
L'objectif correspond à un modèle d'équipe existant	Copier le modèle, puis personnaliser
L'utilisateur souhaite expérimenter largement	Commencer avec `hook-lab` (le plus général)
L'utilisateur ne sait pas par où commencer	Demander quel est son goulot d'étranglement dans l'entonnoir, puis choisir

La boucle GROWS (concept central)

Chaque cycle d'expérience suit cinq étapes :

  Générer        Exécuter       Observer       Peser         Empiler
 hypothèse --> expérience --> signal --> verdict --> manuel
     ^                                                  |
     └──────────────────────────────────────────────────┘

Étape	Ce qui se passe	Où dans le code
G -- Générer	L'agent lit `strategy.md`, propose une hypothèse	`core/cycle.py`
R -- Exécuter	L'agent exécute avec l'hypothèse active, produit une sortie	`flow/executor.py`
O -- Observer	Un LLM économique séparé note la sortie (1-10, décimales forcées)	`core/agent.py`
P -- Peser	Après 5 cycles, compare la moyenne à la base de référence. >20% = conserver/rejeter	`core/experiment.py`
E -- Empiler	Les schémas validés sont écrits dans `strategy.md` + le manuel	`core/agent.py`

Chiffres clés :

Seuil de verdict : 20% d'amélioration pour conserver, 20% de baisse pour rejeter
min_sample_size par défaut : 5 cycles avant verdict
Notation : échelle 1-10 avec décimales forcées (7,3, pas 7)

Guide de configuration

Plateforme : Claude Code / Claude Desktop

pip install swarma
swarma init

Ajoutez à .mcp.json :

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

Important : OPENROUTER_API_KEY doit être dans le bloc env MCP. Le fichier .env de l'instance n'est pas hérité par les sous-processus.

Plateforme : Hermes (via terminal)

Hermes a accès au terminal — il peut exécuter directement les commandes CLI de swarma. Pas besoin de MCP.

pip install swarma
swarma init

Dites ensuite à Hermes : "exécute swarma cycle hook-lab --topic 'Les agents IA sont surfaits'"

Hermes lit la sortie du terminal et agit sur les résultats. Pour un accès structuré, ajoutez MCP :

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

Plateforme : OpenClaw

pip install swarma
swarma init

Configurez en tant qu'outil MCP ou utilisez l'accès terminal selon votre configuration OpenClaw.

Plateforme : CLI (autonome)

pip install swarma
swarma init                                        # crée une instance + équipe de démarrage
swarma cycle starter --topic "pourquoi les startups échouent"   # exécute un cycle
swarma status                                      # vérifie les coûts, exécutions, expériences

Depuis les sources

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

Configuration de l'environnement

Après swarma init, ajoutez votre clé API :

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

Obtenez une clé sur openrouter.ai/keys.

Optionnel (pour le partage de connaissances entre équipes) :

# Nécessaire uniquement lorsque 3 équipes ou plus sont en cours d'exécution
echo "QMD_ENDPOINT=http://localhost:8181/mcp" >> ~/.swarma/instances/default/.env

Parcours d'intégration

Lorsqu'un utilisateur souhaite configurer swarma, suivez cette séquence. Le générateur d'équipe est le chemin le plus rapide — ne forcez pas les utilisateurs à configurer les agents manuellement.

Étape 1 : Comprendre l'objectif

Demandez :

"Qu'est-ce que tu souhaites améliorer ?" (conversion, engagement, taux de réponse des emails, classements SEO, etc.)
"Qui est ton public ?" (utilisateurs B2B SaaS, communauté crypto, acheteurs enterprise, etc.)
"À quoi ressemble le succès ?" (plus d'inscriptions, CTR plus élevé, meilleurs taux de réponse, etc.)

Étape 2 : Installer

pip install swarma
swarma init --yes

Étape 3 : Générer l'équipe

C'est l'étape clé. Utilisez le générateur d'équipe plutôt que de choisir des modèles.

swarma team create growth-lab \
  --from-goal "optimiser la conversion de la page de vente pour notre SaaS B2B" \
  --context "entreprise d'outils pour développeurs, 500 utilisateurs gratuits, conversion de 2% vers le payant" \
  --budget 30

Le générateur :

Conçoit l'équipe (2 à 5 agents avec des rôles spécifiques)
Choisit les modèles qui correspondent à chaque rôle
Rédige les instructions des agents et les modèles d'expérience
Crée une première hypothèse d'expérience prête à être exécutée

Examinez ce qui a été généré :

swarma team show growth-lab

Étape 4 : Exécuter le premier cycle

swarma cycle growth-lab

Sortie attendue :

Exécution du cycle : growth-lab
  flux : researcher -> copywriter -> judge
  agents : ['researcher', 'copywriter', 'judge']

                              Cycle : growth-lab
  Agent      Modèle             Coût       Aperçu de la sortie
  researcher sonar-pro          $0.000384  **Sujet :** 52% des cadres...
  copywriter qwen3.5-plus-02-15 $0.000746  [A] Nous avons envoyé 4 382 emails...
  judge      mistral-nemo       $0.000416  **Variantes de hook :** A : "Avez...

  durée : 43,9 s | coût total : $0.001546 | agents : 3

Étape 5 : Exécuter plus de cycles et examiner

swarma cycle growth-lab                    # exécute un autre cycle
swarma cycle growth-lab --topic "angle spécifique"  # avec un sujet
swarma status                              # vérifie la progression

Après 5 cycles, le moteur d'expérience émet son premier verdict. Le fichier de stratégie évolue automatiquement.

Utilisation quotidienne

Exécution d'expériences

# Cycle unique
swarma cycle hook-lab

# Avec un sujet spécifique
swarma cycle hook-lab --topic "Les agents IA deviennent une commodité"

# Continu (les équipes avec des plannings cron s'exécutent automatiquement)
swarma run

# Continu avec serveur API
swarma run --port 8282

Alimentation de métriques réelles

L'auto-évaluation LLM est un proxy de départ. Pour la production, alimentez les signaux réels :

# Enregistrer une métrique unique
swarma metric log hook-lab copywriter 4.2 --metric ctr_pct

# Attacher à une expérience spécifique
swarma metric log hook-lab copywriter 127 --metric impressions --exp 3

# Ajouter une note
swarma metric log hook-lab copywriter 5.1 --metric ctr_pct --note "depuis linkedin analytics"

# Importer en masse depuis un CSV
swarma metric import hook-lab metrics.csv

# Afficher les métriques enregistrées
swarma metric show hook-lab

Format CSV : agent,valeur,nom_métrique,note

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

Utilisation des modèles d'équipe

# Copier un modèle vers votre instance
cp -r "$(python -c "import swarma; print(swarma.__path__[0])")/examples/hook-lab" \
  ~/.swarma/instances/default/teams/hook-lab

# Ou si vous avez cloné le dépôt
cp -r examples/hook-lab ~/.swarma/instances/default/teams/hook-lab

# L'exécuter
swarma cycle hook-lab --topic "pourquoi la plupart des startups échouent"

Vérification de l'état

swarma status

Affiche : toutes les équipes, exécutions récentes, coûts (aujourd'hui + ce mois), plans en attente, statistiques de file d'attente.

Référence des outils MCP

Lorsqu'il est connecté via MCP, ces 16 outils sont disponibles :

Outil	Description	Paramètres
`swarma_health`	Vérifier si swarma fonctionne	--
`swarma_list_teams`	Lister toutes les équipes configurées	--
`swarma_get_team`	Obtenir les détails d'une équipe (agents, flux, planning)	`team_id`
`swarma_list_agents`	Lister les agents d'une équipe	`team_id`
`swarma_run_agent`	Exécuter un agent unique avec contexte optionnel	`team_id`, `agent_id`, `context?`
`swarma_run_cycle`	Exécuter un cycle complet pour une équipe	`team_id`, `topic?`
`swarma_status`	État de l'instance (coûts, exécutions, expériences)	--
`swarma_costs`	Répartition des coûts (aujourd'hui, ce mois)	--
`swarma_list_plans`	Afficher les plans d'expérience en attente	`team_id?`
`swarma_approve_plan`	Approuver un plan d'expérience en attente	`plan_id`
`swarma_reject_plan`	Rejeter un plan en attente	`plan_id`, `reason?`
`swarma_get_outputs`	Sorties récentes des agents	`team_id?`, `agent_id?`, `limit?`
`swarma_list_tools`	Lister les outils disponibles des agents	--
`swarma_list_experts`	Parcourir les prismes de raisonnement experts	--
`swarma_get_expert`	Obtenir les détails d'un expert par ID	`expert_id`
`swarma_generate_team`	Générer une nouvelle équipe à partir d'un objectif	`name`, `goal`, `context?`, `budget?`

Workflows MCP courants

"Que s'est-il passé ?"

swarma_status — vue d'ensemble
swarma_get_outputs — sorties récentes des agents
swarma_list_plans — expériences en attente

"Lancer une expérience"

swarma_run_cycle avec team_id et sujet optionnel
swarma_get_outputs pour examiner les résultats

"Démarrer un nouveau domaine d'expérimentation"

swarma_generate_team avec objectif et contexte
swarma_get_team pour examiner ce qui a été généré
swarma_run_cycle pour démarrer

"Qu'est-ce qui marche ?"

swarma_get_outputs pour les résultats récents
Lire le fichier strategy.md de l'équipe pour les schémas validés

Référence de configuration d'équipe

Une équipe est un dossier. Aucun code requis.

teams/mon-equipe/
├── team.yaml          # objectif, flux, planning, budget
├── program.md         # contexte et contraintes de l'équipe
└── agents/
    ├── researcher.yaml
    ├── writer.yaml
    └── strategy.md    # connaissances de croissance pré-injectées (évoluent automatiquement)

team.yaml

name: mon-equipe
goal: trouver ce qui marche.
flow: "researcher -> writer"        # séquentiel
# flow: "researcher -> [writer, analyst]"  # parallèle
schedule: "0 8 * * 1-5"            # optionnel : jours de semaine à 8h
budget: 30                           # optionnel : budget mensuel en $

agent.yaml

id: writer
name: Rédacteur
instructions: |
  transforme la recherche en un post. max 200 mots.
  accroche dans la première ligne. ton de praticien.
model: qwen/qwen3.5-plus-02-15     # optionnel : remplace le routage par défaut
metric:
  name: content_quality
  target: 8.0
experiment_config:
  min_sample_size: 5
  auto_propose: true

strategy.md (évolue automatiquement)

Commence par des connaissances de base, grandit avec chaque expérience validée :

### Schémas validés

**La spécificité gagne**
- Les hooks avec des chiffres précis surpassent les affirmations vagues de 2 à 3 fois en termes de sauvegardes
- "47% des startups" > "la plupart des startups"

### Anti-schémas (abandonnés)
- Ouvertures d'inspiration génériques : -23% par rapport à la base de référence. Abandonner.

### Schémas à tester
- [ ] Confession à la première personne vs étude de cas à la troisième personne
- [ ] Hook temporel ("En 2024...") vs hooks intemporels

DSL de flux

# Séquentiel : a s'exécute, la sortie passe à b
flow: "researcher -> writer"

# Parallèle : a s'exécute, puis b et c s'exécutent en même temps
flow: "researcher -> [writer, analyst]"

… [tronqué pour la traduction]

Demander à votre IA préférée

Documentation