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
RunAsyncconstruit son propre hôte de runner par l'amorçage partagé (RunnerExecution, le code qu'exécuteorkeon 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, puisRunnerHost.Buildcompose 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
CrewOutputde l'orchestrateur : un crew qui a tourné et échoué est une sortie avecSucceeded == falseet sonError. 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èveCrewScriptRunExceptionavec la ligne qu'orkeon runaurait imprimée. UncancellationTokenannulé lèveOperationCanceledException, 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,
SettingsPathet les dossiers deMountsse résolvent contre le répertoire de travail du processus quand ils sont relatifs, comme pourorkeon run; un crew hors de ce répertoire est refusé sauf siAllowExternalMountsest posé. Un service dont le répertoire de travail n'est pas sa racine de contenu passe des chemins absolus. - Une configuration par conteneur.
AddOrkeonScriptingenregistre le runner parTryAdd: le premier appel l'emporte, et un second appel — avec d'autres options ou aucune — est ignoré. Une seconde configuration est unnew 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.tsdoit remettre son crew (globalThis.crew = crew), la forme déclarative qu'orkeon runenvoie 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 avecorkeon run. - Options.
SettingsPath,Mounts,MountIds,AllowExternalMountsetLlmProfilesont les options d'orkeon runde mêmes noms.ConfigureServicess'applique après les enregistrements d'Orkeon, donc en remplace un (unILlmProviderFactory, un fournisseur d'entrée humaine).ConfigureLoggingrè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.tsest bundlé par esbuild, que le paquet ne livre pas — la position de l'outilorkeon(Scripting). Mettez-le dans lePATH(npm install -g esbuild), ou pointezORKEON_ESBUILD_PATHouOrkeon:Scripting:Toolchain:EsbuildPathsur 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 aussiRunnerSettings.ReadConfiguration—orkeon doctor, la sonde d'orkeon init— et le REPL) : les variables d'environnement sans préfixe, le fichiersettingsPaths'il existe, puis l'environnement préfixéORKEON_(ORKEON_Llm__ModelremplaceLlm:Model). Ni l'appsettings.jsonet l'appsettings.{Environment}.jsonde 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--mountplacées par racine virtuelle, les montages internes, le montage/credentialsdes jetons OAuth e-mail et drive, et les entréesPathSecurity:AdditionalAllowedDirectoriesqui laissent le validateur de chemins atteindre les dossiers de ces montages (un--mounthors du dossier de travail seulement avecAllowExternalMounts). - Services —
ConfigureRunnerServices(ci-dessous). configureBuilder— invoqué en dernier, sur l'IHostBuilderlui-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é :
- Logging — le logging du runner (console sur une ligne au niveau Warning par défaut ;
--verbose 1/2ou un callbackconfigureLoggingle relève) et, quandRunnerMountPlan.LlmLogVirtualPathest renseigné, leDelegatingHandlerde capture des échanges LLM. - Le fournisseur LLM d'abord —
RegisterLlmProviderlit la section de configLlmet enregistre le fournisseur (et sonIChatClient, sur la configuration de cette section) avantAddOrkeonApplication/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. - Services cœur —
AddOrkeonApplication()puisAddOrkeonInfrastructure()(la surcharge sans paramètre), puisAddOrkeonTelemetry(configuration)pour la sectionTelemetry. - Outils stricts —
CrewFactoryOptions.StrictToolsvauttruepar défaut ici (un crew qui référence un outil inconnu échoue bruyamment avecunknown 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.tset la chaîne d'outils esbuild (ScriptingLimitsOptions,ScriptingToolchainOptions) sont aussi liées ici et jugées au démarrage de l'hôte. - Permission gate —
AddOrkeonPermissionGate(configuration)(opt-in par configOrkeon:Security:PermissionGate:Enabled; no-op sinon). - 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 bloclinks: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 parPrivilegedFileSystemAccess; puis les outils drive (AddOrkeonDriveTools(configuration), inertes tant qu'aucun compte n'est déclaré) et, quand la racine interne/credentialsest montée, leur magasin de jetons dans un sous-répertoire à part ; puis le sous-système RAG et ses trois outils (AddOrkeonRag,AddOrkeonRagTools). - Montages VFS —
AddOrkeonFileSystemquandOrkeon:FileSystem:MountsouOrkeon:FileSystem:InternalMountsexiste 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-toolsn'a que la seconde. Plusieurs entrées deMountspeuvent déclarer une même racine si chacune porte un identifiant :MountSelection.Resolvedécide, pendant la composition de la configuration, laquelle ce run garde — un--mountsur la racine, sinonSelectedMountIds, sinonCrewMountReferences— 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. - 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 etcache_search, et l'outil de recherche Brave quandBRAVE_API_KEYest présent (clé de configuration ou variable d'environnement). - MCP —
AddOrkeonMcp(configuration)quand la sectionMCPdéclare au moins un serveur sousMCP:Serverset queMCP:Enabledn'est pasfalse. 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. - Modèles de décision —
RegisterDecisionModels: un fournisseur de décision actif (TypeSafe, Liquid ou Kev), nommé parOrkeon:Decision:Providerou déduit (la sectionOrkeon:TypeSafeouOrkeon: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 deOrkeon: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émahttpouhttps(Orkeon:Kev:BaseUrl), pour une clé Kev vers une adressehttpnon 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é parOrkeon:Decision:Provider. Voir Modèles de décision. - Registre d'outils — rien de propre :
AddOrkeonInfrastructure()a déjà enregistré leToolRegistrypar défaut, qui lit chaqueIBaseToolenregistré par les étapes ci-dessus à sa première résolution. - Services du runner — le hook
configureServicesde 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.