Table of Contents

🇬🇧 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() enregistre IAgentExecutionService inconditionnellement (AddScoped), et AddOrkeonInfrastructure() 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 IConfiguration ne câble pas les modules d'interopérabilité (MCP, VectorSearch) ni les vector stores externes. Utilisez AddOrkeonInfrastructure(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 explicite AddOrkeonRag(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 extension AddOrkeonXxx(). MCP, lui, vient avec la surcharge IConfiguration (ou AddOrkeonMcp(configuration) seul) — et l'hôte partagé des runners l'ajoute de lui-même dès que MCP:Servers dé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é. KickoffStreamingAsync exécute exactement ce qu'exécute KickoffAsync — 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. Chaque CrewExecutionEvent porte un Kind de RunEventKinds, le vocabulaire qu'orkeon run --events jsonl écrit sur le fil (le bus d'événements du run) : task.started et task.completed pour chaque tâche (avec son id et le rôle de son agent ; task.completed pose DeliverableMissing quand la tâche a réussi sans écrire son livrable tool_call, et EndedOnIterationCap quand la tâche a répondu au tour sans outil qui suit son plafond d'itérations), tool.called et tool.returned pour chaque appel d'outil (le nom de l'outil, jamais ses arguments), llm.delta pour le texte du modèle tel qu'il arrive, et — toujours en dernier — run.finished, dont l'Output est le CrewOutput que KickoffAsync aurait rendu. Un run en échec le dit d'abord : un error dont le Code vaut crew_failed ou crew_cancelled et dont le Message est 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 un IChatClient (AddOrkeonLlmProvider en 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 de run.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 : un break, 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}");