π«π· 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<AgentId>)"]
CrewTask["CrewTask<br/>(AggregateRoot<TaskId>)"]
Crew["Crew<br/>(AggregateRoot<CrewId>)"]
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)