🇬🇧 English version
Documentation Orkeon
Structure
La documentation est organisée en 8 sections thématiques.
Politique de langue — chaque page sous
docs/est maintenue en anglais et en français en parallèle (docs/fr/reflète l'arborescence chemin pour chemin) ; un miroir manquant fait échouer la CI (scripts/check-docs-parity.sh). Voir CONTRIBUTING.fr.md pour le contrat.
En ligne — cette arborescence et la référence d'API générée sont publiées à l'adresse https://orkeon.github.io/orkeon/, déployées par
docs.ymlà chaque tagv*. Le site documente donc toujours une version taguée.
Démarrage
| Fichier | Description |
|---|---|
| Trois façons d'exécuter Orkeon | Page centrale : depuis les sources vs binaire de release vs conteneur — prérequis, commandes, canaux d'installation par OS et tableau comparatif ; l'installation depuis les sources, REPL compris ; la mise à jour, vers la dernière release ou vers le dernier main (canal dev) |
| Exécuter votre premier exemple (depuis les sources) | Première exécution de bout en bout : prérequis, matrice de profils LLM, la commande complète, chaque flag du runner, résolution des settings, dépannage |
| Vue d'ensemble | Architecture, concepts fondamentaux (Agent, Task, Tool, Crew), YAML vs Fluent Builder |
| Bootstrap et exécution | Packages, câblage DI d'un hôte embarquant Orkeon (modèle, montages VFS, registre d'outils), exécution d'une Crew, modes batch/streaming/fire-and-forget |
| YAML, Builders et CrewFactory | Fluent Builders, schéma YAML, pipeline CrewFactory, modes de chargement |
| Comportements par défaut | Les défauts DI délibérément minimaux (base de connaissances, cache LLM, système mémoire, sélection d'agent, embeddings) : ce que chacun fait, le signal warn-once, et le geste de remplacement — et les deux services sans défaut utilisable (VFS, modèle) |
| Forger une équipe à partir d'un besoin | L'Atelier (orkeon forge) : besoin → entretien → équipe → essai en bac à sable → verdict contre vos propres critères → promotion, sessions reprenables sur disque ; autres options (--read, --reference, --with-settings, forge rename) |
Donner une boîte aux lettres aux agents est l'une des fonctionnalités les plus demandées : le tutoriel en met une en service en quelques minutes, le guide couvre chaque fournisseur et chaque réglage.
| Fichier | Description |
|---|---|
| Donner une boîte aux lettres à vos agents | Tutoriel : un compte Gmail, un mot de passe d'application, et un agent qui range le courrier non lu dans des dossiers et laisse chaque réponse en brouillon — rien n'est envoyé |
| Outils e-mail | Donner une boîte aux lettres aux agents : Gmail (mot de passe d'application ou OAuth2), Hotmail/Outlook.com via Microsoft Graph, votre propre serveur IMAP/POP3/SMTP ; droits par compte, liste d'autorisation d'envoi fermée par défaut, filtrage anti-injection, orkeon email login, emplacement des jetons, dépannage |
Commandes orkeon email |
accounts (ce qui est déclaré, ce qui est prêt), check (se connecter et lister les dossiers), login / logout pour les comptes OAuth2 — options et codes de sortie |
| ADR-012 — la famille d'outils e-mail | Pourquoi l'e-mail vit dans Orkeon même, et les alternatives écartées |
Drives dans le nuage
| Fichier | Description |
|---|---|
| Outils drive | Donner aux agents un Google Drive ou un OneDrive : enregistrer l'application OAuth, orkeon drive login, droits, le dossier racine qu'un agent ne peut pas quitter, la liste d'autorisation de partage fermée, ce que le jeton n'atteint jamais |
L'outil firefox |
Donner aux agents le Firefox de la machine, par WebDriver BiDi : un navigateur par exécution, ou un que l'hôte garde entre les exécutions, la page comme graphe de sections, liens et contrôles, des identifiants de nœuds pour cliquer et saisir, search par le sens, ce que la politique d'URL vérifie et ce qui ne passe jamais par l'outil |
Commandes orkeon drive |
accounts, check (trouver le dossier racine et le lister), login / logout — options et codes de sortie |
| ADR-013 — la famille d'outils drive | Pourquoi une famille d'outils plutôt qu'un montage VFS, et la couche OAuth que partagent les deux familles cloud |
Architecture
| Fichier | Description |
|---|---|
| Fournisseurs LLM | 16 providers (OpenAI, Anthropic, Azure, Grok, Ollama, les agrégateurs OpenRouter et Mammouth, etc.), capacités et points d'extension du dialecte, résolution du provider, décorateurs et journalisation des échanges LLM, kit de campagnes sur API réelle |
| Fournisseurs de modèles | Les quatre catégories de fournisseurs de modèles (génération, embedding, reranking, décision), leurs contrats et le ModelProviderCatalog |
| Modèles de décision | Les fournisseurs System One (TypeSafe, Liquid, Kev) derrière IDecisionModel, un seul actif à la fois : questions typées, profils de décision qui bloquent, routent ou escaladent un appel au LLM (cascade, routeur), la garde d'entrée, le reranker decision et system_one_decide |
| Système de mémoire | 5 types de mémoire, 6 providers (InMemory, Redis, SQLite, ChromaDB, Pinecone, LanceDB), mémoire cognitive |
| Événements, CQRS et observabilité | 23 domain events — ceux des tâches et des agents au fil du run, ceux de la crew en fin de kickoff, et par les commandes CQRS —, pipeline CQRS, 2 surfaces d'observation (ICrewExecutionHook, ICallbackHandler avec une étape par appel d'outil) |
| EventHub et cycle de vie des crews | Spécification de référence du messaging inter-agents et inter-crews (EventHub) et de la mise en sommeil/réveil des crews — ports Application, l'adaptateur en mémoire et ses cinq étages de middleware (les hôtes livrés ne câblent que l'ACL), les outils agents ; la persistance SQLite et le sommeil/réveil sont spécifiés, pas encore construits |
| L'API du host et les sondes de santé | La surface HTTP d'orkeon-host, désactivée par défaut : /healthz et /readyz (ce que chacune vérifie, systemd, Docker et Kubernetes), POST /runs avec clés d'idempotence, liste des runs, événements SSE et NDJSON avec reprise, annulation ; authentification partagée avec A2A |
| Le host de service et la passerelle de chat | orkeon-host : héberger des crews en daemon (systemd, service Windows, conteneur), isolation par run, et la passerelle Discord avec sa liste d'autorisation, son routage thread-est-run et son bouton d'arrêt |
| Le bus d'événements du run | orkeon run --events jsonl : le protocole versionné qu'un autre programme lit, les commandes qu'il peut renvoyer, et le siège client:// qu'il obtient sur le hub du run |
| Sécurité, résilience et plugins | Défense en profondeur : les couches de sécurité, de l'outil à l'audit ; politiques Polly, checkpointing, système de plugins |
| Conformité VFS | Principe VFS-only (tout I/O via IFileSystemService) : analyseur Roslyn Orkeon.Compliance.Vfs, 7 diagnostics, périmètres exemptés, critères de sortie de la migration |
| Conformité console | Pas de System.Console dans le code du framework : l'analyseur ORKCON001, les adaptateurs de console et l'unique puits par exécutable, IRunnerConsole / ITerminalProbe, le canal d'avertissements Orkeon.Operator |
| Système de plugins | Contrat IOrkeonPlugin, découverte VFS, isolation AssemblyLoadContext, activation opt-in AddOrkeonPlugins, ⚠️ frontière de confiance |
| DSL de scripting | DSL à syntaxe TypeScript (.ork.ts) : transpilation esbuild, exécution sandboxée Jint, toute la surface Orkeon (agents, crews, tools, FSM, graphes, événements) via builders fluides |
| Commandes CLI TypeScript | Commandes REPL interactives en *.cmd.ts (defineCommand) chargées au démarrage sans recompilation .NET, avec dispatch de travail vers les agents |
| Client & serveur MCP | Intégration Model Context Protocol à deux époques (2026-07-28 sans état + révisions héritées), transports, activation, outils MCP et crews, limites honnêtes |
| Piloter des crews depuis le REPL | Le pont .cmd.ts → crew.ork.ts : plan de contrôle *.cmd.ts vs moteur crew.ork.ts via le service script-host, ctx.llm.act comme boucle d'agent, la garde de permissions et les ports de session — avec une session REPL sans clé, exécutable |
| Référence YAML | Source unique du schéma YAML complet (crew, agents, tasks, graph) |
| RaggableTree — graphe sémantique | Pipeline 6 phases, 29 tools, 12 langages, réindexation incrémentale, fraîcheur paresseuse, recherche hybride, injection de contexte, ce que les hôtes câblent réellement |
| Pipeline RAG | Le sous-système src/rag/ : ingestion, pipeline à 7 étages (transform → retrieve → fuse/MMR → rerank → assemble → generate → groundedness), graphe correctif CRAG, repli web, 5 profils, évaluation mesurée |
| ADR — RaggableTree | Décision graphe stratifié via Tree-sitter (5 niveaux L0–L4 plus la couche d'arêtes), alternatives rejetées, conséquences, amendement d'état d'implémentation du 2026-09-30 |
| Décisions d'architecture (ADR) | ADR-002 (shared kernel Tools.Abstractions), ADR-003 (shared kernels Analysis), ADR-004 (jumeaux de nommage scripting — remplacé par l'ADR-007), ADR-005 (famille Tools.* hétérogène), ADR-006 (sous-système RAG src/rag/), ADR-007 (D3 : renommage Orkeon.Cli.Commands.Scripting), ADR-008 (les chemins virtuels sont la seule monnaie versée aux agents), ADR-009 (satellites de constantes partagées), ADR-010 (interop Microsoft Agent Framework en paquet séparé, dans les deux sens), ADR-011 (le dashboard Aspire est la surface d'observabilité ; pas de front-end web), ADR-012 (la famille d'outils e-mail, deuxième exception motivée au gel du périmètre), ADR-013 (la famille d'outils drive), ADR-014 (le confinement du shell par défaut), ADR-015 (les catégories de fournisseurs de modèles et les étapes de décision), ADR-016 (les tâches de décision et l'éclatement conditionnel), ADR-017 (le modèle d'affichage du transcript), ADR-018 (les moteurs de graphe et le bloc YAML graph:) |
| ADR-014 — le confinement du shell par défaut | Pourquoi shell_command est confiné par plateforme par défaut, coupé dans les conteneurs, et tourne dans une session shell par exécution d'agent |
| ADR-015 — les catégories de fournisseurs de modèles et les étapes de décision | Pourquoi les fournisseurs de modèles se rangent en catégories (génération, embedding, reranking, décision), pourquoi les fournisseurs de décision (TypeSafe, Liquid, Kev) ont leur propre port IDecisionModel, et pourquoi une étape de décision juge un appel au LLM sans le réécrire |
| ADR-016 — les tâches de décision et l'éclatement conditionnel | Pourquoi une tâche de décision répond sans agent, pourquoi une condition when fait ignorer une tâche au lieu de la faire échouer, et quels processus les prennent en charge |
| ADR-017 — le modèle d'affichage du transcript | Pourquoi le transcript peint sur un texte qui reste la seule source, pourquoi seul le contenu peint un fond, et pourquoi un script ne choisit jamais de couleur |
ADR-018 — les moteurs de graphe et le bloc YAML graph: |
Pourquoi deux boucles de graphe restent, ce qu'elles partagent (validation de topologie, vocabulaire, budgets), et la forme et les règles du bloc graph: |
Orchestration
| Fichier | Description |
|---|---|
| Guide comparatif ProcessTypes | Les 6 stratégies côte à côte : matrice, arbre de décision, avantages et inconvénients, coûts |
| FSM — Machine à états | Moteur FSM générique du domaine (utilisé par orkeon forge ; sa policy de circuit breaker borne Graph et le graphe RAG correctif), 4 mécanismes, presets, guards |
| Graph — Graphe d'états | Le mode de process Graph (topologie fixe, circuit breaker à 3 mécanismes) et l'API C# StateGraph style LangGraph : edges conditionnels, cycles contrôlés, retry |
| Autonomous — Auto-organisation | Budget multi-dimensions, tâches assignées par le manager, délégation à un pair en cas d'échec, spawn fourni par l'hôte, canal A2A |
Outils
| Fichier | Description |
|---|---|
| Inventaire des outils | 124 outils par catégorie avec leurs paramètres d'appel, résolution YAML (stricte/tolérante), enregistrement DI, disponibilité par hôte, gaps identifiés |
| Créer un nouvel outil | Pipeline typé, attributs FieldSchema/ReturnSchema, pattern composition, enregistrement |
Guides
| Fichier | Description |
|---|---|
| Écrire une crew en TypeScript | Le DSL .ork.ts de bout en bout : les deux formes de script et pourquoi choisir la mauvaise abandonne la moitié de ce que vous avez écrit (bruyamment) : tâches, agents, outils, le DAG withContext, livrables, ctx.llm.act, état, réglage de l'éditeur |
| Méthodologie de portage | 5 étapes pour migrer une application, YAML d'abord ou code d'abord, estimation de l'effort |
| Exemple de portage | Pipeline e-commerce complet : analyse, mapping agents, YAML, bootstrap C# |
| Blueprint nouvelle orchestration | Gabarit en 8 étapes pour ajouter un nouveau ProcessType au framework |
| Contenu multi-modal (vision) | Vision réelle : MultiModalContent → LlmMessage → blocs Anthropic / parts OpenAI (14 providers compatibles) / images Ollama, chargeur VFS, activation opt-in |
| Enregistrer et rejouer les appels LLM | --llm-record et --llm-replay : figer les appels d'un run réel dans une cassette JSONL et les rejouer sans réseau, la clé d'un appel, le masquage, un échec de rejeu, ce qu'une cassette ne contient pas |
| Format de réponse LLM | Sortie contrainte à la frontière provider (json_object / json_schema), traduction pilotée par les capacités de chaque provider, cascade crew → agent → task → script → appel |
| Quality Gate SonarQube | Analyse SonarQube locale avec la gate « Orkeon Transitional » : seuils transitoires, trajectoire de durcissement, provisionnement automatique par les scripts |
| Modèles locaux | Tout exécuter sur sa machine : Docker Model Runner (pull/configure/inspect, contextes 128K), Ollama, variante d'image local-llm embarquée, changement de modèle, dépannage |
| Vérifier ce que vous installez | Ce que la chaîne de provenance prouve et ne prouve pas (Trusted Publishing OIDC, attestations SLSA, Releases immuables, SHA256SUMS, SBOM), les commandes exactes gh attestation verify / dotnet nuget verify, la requête à l'API sans token, et pourquoi un paquet nuget.org doit être dépouillé de sa signature avant que son digest corresponde |
| Installer avec apt | Debian / Ubuntu (amd64, arm64) : ajouter une fois la source apt signée d'Orkeon, puis apt install / apt upgrade ; les canaux stable, rc et dev, le retour à une version, la désinstallation, les builds Docker, le dépannage |
| Interop MCP | Vérifier le client MCP contre le serveur de référence (server-everything) : le test nocturne et la procédure du MCP Inspector. |
| Whisper par MCP | Transcrire de l'audio depuis orkeon-repl, orkeon run ou orkeon-host : un faster-whisper local derrière un serveur MCP, ses réglages MCP:Servers et de montage, le côté agent, et les limites d'Orkeon autour desquelles le serveur est écrit (chemins, résultats texte seul, plafond de 4000 caractères, handshake de 30 s) |
Référence
| Fichier | Description |
|---|---|
| Référence du DSL de scripting | Chaque builder et chaque méthode .ork.ts, avec la colonne qui n'existe nulle part ailleurs : laquelle des deux formes l'honore. Plus les écarts connus entre les typings et le runtime |
| Catalogue des exemples | Carte éditoriale d'examples/ (9 catégories métier + vitrines RAG/RaggableTree/scripting) ; l'examples/INDEX.md généré est l'inventaire faisant foi |
Référence CLI orkeon |
Chaque commande (run, init, llm, rag, forge, usecases, email, drive, doctor, settings, typings, mcp, quickstart, eval, runs) avec options et exemples, plus orkeon-repl |
| Référence de configuration | La carte unique des réglages (Llm, Orkeon:*, MCP…) : sources et précédence, puis chaque clé par catégorie — une ligne par clé, avec son type, son défaut et les hôtes qui la lisent |
| Limites et contraintes | Contraintes connues de la version courante, dont ce qui est livré mais pas encore câblé |
| Matrice de conformité A2A | Position honnête face à la spec A2A v1.0 : opérations, modèle de données, bindings, sécurité — ce qui interopère et ce qui n'interopère pas |
| Politique de stabilité et de versionnement | Ce qu'un correctif, une mineure et une majeure peuvent changer ; la surface API figée (PublicAPI.Shipped.txt), le hors-engagement, la dépréciation, les versions prises en charge |
| APIs expérimentales | Surfaces [Experimental] (A2A, Autonomous, RAG correctif, MCP), IDs de diagnostic ORKEXP001–007, comment s'inscrire |
| Politique de données des exemples | Pourquoi les exemples livrent de la config et pas des datasets, comment monter vos entrées (/data:ro, /output:rw), règles contributeurs pour les fixtures d'exemple fournies |
| Sous-systèmes opt-in | A2A, monitoring, NIST, DLP, rate-limiting d'outils, rotation de clés, benchmarking, multi-modal, hooks de kickoff, sous-système RAG — activation explicite AddOrkeonXxx() (hors DI par défaut) ; plus les briques que AddOrkeonInfrastructure() enregistre et celles que rien ne consomme |
| Hosting & bootstrap des runners | Orkeon.Hosting : RunnerHost.Build, ordre de câblage ConfigureRunnerServices (LLM d'abord, suites d'outils, VFS, le ToolRegistry par défaut), flux RunnerExecution, télémétrie (OTLP), .NET Aspire (AddOrkeonHost, AddOrkeonCrewRun), pattern hôte web |
| Interop Microsoft Agent Framework | Une crew Orkeon comme AIAgent MAF (CrewAgent, AddOrkeonAgentFramework) ; un agent MAF comme modèle d'un agent Orkeon (WithAgentFrameworkAgent) ou comme outil (WithAgentFrameworkTool) |
| Gabarit de README d'exemple | Gabarit pour examples/**/README.md : Ce qu'il fait / Prérequis / Données requises / L'exécuter / Sortie attendue / Durée & coût |
| Comparatif des fournisseurs LLM | Matrice de capacités par provider (streaming SSE, tool calling natif, grammaire GBNF, response_format, thinking, métriques, résilience), dérivée du code source |
| Résultats des campagnes LLM | Le dernier résultat contre l'API réelle de chaque modèle campagné, mode par mode, régénéré par le kit de campagne après chaque campagne |
| Matrice de publication | Source de vérité de ce qui est publié où : NuGet.org vs GitHub Packages, tools dotnet, artefacts d'installation, flux de version, le canal dev (le dernier main entre deux tags) |
Parcours de lecture recommandés
"Je veux comprendre le framework"
overview → yaml-and-builders → process-types → fsm → graph → autonomous → inventory → new-tool-pattern
Commencer par la vue d'ensemble pour assimiler Agent, Task, Crew, Tool. Puis explorer la configuration YAML et les builders. Le guide comparatif des ProcessTypes donne une vision d'ensemble des 6 stratégies, les docs FSM/Graph/Autonomous approfondissent les modes avancés. L'inventaire des outils montre les capacités natives. Terminer par le pattern de création d'outil pour comprendre l'extensibilité.
"J'ai une application Ă migrer"
overview → bootstrap → inventory → porting-methodology → porting-example → new-tool-pattern
S'imprégner de l'architecture et du câblage DI. Identifier les outils disponibles. Appliquer la méthodologie avec l'exemple concret. Revenir au pattern outil si des outils sur mesure sont nécessaires.
"Je veux étendre le framework"
overview → new-tool-pattern → yaml-and-builders → blueprint → inventory
Comprendre l'architecture, puis maîtriser le pipeline typé et le pattern de composition. Le blueprint guide la création de nouveaux modes d'orchestration. L'inventaire sert de référence pour positionner les contributions.
"Je veux que mes agents traitent des e-mails"
give-your-agents-a-mailbox → email (guide) → cli (orkeon email) → security
Mettez une boîte aux lettres en service de bout en bout avec le tutoriel, puis ouvrez le guide pour votre fournisseur (Gmail OAuth2, Outlook.com/Hotmail via Microsoft Graph, votre propre serveur IMAP/POP3/SMTP), le modèle de droits et la liste d'autorisation d'envoi. La référence CLI liste les commandes orkeon email ; la page sécurité situe le filtrage anti-injection parmi les autres couches.