Table of Contents

🇬🇧 English version

Orkeon.Hosting — bootstrap des runners et des hôtes

Orkeon.Hosting est la couche de bootstrap partagée qui transforme les bibliothèques Orkeon en un hôte exécutable. Elle possède l'ordre de câblage dont un runtime fonctionnel a besoin — fournisseur LLM, services cœur, suites d'outils standard, système de fichiers virtuel et registre d'outils adossé à la DI — plus les flux d'exécution de bout en bout (kickoff one-shot, boucle interactive, listing des outils) utilisés par chaque runner et CLI Orkeon.

Dans ce dépôt, elle est consommée par Orkeon.Scripting.Cli (l'outil orkeon) et par Orkeon.Host (le démon orkeon-host). Elle n'est pas distribuée comme paquet NuGet — voir Distribution ci-dessous. Cette page documente sa surface de bootstrap publique, la télémétrie qu'exporte un hôte bâti dessus, et l'intégration .NET Aspire qui lance ses exécutables.

Distribution

Orkeon.Hosting est livrée dans le paquet Orkeon.Scripting. Son propre csproj reste IsPackable=false, il n'existe donc d'identifiant Orkeon.Hosting sur aucun flux : la matrice de publication liste l'opt-in Orkeon.Scripting, dont le wrapper (src/packaging/Orkeon.Scripting/Orkeon.Scripting.Package.csproj) embarque Orkeon.Hosting.dll à côté d'Orkeon.Scripting.dll ; Orkeon.Constants.Cli arrive comme dépendance de paquet.

dotnet add package Orkeon.Scripting

Elle n'est pas dans le parapluie Orkeon : l'hôte de runner compose toutes les familles d'outils intégrées, donc le paquet dépend d'Orkeon.Tools et d'Orkeon.Tools.Embeddings.Local — un poids qu'un consommateur du seul parapluie ne restaure jamais.

Assembly Orkeon.Hosting.dll (src/hosting/Orkeon.Hosting)
Paquet Orkeon.Scripting (embarquée ; le projet lui-même est IsPackable=false)
Dépendances du paquet Orkeon, Orkeon.Tools, Orkeon.Tools.Embeddings.Local, Jint, Microsoft.Extensions.Hosting, Microsoft.Extensions.Options, CommandLineParser
Livrée aussi par l'outil dotnet orkeon (Orkeon.Scripting.Cli) et les archives d'installation / .deb / MSI produits par release.yml, où Orkeon.Hosting.dll est posée à côté de orkeon et orkeon-host

Exécuter un crew dans le processus

Une application .NET exécute un crew.ork.ts — ou un crew.yaml, ou un dossier de crew multi-fichiers — sans démarrer le processus orkeon : ICrewScriptRunner est la forme in-process d'orkeon run.

using Microsoft.Extensions.DependencyInjection;
using Orkeon.Hosting;

var services = new ServiceCollection().AddOrkeonScripting(options =>
{
    options.SettingsPath = "appsettings.json";   // la section Llm, les montages, les outils - comme pour orkeon run
    options.Mounts.Add("./out:/output:rw");      // --mount
    options.Diagnostics = Console.Error;         // les lignes opérateur qu'orkeon run écrit sur stderr
});
using var provider = services.BuildServiceProvider();

var output = await provider.GetRequiredService<ICrewScriptRunner>().RunAsync("crew.ork.ts");
Console.WriteLine(output.Succeeded ? output.FinalOutput : output.Error);

new CrewScriptRunner(options) fait la même chose sans conteneur.

  • Ce qu'est une exécution. Chaque RunAsync construit son propre hôte de runner par l'amorçage partagé (RunnerExecution, le code qu'exécute orkeon run) : la cible du crew est résolue et montée, le fichier de settings est trouvé de la même façon, les gardes de montage s'exécutent, puis RunnerHost.Build compose le fournisseur LLM, les outils intégrés, le VFS, la porte de permissions (Orkeon:Security) et les serveurs MCP configurés. Le crew est chargé et lancé dans un seul scope ; l'hôte est libéré à la fin de l'exécution. Seul le runner est ajouté au conteneur de l'application.
  • Ce qui revient. Le CrewOutput de l'orchestrateur : un crew qui a tourné et échoué est une sortie avec Succeeded == false et son Error. Une exécution qui ne peut pas démarrer — une cible absente, un setting ou un montage que l'hôte refuse, un crew qui ne se charge pas — lève CrewScriptRunException avec la ligne qu'orkeon run aurait imprimée. Un cancellationToken annulé lève OperationCanceledException, avant que le crew démarre ou pendant qu'il tourne — jamais une sortie en échec.
  • Les chemins sont ceux du processus. Le chemin du crew, SettingsPath et les dossiers de Mounts se résolvent contre le répertoire de travail du processus quand ils sont relatifs, comme pour orkeon run ; un crew hors de ce répertoire est refusé sauf si AllowExternalMounts est posé. Un service dont le répertoire de travail n'est pas sa racine de contenu passe des chemins absolus.
  • Une configuration par conteneur. AddOrkeonScripting enregistre le runner par TryAdd : le premier appel l'emporte, et un second appel — avec d'autres options ou aucune — est ignoré. Une seconde configuration est un new CrewScriptRunner(options). Les exécutions d'un même runner peuvent avancer en même temps ; chacune construit son propre hôte.
  • La forme du script. Un .ork.ts doit remettre son crew (globalThis.crew = crew), la forme déclarative qu'orkeon run envoie dans le même pipeline. Un script procédural (qui pilote des agents lui-même, sans remise) n'est pas une définition de crew : exécutez-le avec orkeon run.
  • Options. SettingsPath, Mounts, MountIds, AllowExternalMounts et LlmProfile sont les options d'orkeon run de mêmes noms. ConfigureServices s'applique après les enregistrements d'Orkeon, donc en remplace un (un ILlmProviderFactory, un fournisseur d'entrée humaine). ConfigureLogging règle la journalisation de l'exécution ; sans lui l'exécution ne journalise rien, et les lignes opérateur ne vont qu'à Diagnostics.
  • esbuild. Un .ork.ts est bundlé par esbuild, que le paquet ne livre pas — la position de l'outil orkeon (Scripting). Mettez-le dans le PATH (npm install -g esbuild), ou pointez ORKEON_ESBUILD_PATH ou Orkeon:Scripting:Toolchain:EsbuildPath sur un binaire. Un crew YAML n'en a jamais besoin.
  • Pas un démon. Un crew qui doit continuer de tourner entre les requêtes — un canal de chat, A2A, plusieurs crews hébergés — relève d'orkeon-host (hôte de service).

RunnerHost.Build

RunnerHost est un builder d'hôte statique. Build retourne un IHost entièrement configuré :

IHost host = RunnerHost.Build(
    settingsPath: "appsettings.json",   // chemin d'appsettings résolu (nullable)
    mounts: new RunnerMountPlan          // toute la surface VFS, en un seul objet
    {
        CliMounts = ["/data:/data:ro"],   // arguments --mount de la CLI (« physique:virtuel:droits »)
        InternalMounts = [],              // montages enregistrés en MountVisibility.Internal — résolubles
                                          // par le VFS, jamais listés à un agent (ADR-008)
        AllowExternalMounts = false,      // autoriser des bases de montage hors de la racine du workspace
        SelectedMountIds = [],            // valeurs --mount-id, parsées : les entrées des settings gardées
                                          // quand plusieurs déclarent une même racine virtuelle
        CrewMountReferences = [],         // le bloc mounts: de la crew — sélectionne et valide, ne restreint jamais
        InputDirectories = [],            // dossiers qu'une commande lit comme entrées, lisibles sans l'opt-in
                                          // des montages externes
        WithdrawsAmbiguousRoots = false,  // true : une racine que les réglages déclarent plusieurs fois sans que
                                          // rien n'en choisisse une est retirée au lieu de refuser l'hôte
        LlmLogVirtualPath = null,         // si renseigné, un répertoire VIRTUEL que l'appelant a monté :
                                          // les échanges HTTP LLM y sont capturés en .jsonl
        WorkingDirectory = null,          // le dossier contre lequel se résout ./.orkeon/state (null : celui du processus)
        RunHistoryByDefault = false,      // l'historique des runs actif quand les réglages ne disent rien (orkeon-host le pose)
        LlmMockResponses = null,          // --llm-mock : un fichier JSONL VIRTUEL dont répond chaque profil LLM
        LlmRecordCassette = null,         // --llm-record : une cassette JSONL VIRTUELLE où s'écrit chaque appel LLM
        LlmReplayCassette = null,         // --llm-replay : une cassette JSONL VIRTUELLE dont répond chaque appel LLM
    },
    configureLogging: null,              // personnalisation optionnelle de ILoggingBuilder
    configureServices: null,             // hook optionnel pour enregistrer les services du runner
    configureBuilder: null,              // hook IHostBuilder optionnel — orkeon-host s'en sert pour UseSystemd()/UseWindowsService()
    llmProfile: null);                   // id de profil LLM d'hôte optionnel (--llm-profile) : Llm:Profiles:<id> devient la section Llm du run

Un llmProfile que la configuration ne définit pas est refusé par une RunnerSettingsException dont le message liste les profils qu'elle définit ; null ou default laisse la section Llm telle quelle.

Un chemin virtuel est toujours un nom commençant par / — jamais un chemin disque (ADR-008). RunnerVirtualRoots — dans le paquet sans dépendance Orkeon.Constants.FileSystem (ADR-009), pour que le moteur et l'outillage lisent une seule déclaration — nomme les racines que les runners livrés se réservent : /crew (le dossier de définition du crew), /script (le dossier d'un point d'entrée scripté), /llm-logs, /llm-mock et /llm-cassette (le fichier de --llm-mock et la cassette enregistrée ou rejouée), /sandbox (où les bacs à sable de code déposent ce qu'ils exécutent) et /credentials (les jetons OAuth des comptes e-mail et drive, refusée à un montage utilisateur par toutes les commandes). RunnerVirtualRoots.All est l'ensemble contre lequel un appelant refuse un --mount utilisateur ; demander l'ensemble plutôt que comparer les racines une à une est délibéré, car l'oubli de /sandbox a survécu à une comparaison deux à deux tant qu'elle restait verte. Un appelant qui active la journalisation des échanges monte son répertoire de logs en interne et passe ici RunnerVirtualRoots.LlmLogs — c'est ce que fait la CLI.

LoadCrewAsync prend de même sa cible en chemin virtuel : elle demande au VFS si la cible est un répertoire au lieu de sonder le disque, donc un chemin physique qu'on lui passe est refusé.

Il compose Host.CreateDefaultBuilder() avec :

  • Configuration d'application — les sources du builder par défaut retirées, celles de chaque hôte Orkeon (RunnerSettings.ComposeSources, que composent aussi RunnerSettings.ReadConfiguration — orkeon doctor, la sonde d'orkeon init — et le REPL) : les variables d'environnement sans préfixe, le fichier settingsPath s'il existe, puis l'environnement préfixé ORKEON_ (ORKEON_Llm__Model remplace Llm:Model). Ni l'appsettings.json et l'appsettings.{Environment}.json de la racine de contenu — le répertoire courant —, ni les secrets utilisateur. Puis une couche en mémoire qui porte les décisions de montage : les valeurs --mount placées par racine virtuelle, les montages internes, le montage /credentials des jetons OAuth e-mail et drive, et les entrées PathSecurity:AdditionalAllowedDirectories qui laissent le validateur de chemins atteindre les dossiers de ces montages (un --mount hors du dossier de travail seulement avec AllowExternalMounts).
  • Services — ConfigureRunnerServices (ci-dessous).
  • configureBuilder — invoqué en dernier, sur l'IHostBuilder lui-même.

Une fois construit, l'hôte juge d'abord ses réglages, que le run s'en serve ou non : chaque section qu'une inscription a déclarée — ses options créées, donc converties par le lieur et soumises à leurs règles, les noms qu'elles portent compris —, les noms de section sous Orkeon: et ses groupes, les clés de chaque section déclarée, et Orkeon:Rag:LlmProfile contre les profils qu'il offre (quand un réglage est refusé). Seules les options et les fabriques nommées sont créées : aucun magasin, fournisseur, modèle ni connexion. Le premier refus est une RunnerSettingsException qui nomme sa clé, l'hôte libéré : rien n'est journalisé, averti ni démarré.

Ensuite l'hôte journalise les décisions de montage qu'il a prises, avertit (dans le journal et sur stderr) quand un compte e-mail OAuth n'a pas de magasin de jetons ou quand il n'y a pas de section Llm — le runtime se replie alors sur le fournisseur écho —, dit d'où vient la clé du défaut et de chaque profil offert aux crews — les profils que cache sa liste blanche (LlmProfileAccessOptions, que lie orkeon-host) sur une ligne à part, jamais signalés — et résout les fournisseurs de traces et de métriques OpenTelemetry, parce que les runners ne démarrent jamais l'hôte et que ces fournisseurs n'existeraient sinon jamais (voir Télémétrie).

RunnerHost porte une exception bootstrap [SuppressVfsCompliance] : il résout des chemins de settings fournis par l'utilisateur et provisionne les montages VFS avant que le conteneur DI (et donc IFileSystemService) n'existe.

Comportement de ConfigureRunnerServices

L'ordre d'enregistrement est délibéré :

  1. Logging — le logging du runner (console sur une ligne au niveau Warning par défaut ; --verbose 1/2 ou un callback configureLogging le relève) et, quand RunnerMountPlan.LlmLogVirtualPath est renseigné, le DelegatingHandler de capture des échanges LLM.
  2. Le fournisseur LLM d'abord — RegisterLlmProvider lit la section de config Llm et enregistre le fournisseur (et son IChatClient, sur la configuration de cette section) avant AddOrkeonApplication / AddOrkeonInfrastructure — ou le fournisseur écho quand la section manque. L'infrastructure n'enregistre aucun modèle à elle : un hôte qui n'en enregistre aucun échoue à sa première résolution LLM, en nommant le service manquant.
  3. Services cœur — AddOrkeonApplication() puis AddOrkeonInfrastructure() (la surcharge sans paramètre), puis AddOrkeonTelemetry(configuration) pour la section Telemetry.
  4. Outils stricts — CrewFactoryOptions.StrictTools vaut true par défaut ici (un crew qui référence un outil inconnu échoue bruyamment avec unknown tool(s): …; available: …) ; opt-out via "Orkeon:CrewFactory:StrictTools": false. (Le défaut de la bibliothèque reste tolérant.) Les limites du bac à sable .ork.ts et la chaîne d'outils esbuild (ScriptingLimitsOptions, ScriptingToolchainOptions) sont aussi liées ici et jugées au démarrage de l'hôte.
  5. Permission gate — AddOrkeonPermissionGate(configuration) (opt-in par config Orkeon:Security:PermissionGate:Enabled ; no-op sinon).
  6. Suites d'outils cœur — système de fichiers, data, web, code, abstractions, outils de session ; puis l'EventHub en mémoire plus ses outils agents et l'ACL EventHub (AddOrkeonEventHubAcl, défaut permissif : une crew sans bloc links: envoie à toute autre crew) ; puis les outils e-mail (AddOrkeonEmailTools(configuration), inertes tant qu'aucun compte n'est déclaré) et, quand un compte e-mail OAuth est déclaré, leur magasin de jetons sur la racine interne /credentials — montée par l'étape de configuration, atteinte par PrivilegedFileSystemAccess ; puis les outils drive (AddOrkeonDriveTools(configuration), inertes tant qu'aucun compte n'est déclaré) et, quand la racine interne /credentials est montée, leur magasin de jetons dans un sous-répertoire à part ; puis le sous-système RAG et ses trois outils (AddOrkeonRag, AddOrkeonRagTools).
  7. Montages VFS — AddOrkeonFileSystem quand Orkeon:FileSystem:Mounts ou Orkeon:FileSystem:InternalMounts existe et contient au moins une entrée (deux tableaux vides n'enregistrent rien). L'une ou l'autre liste suffit à rendre le VFS réel : --list-tools n'a que la seconde. Plusieurs entrées de Mounts peuvent déclarer une même racine si chacune porte un identifiant : MountSelection.Resolve décide, pendant la composition de la configuration, laquelle ce run garde — un --mount sur la racine, sinon SelectedMountIds, sinon CrewMountReferences — et écrit les autres à null à leur propre index ; une sélection que rien ne résout lève le texte même que les gardes des runners impriment, si bien qu'un host construit sans elles refuse de la même façon.
  8. Suites d'outils tardives — RaggableTree (outils de graphe sémantique, opt-out via "RaggableTree:Enabled": false ; pré-enregistre les embeddings locaux quand ils sont le provider choisi), les outils WebSearch et cache_search, et l'outil de recherche Brave quand BRAVE_API_KEY est présent (clé de configuration ou variable d'environnement).
  9. MCP — AddOrkeonMcp(configuration) quand la section MCP déclare au moins un serveur sous MCP:Servers et que MCP:Enabled n'est pas false. Enregistrer n'est pas connecter : les serveurs sont connectés par les flux ci-dessous, avant le chargement de la crew (voir MCP). Aucun réglage ne démarre un serveur MCP.
  10. Modèles de décision — RegisterDecisionModels : un fournisseur de décision actif (TypeSafe, Liquid ou Kev), nommé par Orkeon:Decision:Provider ou déduit (la section Orkeon:TypeSafe ou Orkeon:Liquid, même vide, sinon celui dont la variable de clé est posée ; aucun quand rien n'est présent), et les profils de décision de Orkeon:Decision:Profiles. Le démarrage est refusé pour un nom de fournisseur inconnu, pour TypeSafe et Liquid tous deux présents sans fournisseur nommé (les deux sections, ou aucune section et les deux clés ; avec une seule section, son fournisseur est choisi) (le message cite les deux et le réglage), pour une adresse Kev sans schéma http ou https (Orkeon:Kev:BaseUrl), pour une clé Kev vers une adresse http non locale. Le journal de démarrage nomme le fournisseur actif, son modèle, son adresse et la façon dont il a été choisi ; chaque section de fournisseur qui n'est pas l'actif reçoit un avertissement (« is ignored: the active decision provider is … »), celui de Kev ajoutant, quand aucun fournisseur n'est nommé, que Kev n'est jamais déduit et doit être nommé par Orkeon:Decision:Provider. Voir Modèles de décision.
  11. Registre d'outils — rien de propre : AddOrkeonInfrastructure() a déjà enregistré le ToolRegistry par défaut, qui lit chaque IBaseTool enregistré par les étapes ci-dessus à sa première résolution.
  12. Services du runner — le hook configureServices de l'appelant s'exécute en dernier.

semantic_search n'est pas dans cette liste : il est enregistré par AddSemanticSearchTool(), qu'orkeon run appelle par son hook configureServices et qu'orkeon-host n'appelle pas.

Le registre d'outils (ToolRegistry)

L'IToolRegistry par défaut (Orkeon.Infrastructure.Tools, enregistré par AddOrkeonInfrastructure(), livré dans le paquet Orkeon) résout les noms d'outils YAML/TS en instances IBaseTool depuis la DI. Son constructeur prend IEnumerable<IBaseTool> — chaque outil enregistré par les suites — et les indexe par nom (insensible à la casse) ; deux outils enregistrés sous un même nom font lever le constructeur, qui nomme les deux types. CrewFactory le consomme pour construire les agents avec leurs outils déclarés, raison pour laquelle chaque suite enregistre sous IBaseTool : un outil non enregistré ne peut pas être résolu (et, avec StrictTools, fait échouer le chargement du crew au lieu d'être silencieusement ignoré). RegisterToolAsync ajoute un outil à l'exécution — c'est ce que fait le client MCP — et refuse (rend false) un nom qu'un autre outil tient déjà. Lectures et enregistrements à l'exécution peuvent s'entrelacer sans risque : orkeon-host mène plusieurs crews pendant que ses serveurs MCP se connectent. Le registre n'indexe que des noms — aucune recherche par étiquette ni par capacité.

RunnerExecution — flux d'exécution

RunnerExecution est la glu d'exécution partagée : arrêt gracieux (SIGTERM/SIGINT), câblage de l'AutoSummaryWriter quand un montage /output:rw est déclaré, presets de verbosité, et les flux d'exécution. Tous les points d'entrée construisent l'hôte en interne (même bootstrap), résolvent settings/montages et retournent un code de sortie processus.

Point d'entrée Rôle
RunOneShotAsync(opts, loggerCategory, configureServices?, externalCt?) Exécute un kickoff de crew de bout en bout. Codes de sortie : 0 succès, 1 erreur de config, 2 échec du crew, 75 le run s'est arrêté sur une question et attend la réponse (--resume), 130 annulé.
RunInteractiveLoopAsync(opts, loggerCategory, stopWords, kickoffPerInputAsync, onSessionStart, …) Boucle REPL ; chaque entrée déclenche un kickoff via le délégué fourni par l'appelant ; un mot d'arrêt termine la boucle (exit 0).
RunListToolsAsync(opts, loggerCategory, configureServices?, externalCt?) Construit l'hôte sans crew et imprime sur stdout les noms d'outils runtime triés et dédupliqués (logs sur stderr) — le contrat d'outils runtime consommé par l'outillage de packaging/lint.
RunValidateAsync(opts, loggerCategory, configureServices?, externalCt?) Le dry-run derrière --validate : construit l'hôte et charge la crew (résolution stricte des outils) sans sonder le LLM ni lancer de kickoff.
LoadCrewAsync(host, factory, configPath, logger, ct, targetIsDirectory?) Charge et mappe la définition de crew depuis son chemin virtuel (fichier YAML, dossier de crew, script .ork.ts/.ork.js) — la brique que les flux ci-dessus partagent, et ce qu'orkeon-host appelle à chaque exécution. Elle ne connecte pas les serveurs MCP.

RunOneShotAsync, RunValidateAsync et RunListToolsAsync connectent les serveurs MCP configurés avant de charger ou de lister quoi que ce soit, pour que les trois voient la même surface d'outils. Les gardes que la CLI exécute avant de construire un hôte sont publiques elles aussi — EnsureReservedRootsAreFree (ajoute toujours /credentials), EnsureVirtualRootsAreUnique, EnsureMountSelectionIsResolvable, EnsureMountSourcesExist — tout comme RegisterGracefulShutdown, DetectOutputMountPath, ConfigureVerboseLogging (1 : Information pour les modules Orkeon ; 2 : Debug) et IsScriptedCrewDefinition (.ork.ts / .ork.js).

Consommer depuis un hôte longue durée

Un service longue durée peut simplement envelopper RunnerHost.Build — c'est exactement ce que fait le daemon orkeon-host (Orkeon.Host/Program.cs), en passant configureBuilder pour UseSystemd()/UseWindowsService(). Le daemon reste hors de la sélection des montages : ses crews montent sous des racines par crew (/crews*), aucune racine n'y est donc jamais déclarée deux fois, un --mount opérateur portant un préfixe d'identifiant se parse comme un autre, et aucun bloc mounts: de crew n'est lu. Un hôte qui possède déjà son IHostBuilder (une app ASP.NET, par exemple) réplique l'ordre d'enregistrement de ConfigureRunnerServices dans son propre Program.cs — il n'existe pas de raccourci packagé pour cela ; la console REPL inline la même séquence à la main :

// 1. Enregistrer le fournisseur LLM (AddOrkeonLlmProvider) : AddOrkeonInfrastructure n'enregistre
//    aucun modèle à lui, et un conteneur qui n'en a pas échoue à sa première résolution LLM.
// 2. Services cœur :
services.AddOrkeonApplication();
services.AddOrkeonInfrastructure(configuration);
// 3. Suites d'outils (déterminent les outils utilisables par les crews) :
services.AddOrkeonFileSystemTools();
services.AddOrkeonDataTools();
services.AddOrkeonWebTools();
// … les autres suites AddOrkeon*Tools() …
// 4. Montages VFS depuis la configuration (l'hôte web provisionne au moins un montage) :
services.AddOrkeonFileSystem(configuration);
// 5. Rien pour le registre d'outils : AddOrkeonInfrastructure a enregistré le ToolRegistry
//    par défaut, qui lit chaque IBaseTool enregistré ci-dessus à sa première résolution.

Parce qu'un hôte web exécute typiquement chaque crew dans son propre scope DI (les dépôts de crews d'Orkeon sont scoped), le ToolRegistry — un singleton sur l'ensemble des IBaseTool enregistrés — est partagé entre les exécutions, tandis que CrewFactory et l'orchestrateur se résolvent par scope.

Télémétrie

AddOrkeonTelemetry(configuration) lit la section Telemetry :

Clé Défaut Effet
Enabled true false n'enregistre ni fournisseur ni exportateur : le meter Orkeon mesure pour personne.
OtlpEndpoint — Un point de terminaison OTLP explicite ; il l'emporte sur l'environnement. Une adresse http:// ou https:// : toute autre valeur est refusée, en nommant la clé.
MaxMemoryMB 2048 Seuil du contrôle de santé system_resources.

Console. Aucun réglage n'attache d'exportateur console : il écrirait sur stdout, là où --events jsonl, le manifeste de --list-tools et orkeon mcp serve parlent à un programme. Un hôte C# qui veut la console ajoute l'exportateur à son propre AddOpenTelemetry().

Où vont les données. Un Telemetry:OtlpEndpoint explicite sert de point de terminaison aux exportateurs. Sans lui, un OTEL_EXPORTER_OTLP_ENDPOINT non vide attache les exportateurs OTLP sans aucun réglage propre à Orkeon — l'exportateur lit alors lui-même le point de terminaison, le protocole et les en-têtes dans les variables standard OTEL_EXPORTER_OTLP_*, ce qui permet à un processus lancé par .NET Aspire de rapporter sans rien configurer. Il les lit dans la configuration de l'hôte, par sa couche de variables d'environnement sans préfixe : la raison pour laquelle chaque hôte Orkeon garde cette couche, sous son fichier de réglages (d'où viennent les réglages). Sans l'un ni l'autre, rien n'est exporté.

Ce qui est exporté. Les traces des sources d'activité Orkeon.Crew, Orkeon.Agent, Orkeon.Task, Orkeon.Llm, Orkeon.Tool, Orkeon.Memory, Orkeon.EventHub et Orkeon.Scripting plus l'instrumentation HttpClient ; les métriques du meter Orkeon plus l'instrumentation runtime et HttpClient ; et, dès que l'export OTLP est actif, les journaux structurés (message formaté et scopes compris) vers le même point de terminaison. La ressource nomme le service Orkeon et lui donne la version de la release en cours d'exécution (service.version), que les sources d'activité et le compteur rapportent aussi. Les noms de spans et de métriques suivent les conventions GenAI d'OpenTelemetry — voir Sous-systèmes opt-in.

La section enregistre aussi trois contrôles de santé — llm_provider, memory_provider (qui lit une clé absente : chaque provider le sert, Pinecone et ChromaDB compris), system_resources. orkeon ne sert aucun HTTP ; orkeon-host les expose sur son API de runs opt-in (Orkeon:Host:Api) : /healthz lance system_resources, /readyz lance memory_provider et, quand ReadinessTags contient llm, llm_provider (voir l'API du host).

.NET Aspire — Orkeon.Hosting.Aspire

Orkeon.Hosting.Aspire (paquet Orkeon.Hosting.Aspire, voir la matrice de publication) décrit des processus Orkeon comme ressources d'un AppHost Aspire, pour que le tableau de bord Aspire montre leurs spans, métriques et journaux (ADR-011). Il n'exécute lui-même aucune crew : il lance les exécutables livrés, trouvés sur le PATH ou nommés par command.

Installer. Dans un projet AppHost Aspire (Aspire.AppHost.Sdk) :

dotnet add package Orkeon.Hosting.Aspire
dotnet tool install -g Orkeon.Scripting.Cli   # l'exécutable `orkeon` que lance AddOrkeonCrewRun

orkeon-host vient des archives d'installation complètes ou du MSI per-machine du service — qui n'est pas signé : Windows demande avant de le lancer, voir le service host — ; passez son chemin en command s'il n'est pas sur le PATH. Lancez ensuite l'AppHost avec dotnet run et ouvrez le tableau de bord.

Ce qui circule. Vers chaque processus : ses arguments et les variables ORKEON_ fixées par WithOrkeonSetting/WithOrkeonModel, plus les variables OTEL_EXPORTER_OTLP_* et OTEL_SERVICE_NAME qu'Aspire injecte. Depuis lui : les traces, métriques et journaux structurés décrits sous Télémétrie, et la sortie console. Rien d'autre — ni endpoint, ni sonde de santé, ni état : le tableau de bord observe, il ne pilote pas un run.

var builder = DistributedApplication.CreateBuilder(args);

// le daemon orkeon-host, ses crews enregistrées dans son fichier de settings
builder.AddOrkeonHost("orkeon-host", settingsPath: "host.appsettings.json")
       .WithOrkeonSetting("Orkeon:Host:RunTimeout", "00:10:00");

// un `orkeon run`, fichiers sous ./out, sur un modèle local
builder.AddOrkeonCrewRun("quickstart", crewPath: "../../quickstart/crew.yaml")
       .WithOrkeonModel(new Uri("http://localhost:11434"), "qwen2.5:1.5b");

builder.Build().Run();
Membre Ce qu'il fait
AddOrkeonHost(name, settingsPath?, workingDirectory?, command = "orkeon-host") Une OrkeonHostResource (exécutable) lancée en orkeon-host [--settings <settingsPath>] --allow-external-mounts, dans workingDirectory (défaut : le dossier de l'AppHost), avec l'exportateur OTLP câblé. Aucun endpoint n'est déclaré : l'API de runs et le serveur A2A du daemon sont des réglages opt-in (Orkeon:Host:Api, Orkeon:Host:A2A) que la ressource ne câble pas.
AddOrkeonCrewRun(name, crewPath, outputDirectory?, settingsPath?, command = "orkeon") Une OrkeonCrewRunResource lancée en orkeon run <crewPath> --mount <sortie>:/output:rw --allow-external-mounts [--settings <settingsPath>] dans le dossier de l'AppHost, avec l'exportateur OTLP câblé. Le dossier de sortie (défaut <AppHost>/out) est créé dès la déclaration de la ressource.
WithOrkeonSetting(key, value) Fixe n'importe quelle clé de configuration par l'environnement ORKEON_ que lisent les runners : Llm:Model devient ORKEON_Llm__Model. La clé est le chemin de configuration complet — les clés propres au daemon vivent sous Orkeon:Host, donc Orkeon:Host:RunTimeout, pas Host:RunTimeout.
WithOrkeonModel(baseUrl, model, apiKey?) Raccourci pour Llm:BaseUrl (/ final retiré), Llm:Model et, s'il est donné, Llm:ApiKey.

Un AppHost exécutable se trouve dans examples/aspire/AppHost.

Microsoft Agent Framework

Pour exécuter une crew depuis une application Microsoft Agent Framework — ou un agent MAF dans une crew — voir Interop Agent Framework : son exemple construit son hôte avec RunnerHost.Build et ajoute le pont par configureServices.