π«π· 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()registersIAgentExecutionServiceunconditionally (AddScoped), andAddOrkeonInfrastructure()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
IConfigurationdoes not wire the interoperability modules (MCP, VectorSearch) nor the external vector stores. UseAddOrkeonInfrastructure(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 explicitAddOrkeonRag(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 itsAddOrkeonXxx()extension. MCP, by contrast, comes with theIConfigurationoverload (or standaloneAddOrkeonMcp(configuration)) β and the shared runner host adds it on its own whenMCP:Serversdeclares 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.
KickoffStreamingAsyncruns exactly whatKickoffAsyncruns β 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. EachCrewExecutionEventcarries aKindfromRunEventKinds, the vocabularyorkeon run --events jsonlwrites on the wire (the run event bus):task.startedandtask.completedfor each task (with its id and agent role;task.completedsetsDeliverableMissingwhen the task succeeded without writing itstool_calldeliverable, andEndedOnIterationCapwhen the task answered on the tool-free turn after its iteration cap),tool.calledandtool.returnedfor each tool call (the tool's name, never its arguments),llm.deltafor the model's text as it arrives, and β always last βrun.finished, whoseOutputis theCrewOutputKickoffAsyncwould have returned. A failed run says so first: anerrorwhoseCodeiscrew_failedorcrew_cancelledand whoseMessageis 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 anIChatClient(AddOrkeonLlmProviderregisters 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 isrun.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: abreak, 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}");