🇬🇧 English version
Bootstrap et exécution
Voir aussi : Vue d'ensemble · Configuration YAML · Retour à l'index
Récupérer les paquets
Avant que le code ci-dessous ne compile, ajoutez les deux paquets NuGet qu'il utilise. Le
framework lui-même est livré en un seul paquet, Orkeon ; les suites d'outils intégrées
câblées plus bas (AddOrkeonFileSystemTools, AddOrkeonDataTools, AddOrkeonWebTools,
AddOrkeonCodeTools, AddOrkeonEmailTools ; le paquet porte d'autres suites, comme AddOrkeonDriveTools) vivent dans un second, Orkeon.Tools :
dotnet add package Orkeon
dotnet add package Orkeon.Tools
Les deux commandes écrivent les entrées
<PackageReference> correspondantes dans votre .csproj — une édition à la main donne
exactement le même résultat.
Orkeon embarque la fermeture du cœur en un seul paquet — Domain, Application,
Infrastructure, les moteurs RAG et RaggableTree (Orkeon.Analysis),
Orkeon.Tools.Abstractions et quatre satellites Orkeon.Constants.* ; il n'existe pas de
paquet séparé Orkeon.Domain / Orkeon.Application / Orkeon.Infrastructure. L'hôte des
runners (Orkeon.Hosting, RunnerHost) et le DSL de scripting (Orkeon.Scripting) n'en font
pas partie : ils sont livrés dans le paquet opt-in Orkeon.Scripting et dans la CLI
orkeon — c'est pourquoi l'hôte ci-dessous est câblé à la main. Le chargeur de plugins
(Orkeon.Plugins, IOrkeonPlugin) en fait partie. Les
opt-ins Orkeon.Rag.Onnx, Orkeon.Tools.Embeddings.Local,
Orkeon.Interop.AgentFramework et Orkeon.Hosting.Aspire s'ajoutent de la même façon
quand vous en avez besoin. La liste complète est la
matrice de publication.
Partir d'un modèle
dotnet new install Orkeon.Templates ajoute trois modèles, chacun un projet qui compile
contre les paquets de la même version, écrite en clair dans son .csproj :
| Commande | Génère |
|---|---|
dotnet new orkeon-host -n MyHost |
Un hôte générique .NET qui exécute crew.ork.ts dans son propre processus (ICrewScriptRunner, de Orkeon.Scripting), configuré par appsettings.json comme le démon orkeon-host |
dotnet new orkeon-plugin -n MyPlugin |
Un IOrkeonPlugin, un outil et le plugin.json qui le déclare (le chargeur refuse un outil que le manifeste ne liste pas) |
dotnet new orkeon-tool -n MyTools |
Une bibliothèque de classes avec un outil ToolBase<TRequest, TResponse>, comme dans le patron de nouvel outil |
orkeon init est un autre travail : il écrit le fichier de settings, jamais un projet. Le modèle d'hôte
demande esbuild sur la machine pour compiler crew.ork.ts, comme orkeon run.
Bootstrap et injection de dépendances
L'intégration d'Orkeon dans une application .NET s'effectue par injection de dépendances au démarrage. Voici un exemple complet dans Program.cs, sur l'hôte générique .NET (le paquet Microsoft.Extensions.Hosting — un projet dotnet new worker le référence déjà ) :
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Orkeon.Application.DependencyInjection;
using Orkeon.Domain.SharedKernel.ValueObjects;
using Orkeon.Domain.Tools;
using Orkeon.Infrastructure.DependencyInjection;
using Orkeon.Infrastructure.FileSystem;
using Orkeon.Infrastructure.LLMs;
using Orkeon.Tools.FileSystem.DependencyInjection;
using Orkeon.Tools.Data.DependencyInjection;
using Orkeon.Tools.Web.DependencyInjection;
using Orkeon.Tools.Code.DependencyInjection;
using Orkeon.Tools.Email.DependencyInjection;
var host = Host.CreateDefaultBuilder(args)
.ConfigureServices((context, services) =>
{
// 0. Le modèle : AddOrkeonInfrastructure() n'en enregistre aucun, et un conteneur
// qui n'en a pas échoue à sa première résolution LLM. Ici : un modèle Ollama local.
var llm = LlmConfig.Create("qwen2.5:1.5b") with { BaseUrl = new Uri("http://localhost:11434") };
services.AddOrkeonLlmProvider(
sp => new OllamaLlmProvider(llm, sp.GetRequiredService<IHttpClientFactory>()), llm);
// 1. Couche Application (CQRS, orchestration, services)
services.AddOrkeonApplication();
// 2. Couche Infrastructure (plomberie LLM, mémoire, sécurité, YAML)
services.AddOrkeonInfrastructure();
// 3. Le système de fichiers virtuel — montages lus dans Orkeon:FileSystem:Mounts.
// Obligatoire : le chargeur YAML, les outils fichier et les livrables passent tous par lui.
services.AddOrkeonFileSystem(context.Configuration);
// 4. Suites d'outils
// FileSystem : FileRead, FileWrite, EditFile, DirectoryRead, DirectorySearch, Glob, Grep, CountPattern
services.AddOrkeonFileSystemTools();
// Data : CSV, PDF, JSON, XML, DOCX, XLSX, requĂŞtes SQL, requĂŞtes MongoDB, etc.
services.AddOrkeonDataTools();
// Web : WebScrape, ScrapeElement, HttpApi, GitHub, ImageGeneration, Firefox
// (WebSearch/BraveSearch/Slack/CacheSearch ont leurs propres extensions opt-in)
services.AddOrkeonWebTools();
// Code : ShellCommand (SecureCodeInterpreter est câblé par le sandbox d'AddOrkeonInfrastructure)
services.AddOrkeonCodeTools();
// E-mail : les 13 outils email_*, EmailParser compris, sur les comptes déclarés sous
// Orkeon:Tools:Email (voir docs/fr/guides/email.md)
services.AddOrkeonEmailTools(context.Configuration);
})
.Build();
// 5. Rien à fournir : le registre d'outils qu'a enregistré AddOrkeonInfrastructure lit
// chaque IBaseTool ci-dessus, donc les noms qu'une crew YAML liste sous `tools:` se résolvent.
// Un hôte de longue durée : await host.RunAsync(). Un programme ponctuel exécute une
// crew tout de suite — voir « Exécuter une Crew » ci-dessous.
Les montages viennent d'appsettings.json (format Docker <physique>:<virtuel>:<droits>,
droits ro, rw ou rwnd ; le répertoire physique doit exister) :
{
"Orkeon": {
"FileSystem": {
"Mounts": [ "./config:/config:ro", "./out:/output:rw" ]
}
}
}
Chacun des 16 fournisseurs s'enregistre de la même façon : construisez-le à partir d'un
LlmConfig, ou laissez ILlmProviderFactory.Create(config) le choisir d'après l'URL de
base, le nom du modèle ou la clé. AddOrkeonLlmProvider place une seule instance derrière
ILlmProvider, IBasicLlmProvider et IChatClient, mesurée comme tout fournisseur que la
factory construit. Un fournisseur construit directement envoie les outils d'un agent en natif,
comme celui de la factory : le modèle appelle un outil au lieu d'en écrire l'appel en texte.
La CLI orkeon fait tout cela dans RunnerHost (section Llm, montages, registre
alimenté depuis la DI) et enregistre quelques suites de plus, qu'un hôte ajoute de la même
façon quand ses crews s'en servent : AddOrkeonAbstractionTools() (list_mounts),
AddOrkeonSessionTools(), AddOrkeonInMemoryEventHub() + AddOrkeonEventHubTools(),
AddRaggableTree() + AddRaggableTreeTools(), et la paire RAG
AddOrkeonRag(configuration) + AddOrkeonRagTools() (la CLI y ajoute AddOrkeonOnnxReranker()).
Chaque appel AddOrkeon*() enregistre automatiquement :
- Les interfaces de service (ports)
- Les implémentations (adapters)
- Les dépendances transitives (factories, converters, validators)
- Les outils disponibles dans la suite
Cette approche garantit une injection de dépendances cohérente et testable conforme à l'architecture Clean Architecture.
Surcharger un service Orkeon
AddOrkeonInfrastructure() enregistre ses services surchargeables via TryAdd*. Pour
remplacer une implémentation par défaut (par exemple IPathValidator ou
IComponentSerializer), il suffit d'enregistrer la vôtre avant l'appel — elle sera
respectée quel que soit l'ordre des appels suivants.
Réserve : tous les services ne sont pas enregistrés en
TryAdd.AddOrkeonApplication()enregistreIAgentExecutionServiceinconditionnellement (AddScoped), etAddOrkeonInfrastructure()fait de même pour quelques services qu'il possède en propre (ILlmProviderFactory,ICrewOrchestrationService, …). Pour ceux-là , enregistrez votre implémentation après l'appel Orkeon — le dernier enregistrement gagne à la résolution.
// Votre implémentation gagne car TryAdd* ne réenregistre pas un service déjà présent.
services.AddSingleton<IPathValidator, MyPathValidator>();
services.AddOrkeonInfrastructure();
L'enregistrement n'a aucun effet de bord sur l'état statique du Domain : le
sérialiseur par défaut (ComponentBase.DefaultSerializer) est posé de façon
non destructive (TrySetDefaultSerializer) et ne sera donc jamais écrasé si l'hôte
en a déjà configuré un.
Table des capacités par surcharge
Deux surcharges existent et produisent des conteneurs aux capacités différentes :
| Capacité / module | AddOrkeonInfrastructure() |
AddOrkeonInfrastructure(IConfiguration) |
|---|---|---|
| Cœur (LLM baseline, mémoire in-memory, sécurité, sérialisation, outils) | ✅ | ✅ |
| Télémétrie OpenTelemetry | ❌ | ✅ (section Telemetry) |
| MCP | ❌ | ✅ |
| VectorSearch | ❌ | ✅ |
| Store de connaissances (stub in-memory, avertit au premier usage) | âś… | âś… |
Système de fichiers virtuel (IFileSystemService) |
❌ (explicite : AddOrkeonFileSystem(configuration)) |
❌ (idem) |
| Sous-système RAG | ❌ (opt-in : AddOrkeonRag + AddOrkeonRagTools) |
❌ (même opt-in) |
| Persistance durable de l'état d'exécution | ❌ | ✅ uniquement si Orkeon:ExecutionState:Persistence existe (Enabled=true + un IStateStore) |
| ChromaDB (vector store) | ❌ | ✅ uniquement si la section Orkeon:ChromaDb existe |
| Pinecone (vector store) | ❌ | ✅ uniquement si la section Orkeon:Pinecone existe |
La surcharge sans
IConfigurationne câble pas les modules d'interopérabilité (MCP, VectorSearch) ni les vector stores externes. UtilisezAddOrkeonInfrastructure(configuration)dès que ces capacités sont requises. ChromaDB et Pinecone ne s'activent que si leur section de configuration respective est présente. Le sous-système RAG n'est câblé par aucune des deux surcharges — c'est toujours la paire expliciteAddOrkeonRag(configuration)+AddOrkeonRagTools().
Sous-systèmes optionnels : A2A, monitoring backend, MultiModal, NIST, DLP, rate-limiting d'outils, rotation de clés, benchmarking, hooks de kickoff — et de même le sous-système RAG (
AddOrkeonRag+AddOrkeonRagTools), RaggableTree (AddRaggableTree), le système de plugins (AddOrkeonPlugins) et la permission gate (AddOrkeonPermissionGate) — ne sont enregistrés par aucune des deux surcharges : chacun s'active explicitement via son extensionAddOrkeonXxx(). MCP, lui, vient avec la surchargeIConfiguration(ouAddOrkeonMcp(configuration)seul) — et l'hôte partagé des runners l'ajoute de lui-même dès queMCP:Serversdéclare un serveur — et le store de checkpointing in-memory est enregistré par les deux surcharges — seule sa variante durable est opt-in. Catalogue complet : Sous-systèmes opt-in.
Exécuter une Crew
Approche 1 : À partir d'un fichier YAML
// Récupérer les services depuis l'hôte
var crewFactory = host.Services.GetRequiredService<ICrewFactory>();
var orchestrator = host.Services.GetRequiredService<ICrewOrchestrationService>();
// Créer la Crew depuis le fichier YAML — un chemin VIRTUEL, lu via le montage /config
// (CreateFromDirectoryAsync prend de la même façon un répertoire de crew multi-fichiers)
var crew = await crewFactory.CreateFromFileAsync("/config/sales-report-crew.yaml");
// Préparer l'entrée
var input = CrewInput.Empty("Process last week's sales data");
// Exécuter la Crew de manière synchrone (la factory a déjà rangé la crew, ses agents et
// ses tâches dans les repositories que lit l'orchestrateur)
var output = await orchestrator.KickoffAsync(crew.Id, input);
// KickoffAsync signale un échec dans la sortie au lieu de lever une exception
if (!output.Succeeded)
Console.Error.WriteLine($"Échec de l'exécution : {output.Error}");
// Afficher les résultats
Console.WriteLine("=== Résultat Final ===");
Console.WriteLine(output.FinalOutput);
Console.WriteLine("\n=== Résultats par Task ===");
foreach (var taskOutput in output.TaskOutputs)
{
Console.WriteLine($"[{taskOutput.TaskId}] {taskOutput.Content[..Math.Min(100, taskOutput.Content.Length)]}...");
}
Console.WriteLine($"\nDurée totale : {output.Duration.TotalSeconds:F2}s");
Approche 2 : À partir du Fluent Builder
// Récupérer les repositories et l'orchestrator
var agentRepository = host.Services.GetRequiredService<IAgentRepository>();
var taskRepository = host.Services.GetRequiredService<ITaskRepository>();
var crewRepository = host.Services.GetRequiredService<ICrewRepository>();
var orchestrator = host.Services.GetRequiredService<ICrewOrchestrationService>();
// (Après avoir créé analyst, writer, analyzeTask, reportTask, crew avec builders)
// Persister les entités dans les repositories
await agentRepository.AddAsync(analyst);
await agentRepository.AddAsync(writer);
await taskRepository.AddAsync(analyzeTask);
await taskRepository.AddAsync(reportTask);
await crewRepository.AddAsync(crew);
// Exécuter la Crew
var variables = new Dictionary<string, object>
{
["start_date"] = "2024-10-01",
["end_date"] = "2024-12-31"
};
var input = new CrewInput(
"Generate sales report for Q4 2024",
variables);
var output = await orchestrator.KickoffAsync(crew.Id, input);
Console.WriteLine(output.FinalOutput);
Types d'entrée/sortie
L'exécution d'une Crew utilise les types suivants :
CrewInput (Orkeon.Application.Interfaces.Services) :
public record CrewInput(
string? InitialContext, // Contexte initial textuel
IReadOnlyDictionary<string, object> Variables); // Variables d'exécution
// Helpers :
// CrewInput.Empty(initialContext)
// CrewInput.WithStringVariables(initialContext, variables)
Variables est un simple dictionnaire en lecture seule. La couche Domain définit aussi des records CrewInput/CrewOutput plus riches (Orkeon.Domain.Crew, avec CrewVariables typé) utilisés en interne par l'exécution des Crews.
CrewOutput (Orkeon.Application.Interfaces.Services) :
public record CrewOutput(
string FinalOutput, // Résultat final textuel
IReadOnlyList<TaskOutput> TaskOutputs, // Résultats par tâche
TimeSpan Duration, // Durée d'exécution
TokenUsage? TokensUsed) // Consommation de tokens (si disponible)
{
public bool Succeeded { get; init; } = true; // false quand l'exécution a échoué
public string? Error { get; init; } // l'échec, quand Succeeded vaut false
public string? ExecutionId { get; init; } // l'id du run, par lequel un run en échec reprend
public PendingInputRequest? PendingInput { get; init; } // posé quand le run s'est arrêté sur une question
}
TaskOutput (Orkeon.Application.Execution) :
public record TaskOutput(
string TaskId,
string? AgentId,
string Content, // Sortie de la tâche
DateTime CompletedAt,
bool Success,
TimeSpan ExecutionTime,
IReadOnlyList<ToolUsage>? ToolsUsed = null)
{
public string? DeliverablePath { get; init; } // le fichier livrable de la tâche, quand on sait qu'il existe
}
Modes d'exécution alternatifs
Orkeon prend en charge plusieurs modes d'exécution via ICrewOrchestrationService :
Mode itératif (par lot) :
// Exécuter la Crew pour chaque élément d'une collection, l'un après l'autre
var inputs = new List<CrewInput>
{
CrewInput.Empty("Process sales data for region 1"),
CrewInput.Empty("Process sales data for region 2"),
CrewInput.Empty("Process sales data for region 3")
};
var batchOutput = await orchestrator.KickoffForEachAsync(crew.Id, inputs);
// batchOutput est de type BatchOutput contenant les résultats individuels, dans l'ordre des entrées
Chaque entrée est un run complet de la crew — démarré, terminé, ses événements dispatchés — et le
suivant commence quand le précédent est rendu, comme le kickoff_for_each de CrewAI.
Mode streaming :
using Orkeon.Constants.Protocol; // RunEventKinds
// Exécuter la Crew et recevoir ce qui se passe au fil du run, via IAsyncEnumerable
CrewOutput? output = null;
await foreach (var e in orchestrator.KickoffStreamingAsync(crew.Id, input))
{
switch (e.Kind)
{
case RunEventKinds.TaskStarted: Console.WriteLine($"[{e.AgentRole}] tâche {e.TaskId} démarrée"); break;
case RunEventKinds.ToolCalled: Console.WriteLine($" -> {e.ToolName}"); break;
case RunEventKinds.ToolReturned: Console.WriteLine($" <- {e.ToolName} ({e.Success}, {e.Duration})"); break;
case RunEventKinds.LlmDelta: Console.Write(e.Text); break;
case RunEventKinds.TaskCompleted: Console.WriteLine($"\n[{e.AgentRole}] terminée : {e.Success}, {e.Tokens} jetons"); break;
case RunEventKinds.Error: Console.Error.WriteLine($"[{e.Code}] {e.Message}"); break;
case RunEventKinds.RunFinished: output = e.Output; break; // toujours le dernier événement
}
}
Ce qu'est un run diffusé.
KickoffStreamingAsyncexécute exactement ce qu'exécuteKickoffAsync— les tâches, les agents et l'ordre de la crew, son mode (les six), sa mémoire, sa connaissance et son plan, le cycle de vie de ses tâches et ses événements de domaine — et rend ce qui se passe au fil du run. ChaqueCrewExecutionEventporte unKinddeRunEventKinds, le vocabulaire qu'orkeon run --events jsonlécrit sur le fil (le bus d'événements du run) :task.startedettask.completedpour chaque tâche (avec son id et le rôle de son agent ;task.completedposeDeliverableMissingquand la tâche a réussi sans écrire son livrabletool_call, etEndedOnIterationCapquand la tâche a répondu au tour sans outil qui suit son plafond d'itérations),tool.calledettool.returnedpour chaque appel d'outil (le nom de l'outil, jamais ses arguments),llm.deltapour le texte du modèle tel qu'il arrive, et — toujours en dernier —run.finished, dont l'Outputest leCrewOutputqueKickoffAsyncaurait rendu. Un run en échec le dit d'abord : unerrordont leCodevautcrew_failedoucrew_cancelledet dont leMessageest la raison du run. Les événements d'une tâche arrivent dans l'ordre ; ceux de tâches qui tournent en même temps (Parallel, Consensual,asyncExecution) s'entrelacent. Les deltas de texte viennent des hôtes qui donnent à la crew unIChatClient(AddOrkeonLlmProvideren enregistre un) et sont le texte du modèle tel qu'il est arrivé — un tour que le run écarte ensuite (un essai repris, une révision rejetée, un bulletin de vote) a été diffusé quand même ; la sortie qui compte est celle derun.finished. Une délégation ou un bulletin tourne sur une tâche à lui, et ses événements portent l'id de cette tâche. Quitter le flux annule le run : unbreak, ou le jeton passé à l'énumération, l'annule, et l'itérateur attend sa fin — la crew échoue par annulation, sa tâche en cours est annulée, et ses événements sont dispatchés.
Mode asynchrone non-bloquant (fire-and-forget) :
// Démarrer l'exécution sans attendre la complétion
var executionId = await orchestrator.KickoffNoWaitAsync(crew.Id, input);
Console.WriteLine($"Exécution démarrée avec ID : {executionId}");
// Vérifier le statut ultérieurement
var status = await orchestrator.GetExecutionStatusAsync(executionId);
Console.WriteLine($"Statut : {status.State}");