Table of Contents

🇬🇧 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 tag v*. 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)

E-mail

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.