Table of Contents

πŸ‡«πŸ‡· Version franΓ§aise

Bootstrap and Execution

See also: Overview Β· YAML configuration Β· Back to the index

Getting the packages

Before any of the code below compiles, add the two NuGet packages it uses. The framework itself ships as a single package, Orkeon; the built-in tool suites wired below (AddOrkeonFileSystemTools, AddOrkeonDataTools, AddOrkeonWebTools, AddOrkeonCodeTools, AddOrkeonEmailTools; the package carries other suites too, such as AddOrkeonDriveTools) live in a second one, Orkeon.Tools:

dotnet add package Orkeon
dotnet add package Orkeon.Tools

Both commands write the matching <PackageReference> entries into your .csproj, so an equivalent hand-edit works just as well.

Orkeon carries the core closure in one package β€” Domain, Application, Infrastructure, the RAG and RaggableTree (Orkeon.Analysis) engines, Orkeon.Tools.Abstractions and four Orkeon.Constants.* satellites; there is no separate Orkeon.Domain / Orkeon.Application / Orkeon.Infrastructure package. The plugin loader (Orkeon.Plugins, IOrkeonPlugin) is in it. The runner host (Orkeon.Hosting, RunnerHost) and the scripting DSL (Orkeon.Scripting) are not: they ship in the opt-in Orkeon.Scripting package and in the orkeon CLI β€” which is why the host below is wired by hand. The opt-ins Orkeon.Rag.Onnx, Orkeon.Tools.Embeddings.Local, Orkeon.Interop.AgentFramework and Orkeon.Hosting.Aspire are added the same way when you need them. The full lineup is the publication matrix.

Starting from a template

dotnet new install Orkeon.Templates adds three templates, each a project that compiles against the packages of the same version, written out in its .csproj:

Command Generates
dotnet new orkeon-host -n MyHost A .NET generic host that runs crew.ork.ts in its own process (ICrewScriptRunner, from Orkeon.Scripting), configured from appsettings.json like the orkeon-host daemon
dotnet new orkeon-plugin -n MyPlugin An IOrkeonPlugin, one tool and the plugin.json that declares it (the loader refuses a tool the manifest does not list)
dotnet new orkeon-tool -n MyTools A class library with one ToolBase<TRequest, TResponse> tool, as in the new-tool pattern

orkeon init is a different job: it writes the settings file, never a project. The host template needs esbuild on the machine to compile crew.ork.ts, as orkeon run does.

Bootstrap and dependency injection

Integrating Orkeon into a .NET application is done through dependency injection at startup. Here is a complete example in Program.cs, on the .NET generic host (the Microsoft.Extensions.Hosting package β€” a dotnet new worker project already references it):

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. The model: AddOrkeonInfrastructure() registers none of its own, and a container
        //    without one fails at its first LLM resolution. Here: a local Ollama model.
        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. Application layer (CQRS, orchestration, services)
        services.AddOrkeonApplication();

        // 2. Infrastructure layer (LLM plumbing, memory, security, YAML)
        services.AddOrkeonInfrastructure();

        // 3. The virtual file system β€” mounts read from Orkeon:FileSystem:Mounts. Required:
        //    the YAML loader, the file tools and the deliverables all go through it.
        services.AddOrkeonFileSystem(context.Configuration);

        // 4. Tool suites
        // FileSystem: FileRead, FileWrite, EditFile, DirectoryRead, DirectorySearch, Glob, Grep, CountPattern
        services.AddOrkeonFileSystemTools();

        // Data: CSV, PDF, JSON, XML, DOCX, XLSX, SQL queries, MongoDB queries, etc.
        services.AddOrkeonDataTools();

        // Web: WebScrape, ScrapeElement, HttpApi, GitHub, ImageGeneration, Firefox
        // (WebSearch/BraveSearch/Slack/CacheSearch have their own opt-in extensions)
        services.AddOrkeonWebTools();

        // Code: ShellCommand (SecureCodeInterpreter is wired by AddOrkeonInfrastructure's sandbox)
        services.AddOrkeonCodeTools();

        // E-mail: the 13 email_* tools, EmailParser included, over the accounts declared under
        // Orkeon:Tools:Email (see docs/guides/email.md)
        services.AddOrkeonEmailTools(context.Configuration);
    })
    .Build();

// 5. Nothing to feed: the tool registry AddOrkeonInfrastructure registered reads every
//    IBaseTool above, so the names a YAML crew lists under `tools:` resolve.

// A long-lived host: await host.RunAsync(). A one-shot program runs a crew right
// away β€” see "Running a Crew" below.

The mounts come from appsettings.json (Docker-style <physical>:<virtual>:<rights>, rights ro, rw or rwnd; the physical directory must exist):

{
  "Orkeon": {
    "FileSystem": {
      "Mounts": [ "./config:/config:ro", "./out:/output:rw" ]
    }
  }
}

Any of the 16 providers is registered the same way: construct it from an LlmConfig, or let ILlmProviderFactory.Create(config) pick it from the base URL, the model name or the key. AddOrkeonLlmProvider puts one instance behind ILlmProvider, IBasicLlmProvider and IChatClient, metered like every provider the factory builds. A provider constructed directly sends an agent's tools natively, as the factory's does: the model calls a tool rather than writing the call as text.

The orkeon CLI does all of this in RunnerHost (Llm section, mounts, a registry fed from DI) and registers a few more suites a host adds the same way when its crews use them: AddOrkeonAbstractionTools() (list_mounts), AddOrkeonSessionTools(), AddOrkeonInMemoryEventHub() + AddOrkeonEventHubTools(), AddRaggableTree() + AddRaggableTreeTools(), and the RAG pair AddOrkeonRag(configuration) + AddOrkeonRagTools() (the CLI adds AddOrkeonOnnxReranker() on top).

Each AddOrkeon*() call automatically registers:

  • The service interfaces (ports)
  • The implementations (adapters)
  • The transitive dependencies (factories, converters, validators)
  • The tools available in the suite

This approach guarantees consistent, testable dependency injection in line with Clean Architecture.

Overriding an Orkeon service

AddOrkeonInfrastructure() registers its overridable services via TryAdd*. To replace a default implementation (for example IPathValidator or IComponentSerializer), simply register yours before the call β€” it will be honored regardless of the order of subsequent calls.

Caveat: not every service is TryAdd-registered. AddOrkeonApplication() registers IAgentExecutionService unconditionally (AddScoped), and AddOrkeonInfrastructure() does the same for a few services it owns outright (ILlmProviderFactory, ICrewOrchestrationService, …). For those, register your implementation after the Orkeon call β€” the last registration wins at resolution time.

// Your implementation wins because TryAdd* does not re-register an already present service.
services.AddSingleton<IPathValidator, MyPathValidator>();
services.AddOrkeonInfrastructure();

Registration has no side effect on the Domain's static state: the default serializer (ComponentBase.DefaultSerializer) is set non-destructively (TrySetDefaultSerializer) and will therefore never be overwritten if the host has already configured one.

Capability table per overload

Two overloads exist and produce containers with different capabilities:

Capability / module AddOrkeonInfrastructure() AddOrkeonInfrastructure(IConfiguration)
Core (baseline LLM, in-memory memory, security, serialization, tools) βœ… βœ…
OpenTelemetry telemetry ❌ βœ… (Telemetry section)
MCP ❌ βœ…
VectorSearch ❌ βœ…
Knowledge store (in-memory stub, warns on first use) βœ… βœ…
Virtual file system (IFileSystemService) ❌ (explicit: AddOrkeonFileSystem(configuration)) ❌ (same)
RAG subsystem ❌ (opt-in: AddOrkeonRag + AddOrkeonRagTools) ❌ (same opt-in)
Durable execution-state persistence ❌ βœ… only if Orkeon:ExecutionState:Persistence exists (Enabled=true + an IStateStore)
ChromaDB (vector store) ❌ βœ… only if the Orkeon:ChromaDb section exists
Pinecone (vector store) ❌ βœ… only if the Orkeon:Pinecone section exists

The overload without IConfiguration does not wire the interoperability modules (MCP, VectorSearch) nor the external vector stores. Use AddOrkeonInfrastructure(configuration) as soon as these capabilities are required. ChromaDB and Pinecone are only activated if their respective configuration section is present. The RAG subsystem is wired by neither overload β€” it is always the explicit AddOrkeonRag(configuration) + AddOrkeonRagTools() pair.

Opt-in subsystems: A2A, monitoring backend, MultiModal, NIST, DLP, tool rate-limiting, key rotation, benchmarking, kickoff hooks β€” and likewise the RAG subsystem (AddOrkeonRag + AddOrkeonRagTools), RaggableTree (AddRaggableTree), the plugin system (AddOrkeonPlugins) and the permission gate (AddOrkeonPermissionGate) β€” are registered by neither of the two overloads: each is enabled explicitly via its AddOrkeonXxx() extension. MCP, by contrast, comes with the IConfiguration overload (or standalone AddOrkeonMcp(configuration)) β€” and the shared runner host adds it on its own when MCP:Servers declares a server β€” and the in-memory checkpointing store is registered by both overloads β€” only its durable variant is opt-in. Full catalog: Opt-in subsystems.

Running a Crew

Approach 1: From a YAML file

// Retrieve the services from the host
var crewFactory = host.Services.GetRequiredService<ICrewFactory>();
var orchestrator = host.Services.GetRequiredService<ICrewOrchestrationService>();

// Create the Crew from the YAML file β€” a VIRTUAL path, read through the /config mount
// (CreateFromDirectoryAsync takes a multi-file crew directory the same way)
var crew = await crewFactory.CreateFromFileAsync("/config/sales-report-crew.yaml");

// Prepare the input
var input = CrewInput.Empty("Process last week's sales data");

// Run the Crew synchronously (the factory already stored the crew, its agents and tasks
// in the repositories the orchestrator reads)
var output = await orchestrator.KickoffAsync(crew.Id, input);

// KickoffAsync reports a failed run in the output rather than throwing
if (!output.Succeeded)
    Console.Error.WriteLine($"Run failed: {output.Error}");

// Print the results
Console.WriteLine("=== Final Result ===");
Console.WriteLine(output.FinalOutput);

Console.WriteLine("\n=== Results per Task ===");
foreach (var taskOutput in output.TaskOutputs)
{
    Console.WriteLine($"[{taskOutput.TaskId}] {taskOutput.Content[..Math.Min(100, taskOutput.Content.Length)]}...");
}

Console.WriteLine($"\nTotal duration: {output.Duration.TotalSeconds:F2}s");

Approach 2: From the Fluent Builder

// Retrieve the repositories and the 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>();

// (After creating analyst, writer, analyzeTask, reportTask, crew with builders)
// Persist the entities in the repositories
await agentRepository.AddAsync(analyst);
await agentRepository.AddAsync(writer);
await taskRepository.AddAsync(analyzeTask);
await taskRepository.AddAsync(reportTask);
await crewRepository.AddAsync(crew);

// Run the 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);

Input/output types

Running a Crew uses the following types:

CrewInput (Orkeon.Application.Interfaces.Services):

public record CrewInput(
    string? InitialContext,                          // Initial textual context
    IReadOnlyDictionary<string, object> Variables);  // Execution variables

// Helpers:
//   CrewInput.Empty(initialContext)
//   CrewInput.WithStringVariables(initialContext, variables)

Variables is a plain read-only dictionary. The Domain layer also defines richer CrewInput/CrewOutput records (Orkeon.Domain.Crew, with typed CrewVariables) used internally by crew execution.

CrewOutput (Orkeon.Application.Interfaces.Services):

public record CrewOutput(
    string FinalOutput,                       // Final textual result
    IReadOnlyList<TaskOutput> TaskOutputs,    // Results per task
    TimeSpan Duration,                        // Execution duration
    TokenUsage? TokensUsed)                   // Token consumption (when available)
{
    public bool Succeeded { get; init; } = true;  // false when the run failed
    public string? Error { get; init; }           // the failure, when Succeeded is false
    public string? ExecutionId { get; init; }     // the run's id, which a failed run is resumed by
    public PendingInputRequest? PendingInput { get; init; } // set when the run stopped on a question
}

TaskOutput (Orkeon.Application.Execution):

public record TaskOutput(
    string TaskId,
    string? AgentId,
    string Content,                                  // Task output
    DateTime CompletedAt,
    bool Success,
    TimeSpan ExecutionTime,
    IReadOnlyList<ToolUsage>? ToolsUsed = null)
{
    public string? DeliverablePath { get; init; }  // the task's deliverable file, when it is known to exist
}

Alternative execution modes

Orkeon supports several execution modes via ICrewOrchestrationService:

Iterative mode (batch):

// Run the Crew for each element of a collection, one after the other
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 is a BatchOutput containing the individual results, in the order of the inputs

Each input is a full run of the crew β€” started, ended, its events dispatched β€” and the next one starts once the previous one has returned, like CrewAI's kickoff_for_each.

Streaming mode:

using Orkeon.Constants.Protocol; // RunEventKinds

// Run the Crew and receive what happens as it goes, 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}] started task {e.TaskId}"); 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}] done: {e.Success}, {e.Tokens} tokens"); break;
        case RunEventKinds.Error:         Console.Error.WriteLine($"[{e.Code}] {e.Message}"); break;
        case RunEventKinds.RunFinished:   output = e.Output; break; // always the last event
    }
}

What a streamed run is. KickoffStreamingAsync runs exactly what KickoffAsync runs β€” the crew's tasks, agents and order, its mode (all six), memory, knowledge and plan, the lifecycle of its tasks and its domain events β€” and yields what happens as it goes. Each CrewExecutionEvent carries a Kind from RunEventKinds, the vocabulary orkeon run --events jsonl writes on the wire (the run event bus): task.started and task.completed for each task (with its id and agent role; task.completed sets DeliverableMissing when the task succeeded without writing its tool_call deliverable, and EndedOnIterationCap when the task answered on the tool-free turn after its iteration cap), tool.called and tool.returned for each tool call (the tool's name, never its arguments), llm.delta for the model's text as it arrives, and β€” always last β€” run.finished, whose Output is the CrewOutput KickoffAsync would have returned. A failed run says so first: an error whose Code is crew_failed or crew_cancelled and whose Message is the run's reason. A task's events come in order; the events of tasks that run at once (Parallel, Consensual, asyncExecution) interleave. The text deltas come from hosts that give the crew an IChatClient (AddOrkeonLlmProvider registers one) and are the model's text as it arrived β€” a turn the run then discards (a retried attempt, a rejected revision, a ballot) was streamed all the same; the output that counts is run.finished's. A delegation or a ballot runs on a task of its own, and its events carry that task's id. Leaving the stream cancels the run: a break, or the token passed to the enumeration, cancels it, and the iterator waits for its end β€” the crew fails by cancellation, its running task is cancelled, and its events are dispatched.

Non-blocking asynchronous mode (fire-and-forget):

// Start the execution without awaiting completion
var executionId = await orchestrator.KickoffNoWaitAsync(crew.Id, input);

Console.WriteLine($"Execution started with ID: {executionId}");

// Check the status later
var status = await orchestrator.GetExecutionStatusAsync(executionId);
Console.WriteLine($"Status: {status.State}");