Table of Contents

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

Orkeon Overview

See also: Bootstrap and execution Β· YAML and Builders Β· Back to the index

What is Orkeon?

Orkeon is an open-source framework for building and orchestrating teams of AI agents in .NET. It lets you define specialized agents, assign them tasks, equip them with tools and have them collaborate within a Crew (team) orchestrated according to different execution strategies.

Two words come back throughout the documentation:

  • a team (a crew in the code) is a set of agents, each with a role, working together on a mission;
  • the runtime is the engine that executes the team and enforces the rules. There is only one, whether the team is written in YAML, in TypeScript (.ork.ts) or in C#.

Two principles follow from it. A boundary declared, then enforced: every file, endpoint and budget an agent may use is declared, and the runtime applies it whatever the model decides. No rewrite between trial and application: the team you tuned is the one you integrate; only the configuration changes (the model, the mounted folders, the secrets). The README gives the full presentation, with what Orkeon guarantees and what it does not.

The framework follows a Clean Architecture / DDD architecture and targets .NET 10.

Architecture diagram

graph TB
    subgraph Domain["Orkeon.Domain β€” Domain layer"]
        Agent["Agent<br/>(AggregateRoot&lt;AgentId&gt;)"]
        CrewTask["CrewTask<br/>(AggregateRoot&lt;TaskId&gt;)"]
        Crew["Crew<br/>(AggregateRoot&lt;CrewId&gt;)"]
        IBaseTool["IBaseTool<br/>(Interface)"]
        ILlm["ILlmProvider<br/>(Interface)"]
        IMem["IMemoryProvider<br/>(Interface)"]
        DomainEvents["Domain Events"]

        Crew -->|"contains"| Agent
        Crew -->|"contains"| CrewTask
        Agent -->|"uses"| IBaseTool
        Agent -->|"uses"| ILlm
        CrewTask -->|"assigned to"| Agent
        Agent -->|"emits"| DomainEvents
        Crew -->|"emits"| DomainEvents
    end

    subgraph Application["Orkeon.Application β€” Application layer"]
        Orchestrator["ExecutionOrchestrator"]
        CQRS["Commands / Queries<br/>(CQRS)"]
        CallbackOrch["CallbackOrchestrator"]
        MemService["MemoryService"]
        AgentExec["AgentExecutionService"]

        Orchestrator --> AgentExec
        Orchestrator --> CallbackOrch
        AgentExec --> MemService
    end

    subgraph Infrastructure["Orkeon.Infrastructure β€” Infrastructure layer"]
        SeqOrch["SequentialCrewOrchestrator"]
        LlmProviders["LLM Providers<br/>(OpenAI, Anthropic, Grok,<br/>Ollama, Azure, DeepSeek...)"]
        MemProviders["Memory Providers<br/>(InMemory, Redis, SQLite,<br/>ChromaDB, Pinecone, LanceDB)"]
        ToolImpl["Tool Implementations"]
        Config["Configuration Loaders<br/>(YAML, JSON, Env)"]
        DI["DI Registration<br/>(ServiceCollectionExtensions)"]

        SeqOrch --> Orchestrator
        LlmProviders -.->|"implements"| ILlm
        MemProviders -.->|"implements"| IMem
        ToolImpl -.->|"implements"| IBaseTool
    end

    subgraph Tools["Orkeon.Tools.* β€” Tool packages"]
        ToolsFS["Tools.FileSystem<br/>(FileRead, FileWrite,<br/>DirectoryRead...)"]
        ToolsData["Tools.Data<br/>(CSV, PDF, JSON,<br/>DOCX, SQL, MongoDB...)"]
        ToolsWeb["Tools.Web<br/>(WebSearch, WebScrape,<br/>HttpApi, GitHub...)"]
        ToolsCode["Tools.Code<br/>(ShellCommand)"]
    end

    Tools -.->|"implements"| IBaseTool

    style Domain fill:#e8f5e9,stroke:#2e7d32
    style Application fill:#e3f2fd,stroke:#1565c0
    style Infrastructure fill:#fff3e0,stroke:#ef6c00
    style Tools fill:#f3e5f5,stroke:#7b1fa2

Core concepts

Agent (Orkeon.Domain.Agent.Agent)

An Agent is the intelligent unit of work of the framework. It is a DDD Aggregate Root identified by an AgentId. An agent is defined by two mandatory elements, a role (AgentRole) and a goal (AgentGoal), plus an optional backstory (AgentBackstory) which contextualizes its personality for the LLM.

Each agent has a list of tools (IReadOnlyList<IBaseTool> Tools), a status (the AgentStatus value object: Created, Idle, Busy, Unavailable, Deactivated or Error), execution constraints (MaxIterations, MaxRpm, MaxExecutionTime), and can be configured to delegate tasks (AllowDelegation).

There is only one Agent class β€” the manager behavior in hierarchical mode is handled by the IManagerAgent interface and its LlmBasedManager implementation.

var agent = new AgentBuilder()
    .Role("Data Analyst")
    .Goal("Analyze sales data and produce insights")
    .Backstory("Senior analyst with 10 years of retail experience")
    .WithTool(csvReaderTool)
    .WithTool(jsonTool)
    .MaxIterations(15)
    .Verbose()
    .Build();

Task (Orkeon.Domain.Task.CrewTask)

A Task (or CrewTask) represents a unit of work assignable to an agent. It is defined by a description (TaskDescription) and an expected output (ExpectedOutput). Tasks support inter-task dependencies (Dependencies), asynchronous execution (AsyncExecution β€” a sequential crew runs such a task alongside the tasks after it, see Asynchronous tasks), JSON schema validation (OutputJson), and requesting human intervention (HumanInput).

var task = new CrewTaskBuilder()
    .Description("Analyze Q4 sales CSV and identify top 3 trends")
    .ExpectedOutput("Markdown report with 3 trends and supporting data")
    .Priority(TaskPriority.High)
    .AssignTo(analyst)
    .Build();

Tool (Orkeon.Domain.Tools.IBaseTool)

A Tool is a concrete capability made available to an agent. The IBaseTool interface exposes a Name, a Description, a Schema (JSON schema of the parameters), and two execution methods: CallAsync (structured protocol via ToolCallRequest/ToolCallResponse) and ExecuteAsync (legacy string mode).

Tools are organized into families β€” Orkeon.Tools.FileSystem, .Data, .Web, .Code, .Email, .Drive, .EventHub, .Rag, .Analysis β€” shipped together in the Orkeon.Tools NuGet package; each family has its own registration extension β€” AddOrkeonFileSystemTools(), …, AddOrkeonDriveTools(configuration), …, AddRaggableTreeTools() (see Bootstrap) and the full list is the tool inventory. To give agents a mailbox (the .Email family: Gmail, Outlook.com, your own IMAP/POP3/SMTP server), start with Give your agents a mailbox.

Crew (Orkeon.Domain.Crew.Crew)

A Crew is a team of agents organized around a common goal (CrewGoal). It defines the execution strategy via ProcessType and coordinates the execution of the tasks by the agents.

var crew = new CrewBuilder()
    .Goal("Produce weekly sales report")
    .Sequential()
    .WithAgent(analyst)
    .WithAgent(writer)
    .WithTask(analysisTask)
    .WithTask(reportTask)
    .Planning(true)
    .EnableMemory(true)
    .Build();

.Planning(true) β€” planning: true in YAML, .planning() in .ork.ts β€” has a planner write a step-by-step plan for each task before the first one: one call on the host's default LLM profile (the Llm section), or on the provider .WithPlanningLlm(provider) names. Each task reads its own plan in its prompt, in every mode; the plan changes neither the order of the tasks nor who runs them, and a plan that cannot be read leaves the crew without one, with a warning β€” see Process types.

.EnableMemory(true) β€” memory: true β€” makes the crew remember: each task's result is stored, and the closest ones are recalled into the prompt of the next tasks, run after run. Memories are embedded by the host's embedding provider, which the crew needs from its kickoff (AddOrkeonLocalEmbeddings() or the Orkeon:Embeddings section) β€” see Memory system.

Two definition approaches: YAML or Fluent Builder

Crews and their agents can be defined in two ways: either via a YAML file, or via the Fluent Builder API in C#. Both approaches produce identical results. A third surface, TypeScript (.ork.ts), describes the same crew with the scripting DSL and runs through the same orkeon run β€” see Write a crew in TypeScript.

Approach 1: Definition via YAML

Here is a complete example of a YAML Crew that generates a sales report:

name: "sales-report-crew"
goal: "Produce weekly sales analysis report"
process: "sequential"
verbose: true
memory: true
planning: true

agents:
  data_analyst:
    role: "Sales Data Analyst"
    goal: "Extract and analyze sales metrics from the database"
    backstory: |
      Senior data analyst with 10 years of retail experience.
      Expert in SQL and statistical analysis.
    tools:
      - "relational_database_query"
      - "csv_reader"
    maxIter: 10
    maxRpm: 15

  report_writer:
    role: "Report Writer"
    goal: "Transform analysis results into a clear executive report"
    backstory: |
      Business communications specialist who turns data insights
      into actionable executive summaries.
    tools:
      - "file_write"
    maxIter: 5

tasks:
  analyze_sales:
    description: |
      Query the sales database for the last 7 days.
      Calculate: total revenue, top 5 products by units sold,
      week-over-week growth rate. Return structured JSON.
    expectedOutput: "JSON object with revenue, top_products array, and growth_rate"
    agent: "data_analyst"

  write_report:
    description: |
      Using the sales analysis data, write an executive report
      in Markdown format. Include an executive summary,
      key metrics table, and 3 actionable recommendations.
    expectedOutput: "Markdown report saved to /output/weekly-report.md"
    agent: "report_writer"
    dependencies:
      - "analyze_sales"
    deliverable:
      path: "/output/weekly-report.md"   # default source: tool_call β€” the agent writes it, so it needs file_write (without a writer tool, the load warns and `orkeon run --validate` prints WARNING)
      # source: final_message           # or structured_output: the framework writes the file itself

Approach 2: Definition via Fluent Builder

The C# equivalent with the Fluent Builder API:

// Create the agents
var analyst = new AgentBuilder()
    .Role("Sales Data Analyst")
    .Goal("Extract and analyze sales metrics from the database")
    .Backstory("Senior data analyst with 10 years of retail experience. Expert in SQL and statistical analysis.")
    .WithTool(relationalDatabaseQueryTool)
    .WithTool(csvReaderTool)
    .MaxIterations(10)
    .MaxRpm(15)
    .Build();

var writer = new AgentBuilder()
    .Role("Report Writer")
    .Goal("Transform analysis results into a clear executive report")
    .Backstory("Business communications specialist who turns data insights into actionable executive summaries.")
    .WithTool(fileWriteTool)
    .MaxIterations(5)
    .Build();

// Create the tasks
var analyzeTask = new CrewTaskBuilder()
    .Description("Query the sales database for the last 7 days. Calculate: total revenue, top 5 products by units sold, week-over-week growth rate. Return structured JSON.")
    .ExpectedOutput("JSON object with revenue, top_products array, and growth_rate")
    .AssignTo(analyst)
    .Build();

var reportTask = new CrewTaskBuilder()
    .Description("Using the sales analysis data, write an executive report in Markdown format. Include an executive summary, key metrics table, and 3 actionable recommendations.")
    .ExpectedOutput("Markdown report saved to /output/weekly-report.md")
    .AssignTo(writer)
    .DependsOn(analyzeTask)
    .Build();

// Create the Crew
var crew = new CrewBuilder()
    .Goal("Produce weekly sales analysis report")
    .Sequential()
    .WithAgent(analyst)
    .WithAgent(writer)
    .WithTask(analyzeTask)
    .WithTask(reportTask)
    .Planning(true)
    .EnableMemory(true)
    .Verbose(true)
    .Build();

Inter-agent communication

Communication between agents is provided by AsyncAgentCommunicationService (Orkeon.Infrastructure.Communication), which exposes SendMessageAsync, ReceiveMessagesAsync and IsAgentAvailableAsync.

Agents collaborate through delegation: the AskQuestionTool and DelegateWorkTool tools, which an agent with AllowDelegation receives in the Sequential and Graph modes, and the hand-over of a failed task to a peer in the Autonomous mode.

Project structure

Orkeon.sln
β”œβ”€β”€ src/                            # 48 projects, 14 zones
β”‚   β”œβ”€β”€ core/
β”‚   β”‚   β”œβ”€β”€ Orkeon.Domain/          # Entities, value objects, interfaces, events
β”‚   β”‚   β”œβ”€β”€ Orkeon.Application/     # CQRS, services, orchestration, ports
β”‚   β”‚   └── Orkeon.Infrastructure/  # Implementations, LLM providers, memory, DI
β”‚   β”œβ”€β”€ tools/                      # 11 tool packs
β”‚   β”‚   β”œβ”€β”€ Orkeon.Tools.Abstractions/     # Tool base classes
β”‚   β”‚   β”œβ”€β”€ Orkeon.Tools.Analysis/         # RaggableTree agent tools (29)
β”‚   β”‚   β”œβ”€β”€ Orkeon.Tools.Code/             # Code tools (ShellCommand)
β”‚   β”‚   β”œβ”€β”€ Orkeon.Tools.Data/             # Data tools (CSV, PDF, JSON, SQL, MongoDB…)
β”‚   β”‚   β”œβ”€β”€ Orkeon.Tools.Drive/            # Google Drive and OneDrive tools
β”‚   β”‚   β”œβ”€β”€ Orkeon.Tools.Email/            # E-mail tools (IMAP, POP3, SMTP, Microsoft Graph)
β”‚   β”‚   β”œβ”€β”€ Orkeon.Tools.Embeddings.Local/ # On-device embeddings (BGE-micro ONNX)
β”‚   β”‚   β”œβ”€β”€ Orkeon.Tools.EventHub/         # EventHub messaging tools
β”‚   β”‚   β”œβ”€β”€ Orkeon.Tools.FileSystem/       # File tools (Read, Write, Directory…)
β”‚   β”‚   β”œβ”€β”€ Orkeon.Tools.Rag/              # RAG agent tools
β”‚   β”‚   └── Orkeon.Tools.Web/              # Web tools (Search, Scrape, HTTP, GitHub…)
β”‚   β”œβ”€β”€ rag/                        # RAG subsystem (Abstractions, Rag, Onnx, Onnx.Model)
β”‚   β”œβ”€β”€ analysis/                   # RaggableTree engine (Abstractions, Analysis)
β”‚   β”œβ”€β”€ scripting/                  # .ork.ts DSL (Orkeon.Scripting) + the `orkeon` CLI (Orkeon.Scripting.Cli)
β”‚   β”œβ”€β”€ cli/                        # CLI building blocks (Abstractions, Cli, Commands.Scripting, TerminalGui)
β”‚   β”œβ”€β”€ hosting/                    # Orkeon.Hosting (RunnerHost), Orkeon.Host (`orkeon-host` daemon), Orkeon.Hosting.Aspire
β”‚   β”œβ”€β”€ plugins/                    # Orkeon.Plugins (runtime plugin loading)
β”‚   β”œβ”€β”€ interop/                    # Orkeon.Interop.AgentFramework (Microsoft Agent Framework bridge)
β”‚   β”œβ”€β”€ generators/                 # Orkeon.Generators (source generators)
β”‚   β”œβ”€β”€ constants/                  # Satellites of SHARED constants, zero runtime dependency (ADR-009)
β”‚   β”œβ”€β”€ analyzers/                  # Orkeon.Compliance.Vfs (Roslyn analyzer)
β”‚   β”œβ”€β”€ packaging/                  # NuGet packaging projects (Orkeon, Orkeon.Tools, 6 opt-in wrappers and Orkeon.Templates)
β”‚   └── apps/
β”‚       └── Orkeon.ConsoleApp/      # Interactive REPL (`orkeon-repl`)
β”œβ”€β”€ tests/                          # 34 projects (src mirrors + e2e, shared)
β”œβ”€β”€ examples/                       # 104 numbered examples in 9 categories, plus showcases
└── docs/                           # Documentation (EN + docs/fr mirror)