Kernel d'Organisation pour Reseaux d'Agents Logiques
60 ans de science de la collaboration humaine, traduits en architecture multi-agents IA.
KORAL est un framework open-source d'orchestration multi-agents implemente sous forme de skills pour Claude Code. Il traduit 60 ans de recherche en science de la collaboration humaine en patterns d'architecture IA concrets et reutilisables. Développé par Félix LENCI.
Bag of Agents (sans KORAL) Equipe coordonnee (avec KORAL)
Agent A ──?──> ??? Coordinator ──> Architect (Plant)
Agent B ──?──> ??? |──> Coder (Implementer)
Agent C ──?──> ??? |──> Reviewer (Monitor Evaluator)
Agent D ──?──> ??? └──> Tester (Completer-Finisher)
|
Pas de roles definis Roles Belbin assignes
Pas de coordination Topologie Orchestrator
Pas de memoire Memoire transactive (Wegner)
Pas de qualite Evaluator-Optimizer loop
Resultat : chaos Resultat : livrable coherent
Le Bag of Agents Problem est la premiere cause d'echec des systemes multi-agents en production (40-87% des pilotes echouent). Il se manifeste quand on lance plusieurs agents IA sans structure de coordination. KORAL resout ce probleme en appliquant des theories scientifiques validees depuis 60 ans.
| Metrique | Valeur | Source |
|---|---|---|
| Gain multi-agents vs single-agent | +90.2% | Anthropic, 2024 |
| Taux d'echec des pilotes multi-agents | 40-87% | Gartner / McKinsey, 2024-2025 |
| Performance roles specifies vs generaux | 58% vs 36% | Li et al., "Camel", 2023 |
| Marche agents IA 2025 | $7.84B | Grand View Research |
| Marche agents IA 2030 (projection) | $52.62B | Grand View Research |
| Correlation QI moyen / intelligence collective | r=0.15 (FAIBLE) | Woolley & Malone, 2010 |
| Impact de la diversite sur la performance | >2x | Woolley & Malone, 2010 |
Chaque theorie a ete traduite en protocole executable. KORAL n'est pas une metaphore, c'est une implementation operationnelle.
TUCKMAN LIFECYCLE — Cycle de vie d'equipe KORAL
================================================
Phase 1 Phase 2 Phase 3 Phase 4 Phase 5
FORMING STORMING NORMING PERFORMING ADJOURNING
┌──────┐ ┌──────┐ ┌──────┐ ┌──────────┐ ┌─────────┐
│ Init │──────> │Diver-│──────> │Conver│──────> │ Execution│────>│ Wrap-up │
│ │ │gence │ │gence │ │ │ │ │
└──────┘ └──────┘ └──────┘ └──────────┘ └─────────┘
│ │ │ │ │
v v v v v
Contexte Exploration Consensus Production Memoire
partage, independante, sur le plan, selon topologie, persistee,
roles Belbin, debat MAD, standards, circuit breaker, metriques,
mission devil's synthese metriques agiles rapport final
prompt advocate
| Phase | Action KORAL | Duree typique |
|---|---|---|
| Forming | Chargement contexte, assignation roles Belbin, mission prompt | ~10% du run |
| Storming | Debat multi-agents (DMAD), propositions independantes, devil's advocate | ~20% du run |
| Norming | Synthese des propositions, plan d'execution, normes de qualite | ~15% du run |
| Performing | Execution selon topologie, circuit breaker actif, metriques | ~45% du run |
| Adjourning | Sauvegarde memoire, metriques, rapport final | ~10% du run |
HACKMAN PRE-FLIGHT CHECKLIST
============================
╔════════════════════════════════════════════════════════════════╗
║ CONDITION VERIFICATION KORAL RESULTAT ║
╠════════════════════════════════════════════════════════════════╣
║ ║
║ [?] 1. REAL TEAM Agents definis avec : ║
║ (Equipe reelle) - Nom et role clairs ║
║ - Frontieres definies ║
║ - Interdependances explicites ║
║ ║
║ [?] 2. COMPELLING Mission prompt incluant : ║
║ DIRECTION - Objectif unique et clair ║
║ - Criteres de succes ║
║ - Livrables mesurables ║
║ ║
║ [?] 3. ENABLING Chaque agent dispose de : ║
║ STRUCTURE - Outils appropries a son role ║
║ - Formats I/O definis ║
║ - Protocoles de handoff ║
║ ║
║ [?] 4. SUPPORTIVE Contexte disponible : ║
║ CONTEXT - Fichiers projet accessibles ║
║ - Connaissances domaine fournies ║
║ - Historique runs precedents ║
║ ║
║ [?] 5. EXPERT Coaching en place : ║
║ COACHING - Agent orchestrateur configure ║
║ - Chemin d'escalade vers humain ║
║ - Mecanismes de feedback ║
║ ║
╚════════════════════════════════════════════════════════════════╝
Si une condition echoue : ARRET. L'execution ne demarre pas.
Enrichit le prompt de l'agent avec le contexte pertinent (fichiers, memoire, recherche) avant execution. Toujours applique en premiere etape.
Fichiers ──> Context ──> Agent projet Assembly enrichi Memoire ──> TMS
Pipeline sequentiel avec gate de qualite entre chaque etape. Si le score < seuil, retry avant de passer au suivant.
Agent 1 ──[gate >=7?]──> Agent 2 ──[gate >=7?]──> Agent 3
|retry |retryAgents en parallele sur des sous-taches independantes ou la meme tache (voting). Agregation finale.
┌──> Agent A ──┐
Task ──┼──> Agent B ──┼──> Agregation
└──> Agent C ──┘Classification et routage vers l'agent specialiste le plus qualifie. Utilise le TMS "qui sait quoi" de Wegner.
┌──> Specialiste A Routeur ────┼──> Specialiste B (TMS) └──> Specialiste C
Boucle generateur/evaluateur iterative. Le generateur produit, l'evaluateur score, feedback si score < seuil. Max 3 iterations.
Generator ──> Draft ──> Evaluator ──> Score
^ |
└── feedback (si < 7.0) ┘Un orchestrateur central (opus) decompose, delegue et synthetise. Les workers (sonnet) executent les sous-taches.
┌─────────────────────┐
│ ORCHESTRATOR │
│ (opus / CO) │
└──┬──────┬──────┬────┘
v v v
Worker Worker Worker
(IMP) (SP) (CF)
sonnet sonnet sonnet
TRANSACTIVE MEMORY SYSTEM — "Qui sait quoi ?"
================================================
┌─────────────────────────────────────────────────────────┐
│ TMS ROUTING TABLE │
│ .koral/memory/tms-routing.json │
├─────────────────────────────────────────────────────────┤
│ │
│ Domaine Agents experts │
│ authentication --> [architect, security-specialist] │
│ frontend --> [ui-developer, designer] │
│ database --> [data-engineer, architect] │
│ testing --> [qa-engineer, reviewer] │
│ │
└─────────────────────────────────────────────────────────┘
| | |
v v v
┌──────────────┐ ┌──────────────┐ ┌──────────────────┐
│ EPISODIQUE │ │ SEMANTIQUE │ │ PROCEDURALE │
│ │ │ │ │ │
│ Ce qui s'est │ │ Ce que l'on │ │ Comment on fait │
│ passe │ │ sait │ │ les choses │
│ │ │ │ │ │
│ - Outcomes │ │ - Faits │ │ - SOPs │
│ - Erreurs │ │ - Entites │ │ - Workflows │
│ - Lecons │ │ - Domaines │ │ - Best practices │
└──────────────┘ └──────────────┘ └──────────────────┘
KORAL s'installe en 30 secondes. Aucune dependance externe requise.
# 1. Cloner le depot git clone https://github.com/FelixMining/KORAL.git # 2. Copier les skills dans votre projet cp -r KORAL/.claude/skills/koral* votre-projet/.claude/skills/ # 3. C'est tout ! Utilisez /koral dans votre projet
# Creer des symlinks vers les skills ln -s /chemin/vers/KORAL/.claude/skills/koral \ votre-projet/.claude/skills/koral # Repeter pour koral-team, koral-run, # koral-monitor, koral-memory
git submodule add \ https://github.com/FelixMining/KORAL.git \ .koral-framework cp -r .koral-framework/.claude/skills/koral* \ .claude/skills/
Telechargez le ZIP depuis GitHub et copiez le dossier .claude/skills/ dans votre projet.
/koral sans argument. L'assistant guide pose 6 questions et configure tout automatiquement.
/koral create a REST API with auth. KORAL analyse, detecte secteur/complexite/topologie et propose un lancement.
/koral-team create puis /koral-run puis /koral-monitor. Controle total.
KORAL se decompose en 5 skills specialises, chacun avec ses sous-commandes.
| Etape | Question | Options |
|---|---|---|
| 1/6 | Secteur | Dev, Marketing, Research, Finance, Custom |
| 2/6 | Tache | Texte libre |
| 3/6 | Complexite | Simple, Medium, Complex, Auto |
| 4/6 | Topologie | Pipeline, Parallel, Orchestrator, Debate, Auto (Thompson) |
| 5/6 | HITL | Autonomous, Checkpoints, Supervised |
| 6/6 | Qualite | Standard, Evaluator-Optimizer, MAD/DMAD |
createAssistant de creation d'equipe en 7 etapes
listLister toutes les equipes configurees
show <name>Afficher les details d'une equipe
edit <name>Modifier une equipe existante
delete <name>Supprimer une equipe (avec confirmation)
templatesAfficher les 4 templates pre-configures
| Syntaxe | Comportement |
|---|---|
/koral-run dev-squad Implement auth | Charge l'equipe + lance la tache |
/koral-run dev-squad | Charge l'equipe, demande la tache |
/koral-run | Liste les equipes, demande le choix |
latestDashboard du dernier run en cours
<run-id>Dashboard d'un run specifique
historyHistorique de tous les runs passes
metricsMetriques agregees inter-runs + facteur "c"
show [type]Afficher le contenu memoire
search <query>Rechercher dans toute la memoire
add <type> <content>Ajouter une entree memoire
clear <type>Effacer un type (avec confirmation)
exportExporter toute la memoire en markdown
Chaque topologie correspond a un type d'interdependance (Thompson) et un pattern Anthropic.
Agent 1 ──[gate]──> Agent 2 ──[gate]──> Agent 3 ──> Output RI SP CF collect analyze finalize
┌──> Agent A ──> output-a ──┐
Task ──┼──> Agent B ──> output-b ──┼──> Coordinator ──> Final
└──> Agent C ──> output-c ──┘ (merge) ┌────────────────────┐
│ ORCHESTRATOR │
│ (opus / CO) │
└──┬─────┬─────┬────┘
assign v v v assign
┌────┐┌────┐┌────┐
│W-A ││W-B ││W-C │ sonnet
└──┬─┘└──┬─┘└──┬─┘
report v v v report
┌────────────────────┐
│ SYNTHESE FINALE │
└────────────────────┘Round 1: Propositions independantes A prop. | B prop. | C prop. Round 2: Critiques croisees A->B | B->C | C->A Round 3: Revisions A' | B' | C' Judgment: Monitor Evaluator synthetise
KORAL EXECUTION FLOW
====================
Utilisateur
|
| /koral [task] ou /koral (wizard)
v
┌────────────────────┐
│ MODE SELECTION │──> Quick Mode ou Wizard (6 QCM)
└─────────┬──────────┘
v
┌────────────────────┐
│ INITIALIZATION │──> mkdir .koral/, config.json, team.json, state.json
└─────────┬──────────┘
v
┌────────────────────┐ ┌───────────────────┐
│ HACKMAN │──X──> │ STOP + diagnostic │
│ PRE-FLIGHT │ └───────────────────┘
│ (5 conditions) │
└─────────┬──────────┘
| OK
v
┌────────────────────┐
│ TUCKMAN CYCLE │
│ │
│ Forming ────┐ │
│ Storming ───┤ │ Circuit Breaker actif
│ Norming ────┤ │ HITL aux checkpoints
│ Performing ─┤ │ Memoire TMS consultee
│ Adjourning ─┘ │ Metriques collectees
│ │
└─────────┬──────────┘
v
┌────────────────────┐
│ OUTPUT │──> final.md + metrics.json + memory update
└────────────────────┘
CIRCUIT BREAKER FLOW
====================
Agent Action
|
v
Execute ──> Success ──> Continue
|
v (failure)
Retry 1 (ajuste prompt) ──> Success ──> Continue
|
v (failure)
Retry 2 (simplifie scope) ──> Success ──> Continue
|
v (failure)
Retry 3 (template partiel) ──> Success ──> Continue
|
v (failure)
┌──────────────────────────────────────────┐
│ FALLBACK STRATEGY │
│ │
│ degrade ──> Continue sans cet agent │
│ skip ──> Retirer la sous-tache │
│ escalate ──> Pause + demande a humain │
└──────────────────────────────────────────┘
votre-projet/ ├── .claude/ │ └── skills/ │ ├── koral/ # /koral — Commande principale │ ├── koral-team/ # /koral-team — Gestion d'equipes │ ├── koral-run/ # /koral-run — Execution │ ├── koral-monitor/ # /koral-monitor — Monitoring │ └── koral-memory/ # /koral-memory — Memoire │ └── .koral/ # Donnees runtime (cree automatiquement) ├── config.json # Configuration globale ├── teams/ # Configurations d'equipes (.json) ├── memory/ │ ├── episodic/ # Experiences passees │ ├── semantic/ # Connaissances validees │ ├── procedural/ # Procedures eprouvees │ └── tms-routing.json # Table "qui sait quoi" ├── runs/ │ └── <timestamp>/ │ ├── state.json # Etat du run │ ├── outputs/ # Sorties des agents + final.md │ └── logs/ # Logs detailles └── templates/ # Templates personnalises
Chaque template est une configuration d'equipe optimisee pour un secteur, basee sur les roles Belbin et les topologies Thompson.
{
"version": "1.0.0",
"default_hitl_level": 1,
"default_quality": "evaluator-optimizer",
"circuit_breaker": {
"max_retries": 3,
"timeout_ms": 120000,
"fallback": "degrade_gracefully"
},
"evaluator_optimizer": {
"threshold": 7.0,
"max_iterations": 3
}
}| Aspect | Autonomous | Checkpoints | Supervised |
|---|---|---|---|
| Forming | Auto | Validation | Validation |
| Norming | Auto | Approbation plan | Review detaille |
| Performing | Auto | Auto | Approbation chaque agent |
| Temps ajoute | 0% | +20-30% | +100-200% |
| Risque | Moyen | Faible | Tres faible |
| Scenario | max_retries | timeout_ms | fallback | propagation |
|---|---|---|---|---|
| Dev rapide | 2 | 60 000 | degrade | isolate |
| Production standard | 3 | 120 000 | degrade | isolate |
| Compliance critique | 5 | 300 000 | escalate | halt |
| Experimentation | 1 | 30 000 | skip | isolate |
Le taux d'echec de 40-87% des pilotes multi-agents vient de ces erreurs recurrentes. KORAL les previent structurellement.
Preferez un single-agent quand : la tache est simple et mono-domaine, elle prend moins de 5 minutes,
le domaine est unique sans ambiguite, les contraintes de temps sont serrees, ou le resultat est factuel et univoque.
Regle pratique : si un seul prompt bien concu peut resoudre le probleme, ne lancez pas 4 agents pour le faire.
Developpeur passione par l'intelligence artificielle et l'orchestration multi-agents.