Orkestra : orchestrer des agents IA à grande échelle

Les chiffres de cet article reflètent le système au moment de la publication (janvier 2026). Consultez notre page équipe pour les chiffres actuels.

Quand nous avons commencé à construire avec Claude Code, nous nous sommes heurtés à un problème que toute équipe utilisant des assistants de codage IA finit par rencontrer : un seul agent ne peut pas tout bien faire.

Vous pouvez demander à un agent d’être un spécialiste base de données. Ou un auditeur de sécurité. Ou un ingénieur frontend. Mais dès l’instant où vous lui demandez d’être les trois à la fois, la qualité en souffre. Le contexte se dilue. Les instructions entrent en conflit. L’agent devient un généraliste médiocre en tout.

Nous avons donc construit Orkestra.

Qu’est-ce qu’Orkestra ?

Orkestra est un système d’orchestration d’agents pour Claude Code et les outils de codage IA similaires. Il coordonne plusieurs agents spécialisés, chacun doté d’une expertise distincte, sous un orchestrateur unique qui répartit le travail vers le bon spécialiste.

Imaginez-le comme une agence de placement pour agents IA. L’orchestrateur reçoit une tâche, identifie quel spécialiste doit la traiter, et délègue avec le bon contexte. Une fois le travail fait, les résultats remontent vers l’orchestrateur pour synthèse.

Les chiffres parlent d’eux-mêmes :

Composant	Nombre
Agents spécialistes	46
Compétences réutilisables	466
Archétypes d’identité	27
États d’esprit	11
Styles de communication	10
Domaines de connaissance	21

Le système de personnage : le D&D des agents

L’idée centrale derrière Orkestra est que le comportement d’un agent émerge de trois primitives composables :

L’identité définit ce que l’agent est. Un architecte conçoit des structures système. Un débogueur remonte des échecs jusqu’à leurs causes racines. Un gardien fait respecter la conformité et les frontières de sécurité. Nous avons 27 archétypes d’identité qui peuvent être combinés.

L’état d’esprit définit comment l’agent pense. Un état d’esprit analytique ancre les affirmations dans des preuves et quantifie l’incertitude. Un état d’esprit sceptique interroge les hypothèses et recherche des preuves contradictoires. Un état d’esprit exploratoire embrasse l’ambiguïté et essaie plusieurs approches.

Le style définit comment l’agent communique. Un style technique inclut des valeurs exactes et référence des fichiers précis. Un style concis élimine le superflu et commence par la réponse. Un style diplomatique équilibre honnêteté et tact.

Un agent combine ces primitives :

# architecture-advisor.yaml
identity:
  - knowledge-architect
  - architect
  - strategist
mindset: analytical
style: concise

Cette composition crée un agent qui conçoit des systèmes (architecte), relie les connaissances entre domaines (architecte-connaissances), fixe une direction stratégique (stratège), pense en preuves et en données (analytique), et communique sans superflu (concis).

La puissance vient de l’explosion combinatoire. 27 identités multipliées par 11 états d’esprit multipliées par 10 styles donnent près de 3 000 personnalités d’agent possibles. Mais vous ne définissez que les combinaisons qui comptent pour votre travail.

Compétences : des modules de capacité réutilisables

Les compétences sont le savoir et les flux de travail que les agents peuvent invoquer. Elles suivent un système par paliers fondé sur la portée :

Palier	Nom	Portée	Exemple
K0	Fondations	Méthodologie universelle	Discipline test-first, achèvement fondé sur les preuves
K1	Identités	Flux de travail par rôle	Standards d’interface CLI, guide de performance
K2	Domaines	Savoir spécifique à un domaine	Schémas de migration de base de données, validation d’authentification
K3	Piles techniques	Spécifique à une technologie	Déploiement Cloudflare, opérations Supabase
K4	Projet	Cette base de code uniquement	Flux de travail et conventions spécifiques au projet

Les compétences sont chargées paresseusement. Un agent voit les noms et descriptions des compétences au démarrage, mais le contenu complet d’une compétence ne se charge que lorsqu’elle est déclenchée. Cela garde le contexte léger tout en rendant des centaines de compétences découvrables.

Chaque compétence inclut :

• Des conditions de déclenchement claires (« À utiliser lors de la migration de schémas de base de données »)
• Des consignes étape par étape
• Les outils autorisés pour le flux de travail
• Des critères de succès et des chemins de récupération en cas d’échec

Les 466 compétences de notre registre couvrent tout, de l’isolation par worktree Git aux flux de travail de recherche web, en passant par la validation de la santé des déploiements.

Pourquoi l’orchestration compte

Les architectures à agent unique se heurtent vite à des murs :

Dilution du contexte. Une fenêtre de contexte de 200 000 tokens paraît vaste, jusqu’à ce que vous chargiez des schémas de base de données, de la documentation d’API, des fixtures de test et du savoir de domaine. Les spécialistes peuvent travailler avec un contexte ciblé.

Conflits d’instructions. Dire à un agent d’« être minutieux mais rapide » et de « tout vérifier sans sur-ingénierie » crée une tension. Les spécialistes résolvent cela en ayant une portée claire.

Profondeur d’expertise. Un agent généraliste sait un peu de tout. Un agent spécialiste, composé avec la bonne identité et les bonnes compétences, connaît son domaine en profondeur.

Orkestra met en œuvre une orchestration plate : un orchestrateur coordonne plusieurs spécialistes. Les spécialistes ne peuvent pas engendrer de sous-spécialistes. Cela empêche l’explosion de complexité tout en permettant le travail parallèle.

L’orchestrateur a accès à une capacité effective de 2,2 millions de tokens : sa propre fenêtre de 200 000 tokens, plus 10 sous-agents simultanés de 200 000 tokens chacun. Un travail qui épuiserait un agent unique tourne confortablement à travers la flotte.

Le pipeline de rendu

Les définitions d’agents vivent en YAML. Claude Code lit du Markdown. Orkestra comble cet écart avec un pipeline de rendu déterministe :

YAML Registries → Jinja Templates → .claude/agents/*.md

Les opérateurs modifient la source YAML. Exécutent orkestra sync. Le Markdown rendu apparaît dans .claude/agents/. Claude Code récupère les changements.

Cette séparation sert des publics différents :

• La source YAML inclut les métadonnées de cycle de vie, les tags, les règles de validation et les notes de dépréciation pour l’outillage
• Le Markdown rendu inclut seulement ce dont le modèle a besoin : description, outils, compétences et consignes de comportement

Le pipeline compose identités, états d’esprit, styles et compétences en un seul prompt cohérent. Un agent architecte-analytique-concis reçoit un prompt système très différent d’un agent débogueur-sceptique-technique, même s’ils partagent certaines compétences sous-jacentes.

Savoir de domaine : le schéma en quatre fichiers

Chaque domaine de connaissance suit une structure cohérente :

domain-name/
  decisions.md      # Key choices, rationale, consequences
  patterns.md       # Step-by-step guidance and examples
  anti-patterns.md  # Failure modes and remediation
  evolution.md      # Dated log of changes

Cette structure sert le chargement du contexte des agents. Un agent qui travaille sur l’authentification charge authentication/patterns.md pour s’orienter et authentication/anti-patterns.md pour éviter les pièges connus. Les fichiers sont dimensionnés pour un chargement de contexte efficace : assez ciblés pour être utiles, assez complets pour faire autorité.

Nous maintenons 21 domaines de premier niveau, incluant l’analytique, l’authentification, la data science, l’infrastructure, l’apprentissage automatique, la performance, la sécurité, et plus encore. Chaque domaine peut avoir des sous-domaines pour une granularité plus fine.

Valeurs : le système d’exploitation

Tous les agents partagent une couche de base de valeurs qui définit comment ils opèrent :

La simplicité d’abord. Utiliser la solution la plus simple qui fonctionne. N’ajouter de la complexité que lorsqu’elle est justifiée.

Corriger les causes racines. Ne jamais rafistoler autour des échecs. Si un pipeline échoue, déboguer le pipeline. Si un test échoue, corriger le code ou le test.

Fondé sur les preuves. Étiqueter les affirmations comme « vérifiées » (avec des benchmarks) ou « estimées » (avec des hypothèses). Un schéma détecté n’équivaut pas à un problème confirmé.

Économie de contexte. Les outils MCP coûtent 0,1 % du contexte. Les lectures de fichiers coûtent 2 % chacune. Appliquer l’expertise de domaine avant d’explorer le code.

Ces valeurs se propagent à chaque spécialiste via le pipeline de rendu. Un agent ne peut pas les contourner par composition.

CLI : le plan de contrôle

Orkestra est livré avec une CLI pour gérer l’écosystème d’agents :

# Discovery
orkestra agents search "database"
orkestra agents info database-architect

# Validation
orkestra validate --show-warnings

# Rendering
orkestra sync --dry-run
orkestra sync

# Skills
orkestra skills list
orkestra skills info schema-migration-workflow

# Decisions
orkestra decisions search "authentication"

La CLI est la source de vérité pour savoir quels agents existent, quelles compétences ils possèdent, et si le système est en bonne santé. Elle exécute une validation avant la synchronisation pour détecter les problèmes tôt.

Considérations open source

Nous avons construit Orkestra pour résoudre notre propre problème : coordonner des agents IA à grande échelle pour une base de code complexe. Les schémas que nous avons découverts ne sont pas spécifiques à notre domaine.

Le système de composition de personnage (identité + état d’esprit + style) s’applique à toute équipe qui définit des personnalités d’agent.

Le système de paliers de compétences (K0-K4) fournit un modèle mental pour organiser des capacités réutilisables par portée.

Le schéma de pipeline de rendu (source YAML + templates + artefacts générés) sépare les préoccupations entre l’outillage et la consommation par le modèle.

Le modèle d’orchestration plate (un coordinateur, de nombreux spécialistes) évite la complexité tout en permettant le parallélisme.

Qu’Orkestra devienne open source ou non dépend de la valeur de ces schémas pour d’autres équipes qui construisent avec Claude Code. Si vous vous heurtez aux murs que nous avons décrits, cette architecture pourrait vous aider.

Ce que nous avons appris

Construire Orkestra nous a appris que l’orchestration ne consiste pas à rendre les agents plus intelligents. Elle consiste à les rendre plus concentrés.

Un agent unique avec des instructions parfaites finit quand même par manquer de contexte. Un agent unique avec toutes les compétences se retrouve quand même embrouillé sur laquelle appliquer. Un agent unique qui essaie d’être tout produit des résultats médiocres partout.

Quarante spécialistes, chacun excellent dans son domaine, coordonnés par un orchestrateur qui sait quand déléguer : voilà comment nous livrons.

Les chiffres comptent moins que l’architecture. Vous pourriez avoir besoin de cinq agents, ou de cinquante. Le principe demeure : la composition plutôt que la capacité brute, la spécialisation plutôt que la généralisation, la coordination plutôt que l’héroïsme individuel.

---

Orkestra alimente l’écosystème d’agents derrière Maguyva, notre plateforme d’intelligence du code. Vous voulez en savoir plus ? Contactez l’équipe.