π«π· Version franΓ§aise
Orkeon Documentation
Structure
The documentation is organized into 8 thematic sections.
Language policy β every page under
docs/is maintained in English and French in parallel (docs/fr/mirrors the tree path-for-path); a missing mirror fails CI (scripts/check-docs-parity.sh). See CONTRIBUTING.md for the contract.
Online β this tree and the generated API reference are published at https://orkeon.github.io/orkeon/, deployed by
docs.ymlon everyv*tag. The site therefore always documents a tagged version.
Getting started
| File | Description |
|---|---|
| Three ways to run Orkeon | Hub page: from source vs. release binary vs. container β prerequisites, commands, per-OS install channels and a comparison table; installing from source, the REPL included; how to update, to the latest release or to the latest main (dev channel) |
| Run your first example (from source) | End-to-end first run: prerequisites, LLM profile matrix, the full crew command, every runner flag, settings resolution, troubleshooting |
| Overview | Architecture, core concepts (Agent, Task, Tool, Crew), YAML vs Fluent Builder |
| Bootstrap and execution | Packages, DI wiring for an embedding host (model, VFS mounts, tool registry), running a Crew, batch/streaming/fire-and-forget modes |
| YAML, Builders and CrewFactory | Fluent Builders, YAML schema, CrewFactory pipeline, loading modes |
| Default behaviors | The deliberately-minimal DI defaults (knowledge store, LLM cache, memory system, agent selection, embeddings): what each does, the warn-once signal, and the replacement gesture β and the two services with no working default (VFS, model) |
| Forge a team from a need | The Atelier (orkeon forge): need β interview β team β sandboxed try β verdict against your own criteria β promotion, sessions resumable on disk; other options (--read, --reference, --with-settings, forge rename) |
Giving agents a mailbox is one of the most requested features: the tutorial gets one working in minutes, the guide covers every provider and setting.
| File | Description |
|---|---|
| Give your agents a mailbox | Tutorial: a Gmail account, an app password, and an agent that sorts the unread mail into folders and leaves each reply as a draft β nothing is sent |
| E-mail tools | Give agents a mailbox: Gmail (app password or OAuth2), Hotmail/Outlook.com through Microsoft Graph, your own IMAP/POP3/SMTP server; per-account rights, the fail-closed send allow-list, prompt-injection screening, orkeon email login, where the tokens live, troubleshooting |
orkeon email commands |
accounts (what is declared, what is ready), check (connect and list the folders), login / logout for OAuth2 accounts β options and exit codes |
| ADR-012 β the e-mail tool family | Why e-mail lives in Orkeon itself, and the alternatives rejected |
Cloud drives
| File | Description |
|---|---|
| Drive tools | Give agents a Google Drive or a OneDrive: registering the OAuth application, orkeon drive login, rights, the root folder an agent cannot leave, the closed share allow-list, what the token never reaches |
The firefox tool |
Give agents the Firefox of the machine, over WebDriver BiDi: one browser per run, or one the host keeps between runs, the page as a graph of sections, links and controls, node ids for click and type, search by meaning, what the URL policy checks and what never goes through the tool |
orkeon drive commands |
accounts, check (find the root folder and list it), login / logout β options and exit codes |
| ADR-013 β the drive tool family | Why a tool family rather than a VFS mount, and the OAuth layer the two cloud families share |
Architecture
| File | Description |
|---|---|
| LLM providers | 16 providers (OpenAI, Anthropic, Azure, Grok, Ollama, the OpenRouter and Mammouth aggregators, etc.), capabilities and dialect seams, provider resolution, decorators and LLM exchange logging, real-API campaign kit |
| Model providers | The four categories of model providers (generation, embedding, reranking, decision), their contracts and the ModelProviderCatalog |
| Decision models | System One providers (TypeSafe, Liquid, Kev) behind IDecisionModel, one active at a time: typed questions, decision profiles that block, route or escalate an LLM call (cascade, router), the input guard, the decision reranker and system_one_decide |
| Memory system | 5 memory types, 6 providers (InMemory, Redis, SQLite, ChromaDB, Pinecone, LanceDB), cognitive memory |
| Events, CQRS and observability | 23 domain events β the tasks' and agents' as a run goes, the crew's at the end of each kickoff, and by the CQRS commands β, the CQRS pipeline, 2 observation surfaces (ICrewExecutionHook, ICallbackHandler with a step per tool call) |
| EventHub and crew lifecycle | Reference specification for inter-agent and inter-crew messaging (EventHub) and crew sleep/wake β Application ports, the in-memory adapter and its five middleware stages (the shipped hosts wire only the ACL), the agent tools; SQLite persistence and sleep/wake are specified, not built yet |
| The host API and the health probes | orkeon-host's HTTP surface, off by default: /healthz and /readyz (what each checks, systemd, Docker and Kubernetes), POST /runs with idempotency keys, run listing, SSE and NDJSON events with resume, cancel; authentication shared with A2A |
| The service host and the chat gateway | orkeon-host: hosting crews as a daemon (systemd, Windows service, container), per-run isolation, and the Discord gateway with its allow list, thread-is-run routing and stop button |
| The run event bus | orkeon run --events jsonl: the versioned protocol another program reads, the commands it can send back, and the client:// seat it gets at the run's hub |
| Security, resilience and plugins | Defense in depth: the security layers, from tool to audit; Polly policies, checkpointing, plugin system |
| VFS compliance | VFS-only principle (all I/O via IFileSystemService): Orkeon.Compliance.Vfs Roslyn analyzer, 7 diagnostics, exempted scopes, migration exit criteria |
| Console compliance | No System.Console in framework code: the ORKCON001 analyzer, the console adapters and the one sink per executable, IRunnerConsole / ITerminalProbe, the Orkeon.Operator warning channel |
| Plugin system | IOrkeonPlugin contract, VFS discovery, AssemblyLoadContext isolation, opt-in activation AddOrkeonPlugins, β οΈ trust boundary |
| Scripting DSL | TypeScript-syntax DSL (.ork.ts): esbuild transpilation, sandboxed Jint execution, the full Orkeon surface (agents, crews, tools, FSM, graphs, events) via fluent builders |
| TypeScript CLI commands | Interactive REPL commands in *.cmd.ts (defineCommand) loaded at startup without .NET recompilation, with work dispatch to agents |
| MCP client & server | Dual-era Model Context Protocol integration (2026-07-28 stateless + legacy revisions), transports, activation, MCP tools and crews, honest gaps |
| Driving crews from the REPL | The .cmd.ts β crew.ork.ts bridge: *.cmd.ts control plane vs crew.ork.ts engine over the script-host service, ctx.llm.act as an agent loop, the permission gate and the session ports β with a keyless REPL session you can run |
| YAML reference | Single source of the complete YAML schema (crew, agents, tasks, graph) |
| RaggableTree β semantic graph | 6-phase pipeline, 29 tools, 12 languages, incremental reindexing, lazy freshness, hybrid search, context injection, what the hosts actually wire |
| RAG pipeline | The src/rag/ subsystem: ingestion, 7-stage pipeline (transform β retrieve β fuse/MMR β rerank β assemble β generate β groundedness), corrective CRAG graph, web fallback, 5 profiles, measured evaluation |
| ADR β RaggableTree | Decision for a stratified graph via Tree-sitter (5 levels L0βL4 plus the edge layer), rejected alternatives, consequences, 2026-09-30 implementation-status amendment |
| Architecture Decision Records (ADR) | ADR-002 (Tools.Abstractions shared kernel), ADR-003 (Analysis shared kernels), ADR-004 (scripting naming twins β superseded by ADR-007), ADR-005 (heterogeneous Tools.* family), ADR-006 (RAG subsystem src/rag/), ADR-007 (D3: Orkeon.Cli.Commands.Scripting rename), ADR-008 (virtual paths are the only currency agents are paid in), ADR-009 (satellites of shared constants), ADR-010 (Microsoft Agent Framework interop as a separate package, both directions), ADR-011 (the Aspire dashboard is the observability surface; no web front-end), ADR-012 (the e-mail tool family, the second motivated exception to the scope freeze), ADR-013 (the drive tool family), ADR-014 (shell confinement by default), ADR-015 (model provider categories and decision stages), ADR-016 (decision tasks and conditional fan-out), ADR-017 (the transcript display model), ADR-018 (graph engines and the YAML graph: block) |
| ADR-014 β shell confinement by default | Why shell_command is confined per platform by default, off in containers, and runs one shell session per agent run |
| ADR-015 β model provider categories and decision stages | Why model providers come in categories (generation, embedding, reranking, decision), why decision providers (TypeSafe, Liquid, Kev) have their own IDecisionModel port, and why a decision stage judges an LLM call without rewriting it |
| ADR-016 β decision tasks and conditional fan-out | Why a decision task answers without an agent, why a when condition skips a task instead of failing it, and which processes support them |
| ADR-017 β the transcript display model | Why the transcript paints over a text that stays the one source, why only content paints a background, and why scripts never choose a colour |
ADR-018 β graph engines and the YAML graph: block |
Why two graph loops stay, what they share (topology validation, vocabulary, budgets), and the shape and rules of the graph: block |
Orchestration
| File | Description |
|---|---|
| ProcessTypes comparative guide | The 6 strategies side by side: matrix, decision tree, pros/cons, costs |
| FSM β State machine | Generic Domain FSM engine (used by orkeon forge; its circuit-breaker policy bounds Graph and the corrective RAG graph), 4 mechanisms, presets, guards |
| Graph β State graph | The Graph process mode (fixed topology, 3-mechanism circuit breaker) and the LangGraph-style C# StateGraph API: conditional edges, controlled cycles, retry |
| Autonomous β Self-organization | Multi-dimensional budget, manager-assigned tasks, delegation to a peer on failure, host-provided spawn, A2A channel |
Tools
| File | Description |
|---|---|
| Tool inventory | 124 tools by category with their call parameters, YAML resolution (strict/lenient), DI registration, availability per host, identified gaps |
| Creating a new tool | Typed pipeline, FieldSchema/ReturnSchema attributes, composition pattern, registration |
Guides
| File | Description |
|---|---|
| Write a crew in TypeScript | The .ork.ts DSL end to end: the two script shapes and why picking the wrong one drops half of what you wrote (loudly): tasks, agents, tools, the withContext DAG, deliverables, ctx.llm.act, state, editor setup |
| Porting methodology | 5 steps to migrate an application, YAML-first vs Code-first, effort estimation |
| Porting example | Complete e-commerce pipeline: analysis, agent mapping, YAML, C# bootstrap |
| New orchestration blueprint | 8-step template to add a new ProcessType to the framework |
| Multi-modal content (vision) | Real vision: MultiModalContent β LlmMessage β Anthropic blocks / OpenAI parts (14 compatible providers) / Ollama images, VFS loader, opt-in activation |
| Record and replay LLM calls | --llm-record and --llm-replay: freeze the calls of a real run in a JSONL cassette and replay them with no network, the key of a call, redaction, a replay miss, what a cassette does not hold |
| LLM response format | Constrained output at the provider boundary (json_object / json_schema), capability-driven translation per provider, cascade crew β agent β task β script β call |
| SonarQube Quality Gate | Local SonarQube analysis with the "Orkeon Transitional" gate: transitional thresholds, hardening trajectory, automatic provisioning by the scripts |
| Local models | Run everything on your own machine: Docker Model Runner (pull/configure/inspect, 128K contexts), Ollama, embedded local-llm image variant, model switching, troubleshooting |
| Verify what you install | What the provenance chain proves and does not (OIDC Trusted Publishing, SLSA attestations, immutable Releases, SHA256SUMS, SBOM), the exact gh attestation verify / dotnet nuget verify commands, the token-free API query, and why a nuget.org package must be un-signed before its digest matches |
| Install with apt | Debian / Ubuntu (amd64, arm64): add the signed Orkeon apt source once, then apt install / apt upgrade; the stable, rc and dev channels, going back to a version, removal, Docker builds, troubleshooting |
| MCP interop | Check the MCP client against the reference server (server-everything): the nightly test and the MCP Inspector procedure. |
| Whisper through MCP | Transcribe audio from orkeon-repl, orkeon run or orkeon-host: a local faster-whisper behind an MCP server, its MCP:Servers and mount settings, the agent side, and the Orkeon limits the server is written around (paths, text-only results, the 4000-character cap, the 30 s handshake) |
Reference
| File | Description |
|---|---|
| Scripting DSL reference | Every .ork.ts builder and method, with the column that exists nowhere else: which of the two shapes honours it. Plus the known gaps between the typings and the runtime |
| Examples catalog | Editorial map of examples/ (9 business categories + RAG/RaggableTree/scripting showcases); the generated examples/INDEX.md is the authoritative inventory |
orkeon CLI reference |
Every command (run, init, llm, rag, forge, usecases, email, drive, doctor, settings, typings, mcp, quickstart, eval, runs) with options and examples, plus orkeon-repl |
| Configuration reference | The single map of the settings (Llm, Orkeon:*, MCPβ¦): sources and precedence, then every key by category β one line per key, with its type, its default and the hosts that read it |
| Limits and constraints | Known constraints of the current version, including what ships but is not wired yet |
| A2A conformance matrix | Honest position vs the A2A v1.0 spec: operations, data model, bindings, security β what interoperates and what does not |
| Stability and versioning policy | What a patch, a minor and a major may change; the frozen API surface (PublicAPI.Shipped.txt), what is outside the commitment, deprecation, supported versions |
| Experimental APIs | [Experimental] surfaces (A2A, Autonomous, corrective RAG, MCP), ORKEXP001β007 diagnostic IDs, how to opt in |
| Example data policy | Why examples ship config not datasets, how to mount your own input (/data:ro, /output:rw), and contributor rules for bundled sample fixtures |
| Opt-in subsystems | A2A, monitoring, NIST, DLP, tool rate-limiting, key rotation, benchmarking, multi-modal, kickoff hooks, RAG subsystem β explicit activation AddOrkeonXxx() (outside default DI); plus the building blocks AddOrkeonInfrastructure() registers and which of them nothing consumes |
| Hosting & runner bootstrap | Orkeon.Hosting: RunnerHost.Build, ConfigureRunnerServices wiring order (LLM-first, tool suites, VFS, the default ToolRegistry), RunnerExecution flows, telemetry (OTLP), .NET Aspire (AddOrkeonHost, AddOrkeonCrewRun), and the web-host consumption pattern |
| Microsoft Agent Framework interop | An Orkeon crew as a MAF AIAgent (CrewAgent, AddOrkeonAgentFramework); a MAF agent as an Orkeon agent's model (WithAgentFrameworkAgent) or tool (WithAgentFrameworkTool) |
| Example README template | Template for examples/**/README.md: What it does / Prerequisites / Required data / Run it (per way) / Expected output / Duration & cost |
| LLM provider comparison | Capability matrix per provider (SSE streaming, native tool calling, GBNF grammar, response_format, thinking, metrics, resilience), derived from the source code |
| LLM campaign results | The latest real-API result of every campaigned model, mode by mode, regenerated by the campaign kit after each campaign |
| Publication matrix | Source of truth for what ships where: NuGet.org vs GitHub Packages, dotnet tools, installer artifacts, version flow, the dev channel (the latest main between two tags) |
Recommended reading paths
"I want to understand the framework"
overview β yaml-and-builders β process-types β fsm β graph β autonomous β inventory β new-tool-pattern
Start with the overview to absorb Agent, Task, Crew, Tool. Then explore YAML configuration and the builders. The ProcessTypes comparative guide gives a global view of the 6 strategies; the FSM/Graph/Autonomous docs dive into the advanced modes. The tool inventory shows the native capabilities. Finish with the tool creation pattern to understand extensibility.
"I have an application to migrate"
overview β bootstrap β inventory β porting-methodology β porting-example β new-tool-pattern
Absorb the architecture and the DI setup. Identify the available tools. Apply the methodology with the concrete example. Come back to the tool pattern if custom tools are needed.
"I want to extend the framework"
overview β new-tool-pattern β yaml-and-builders β blueprint β inventory
Understand the architecture, then master the typed pipeline and the composition pattern. The blueprint guides the creation of new orchestration modes. The inventory serves as a reference to position contributions.
"I want my agents to handle e-mail"
give-your-agents-a-mailbox β email (guide) β cli (orkeon email) β security
Get one mailbox working end to end with the tutorial, then open the guide for your provider (Gmail OAuth2, Outlook.com/Hotmail through Microsoft Graph, your own IMAP/POP3/SMTP server), the rights model and the send allow-list. The CLI reference lists the orkeon email commands; the security page places the prompt-injection screen among the other layers.