Table of Contents

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

YAML, Builders and CrewFactory

See also: Bootstrap Β· YAML schema reference Β· Back to the index

Fluent Builders

The three main entities are built via fluent builders defined in the Domain layer:

  • AgentBuilder (Orkeon.Domain.Agent): configures role, goal, backstory, tools, execution constraints, prompt templates (SystemTemplate replaces the default role section of the agent's system prompt, ResponseTemplate is appended to it as the expected response format, and PromptTemplate wraps the task's prompt at each {{ .Prompt }} and is refused by Build() without that mark), tool access policy, and the provider the agent's turns run on when it carries its own (.WithLlm(provider) β€” Agent.Llm, metered as the agent's work; a Microsoft Agent Framework agent through .WithAgentFrameworkAgent(agent)). Build() refuses it with a host profile (.WithLlmConfig(LlmConfig.OnProfile(name))), and, on a provider that runs its own tools β€” a MAF agent β€”, with .WithTool or .AllowDelegation()
  • CrewTaskBuilder (Orkeon.Domain.Task): configures description, expected output, priority, dependencies, output JSON schema, async mode (.Async() β€” honoured by a sequential crew, refused by CrewBuilder.Build() outside Sequential and Parallel), human intervention
  • CrewBuilder (Orkeon.Domain.Crew): configures name, goal, process type, agents, tasks, planning (.Planning(), on the provider .WithPlanningLlm(provider) sets β€” refused without .Planning()), memory, callbacks, dynamic agents, and the manager of a hierarchical crew β€” an agent (.Hierarchical(manager), .WithManager(agent)), or a provider of its own (.WithManagerLlm(provider), CrewAI's manager_llm: the manager assigns and reviews on it, the crew then needs no manager agent and every agent works). A manager agent is also a consensual crew's arbiter; a manager LLM also hands an autonomous crew's tasks out. Build() refuses either in a process that has none

Each builder internally delegates to the factory methods Agent.Create(), CrewTask.Create(), Crew.Create() and throws a BuilderValidationException if the required fields are missing.

An agent's model settings: WithLlmConfig(config) sets them whole; the sugar Thinking(enabled, effort) and MaxOutputTokens(n) merges into them and, on an agent that has none, starts from a configuration that names no model (LlmConfig.OnProfile()) β€” the agent then runs on the host's model, whatever vendor the host runs. To pin a model, start from LlmConfig.Create(model); to run on one of the host's named profiles, from LlmConfig.OnProfile("claude"). A token cap (max_tokens, MaxTokens) is a positive integer; omit it to keep the inherited cap. YAML loading, LlmConfig.with in scripts, Agent.Create and SetLlmOverride refuse a value of 0 or less.

YAML configuration

Orkeon supports full crew configuration via YAML. The YamlCrewDefinitionLoader loader (Orkeon.Infrastructure.Configuration) converts YAML files into domain objects.

Configuration schema (abridged)

The YAML structure follows this schema:

# CrewYamlConfig schema β€” most-used keys (see docs/architecture/yaml-schema.md for the full surface:
# crew-level llm:/rag:/links:/mounts:/announce_mounts:, agent workingRoot:/filesystem:/knowledge:, task decision:/when: (see docs/architecture/decision-models.md), tools:/deliverable:/llm_override:, llm thinking/responseFormat/cache)
name: string              # Crew identifier; scopes the crew's long-term memory (the crews of one name share it)
goal: string              # Goal (required)
process: string           # "sequential" | "hierarchical" | "parallel" | "consensual" | "graph" | "autonomous"
verbose: bool             # default: false β€” every agent of the run logs its turns (tool calls, tool results, model responses) at Information, category Orkeon.Verbose
memory: bool              # default: false. true: stores each task's result and recalls the closest ones before each task (needs an embedder)
memoryProvider: string    # needs memory: true. "InMemory" | "Redis" | "Sqlite" | "ChromaDb" | "Pinecone" | "LanceDb" β€” the type; the host section (Orkeon:Redis, …) gives the connection; unset: the host's default store
planning: bool            # default: false. true: a step-by-step plan per task, written before the first one and read by each task in its prompt; never reorders the tasks
maxRpm: int               # default: none β€” at most N model requests per minute for the crew, all its agents and its manager together; one more waits its turn
budget: {tokens, wallTimeSeconds, toolCalls, delegationDepth, spawnedAgents}  # process: autonomous only; default: no token or time cap, 50 / 4 / 10
managerAgent: string      # An agent's key. Required when process = "hierarchical": the manager, on its own llm: block; optional when "consensual": the ManagerDecision arbiter; refused by the other processes
mounts: [string]          # Virtual roots the crew uses ("/output", or "<id>|/output" to pin one settings entry)

agents:
  <agent_id>:             # Key = unique agent identifier
    role: string          # Agent role (required)
    goal: string          # Agent's personal goal (required)
    backstory: string     # Context and expertise (multi-line recommended)
    tools: [string]       # Names of tools registered in IToolRegistry
    allowDelegation: bool # default: true β€” allows delegation to other agents
    maxIter: int          # default: 20 β€” the turns the agent may take on a task
    maxRpm: int           # default: none β€” at most N model requests per minute for this agent; one more waits its turn
    maxExecutionTime: int # default: none β€” the seconds a task may take on this agent (alias max_execution_time; 0 < value <= 4294967, about 49.7 days)
    verbose: bool         # default: false β€” detailed logs for this agent (tool calls, tool results, model responses, at Information, category Orkeon.Verbose)
    llm:
      profile: string     # Host LLM profile (Llm:Profiles:<name>) β€” unset = the host's default provider
      model: string       # LLM model ("gpt-4", "claude-3-opus", etc.) β€” unset = the profile's own model
      temperature: float  # Creativity (0.0-2.0) β€” unset = the profile's, else none is sent and the model applies its own
      maxTokens: int      # Output token limit

tasks:
  <task_id>:              # Key = unique task identifier
    description: string   # Detailed task description (required)
    expectedOutput: string # Expected output format/content (required)
    agent: string         # Key of the agent assigned to the task (an unknown key fails the load)
    dependencies: [string] # Keys of prerequisite tasks (guarantees ordering; an unknown key fails the load)
    asyncExecution: bool  # default: false β€” sequential: runs alongside the next tasks, a dependant waits for it; parallel: no effect of its own; other modes: true fails the load
    humanInput: bool      # default: false β€” requests human intervention
    context: {key: value} # Additional context data
    tools: [string]       # Tools ADDED to the agent's own for this task only β€” never replacing them
    guardrails:           # Task-level guardrails (optional) β€” same shape as at agent level
      preset: string      # "analysis" | "strict" | "creative" β€” any other name fails the load
      header: string
      rules: [string]
      toolRules:
        <tool_name>: [string]

One provider per agent (profiles)

A host offers its providers as named profiles (Llm:Profiles:<name> in its settings, the Llm section being the default one β€” see Configuration). A crew picks one by name β€” at crew level (every agent), on an agent, or on a task's llm_override (that task only); the most specific wins, and profile: default brings an agent or a task back to the host's default. A crew file never carries a key or an endpoint.

llm:
  profile: deepseek          # crew level: every agent, unless it says otherwise
agents:
  planner:
    role: Planner
    goal: Plan the article
    llm:
      profile: claude        # this agent runs on the host's "claude" profile…
      model: claude-opus-5   # …on another model than the profile's own
  writer:
    role: Writer
    goal: Write the article  # inherits the crew's "deepseek" profile, on its own model
tasks:
  review:
    description: Review the article
    expectedOutput: A review
    agent: writer
    llm_override:
      profile: claude        # this task alone moves the writer to "claude"

A profile the host does not define fails the crew load, and the message lists the profiles it offers β€” exactly like an unknown tool. A llm: block that names no model runs on the profile's own model (the host's for the default profile), never on a framework default. The manager of a hierarchical crew runs on its manager agent's llm: block like any agent (in C#, a provider set with WithManagerLlm wins, then the provider the manager agent carries itself, WithLlm); the RAG subsystem runs on the profile Orkeon:Rag:LlmProfile names; the planner and the Guardian stay on the default profile (Configuration). In .ork.ts the same choice is agentBuilder().llm(llm.profile("claude")) on an agent and taskBuilder().withProfile("claude") on a task.

A task's tools: add to its agent's own for that task only: a writer that holds file_read and runs a task declaring tools: [file_write] can read and write during that task, and only read during the others. There is no circuitBreaker: block β€” a crew that writes one is refused at load. What bounds a task at run time is the agent loop (maxIter, a stop after 3 consecutive identical tool errors, and the output-validation retries); a Graph run is bounded by graph: (below).

Guardrails may be declared on an agent (all its tasks) and/or on a task (that task only). When both exist, both apply β€” agent rules first, then the task's β€” injected into the executing agent's system prompt. A preset other than analysis, strict or creative fails the load, naming the agent or the task. See YAML schema β€” Guardrails configuration.

When process: "graph" is used, an additional graph: block describes the nodes and edges of the state graph and bounds it:

graph:
  start: string                 # optional: the first node by default
  nodes: [{ id, task }]         # optional: absent = one implicit node per task
  edges: [{ from, to, when? }]  # `to: END` ends the run; several from one node, in order; no `when` = the otherwise
  circuitBreakerPreset: string  # "strict" | "permissive" | "default" β€” default: strict
  maxTransitions: int           # Default: computed, 2 Γ— visits + 1
  maxVisits: int                # Visits of one node β€” default: computed, sum over the tasks of 1 + their retries
  maxTotalDurationSeconds: int  # Total duration in seconds (overrides the preset)

See Graph Orchestration for the full details.

YAML models

The YAML models include:

  • CrewYamlConfig (complete definition of a crew)
  • AgentYamlConfig (role, goal, backstory, tools, limits)
  • TaskYamlConfig (description, expected output, dependencies, tools, deliverable, guardrails)
  • LlmYamlConfig (profile, model, temperature, max tokens)
  • GraphYamlConfig (circuitBreakerPreset, overrides β€” see Graph Orchestration; a failed task is retried by its own retry:, see Task retry)

There is no framework-level "predefined configuration" object: a host composes its own settings through AddOrkeonInfrastructure / AddOrkeonApplication and its appsettings.json.

Loading modes

The YamlCrewDefinitionLoader loader supports the modes below. It reads through the virtual file system (IFileSystemService), so every path it takes is a virtual path under a declared mount β€” /crews/... below assumes a mount such as ./crews:/crews:ro (ADR-008); a disk path finds no mount.

Single-file mode: contains agents and tasks in a single file

// loader: ICrewDefinitionLoader (YamlCrewDefinitionLoader implementation) resolved via DI
var config = await loader.LoadFromFileAsync("/crews/research_crew.yaml", ct);
var crew = await crewFactory.CreateFromConfigAsync(config, ct);

Multi-file mode: separate agents.yaml, tasks.yaml, and crew.yaml in a directory

var config = await loader.LoadFromDirectoryAsync("/crews/research/", ct);
var crew = await crewFactory.CreateFromConfigAsync(config, ct);
// Automatically loads: crew.yaml, agents.yaml, tasks.yaml

Per-entity directory mode: crew settings in config.yaml (or crew.yaml), one agent per file under agents/, one task per file under tasks/. The file-name stem is the entity id β€” i.e. the dictionary key used in the flat formats. LoadFromDirectoryAsync selects this mode automatically as soon as an agents/ or tasks/ sub-directory is present.

crews/research/
β”œβ”€β”€ config.yaml          # crew settings (name, goal, process, llm, …) β€” or crew.yaml
β”œβ”€β”€ agents/
β”‚   β”œβ”€β”€ researcher.yaml  # β†’ agent id "researcher"
β”‚   └── writer.yaml      # β†’ agent id "writer"
└── tasks/
    β”œβ”€β”€ collect.yaml     # β†’ task id "collect"
    └── report.yaml      # β†’ task id "report"
// Same call: the layout is detected automatically.
var config = await loader.LoadFromDirectoryAsync("/crews/research/", ct);
var crew = await crewFactory.CreateFromConfigAsync(config, ct);

Notes:

  • config.yaml is preferred over crew.yaml when both are present; a missing settings file raises FileNotFoundException (parity with flat mode).
  • Empty or absent agents//tasks/ folders simply yield no agents/tasks β€” the usual "at least one agent/task" validation error then surfaces via loader.Validate(config).
  • Mixing the two layouts (e.g. both agents.yaml and an agents/ directory) raises InvalidOperationException rather than picking a silent precedence.
  • Entity files may end in .yaml or .yml; the same stem under both extensions raises InvalidOperationException (Keep one.).
  • The folder's settings file carries crew settings only: an agents: or tasks: key in it is refused like any key no model reads, with its file, line and the nearest key. The agents and tasks are the files of the two folders.
  • Limitation: YAML anchors cannot span files β€” each file is preprocessed independently (this was already true across the three flat files).

On the CLI side, orkeon run <directory> accepts these directories directly β€” see Three ways to run Orkeon.

CrewFactory β€” From YAML to domain objects

The creation pipeline transforms the YAML configuration into operational domain objects via CrewFactory (Orkeon.Infrastructure.Configuration), which implements ICrewFactory (Orkeon.Application.Interfaces).

Creation pipeline

  1. YAML β†’ CrewYamlConfig: YAML deserialization into configuration models
  2. CrewYamlConfig β†’ CrewConfiguration: Mapping of the YAML models to the application DTOs with basic validation (errors throw InvalidOperationException, warnings are logged)
  3. RAG collections: the collections a rag: block declares are ingested (incrementally) β€” when the RAG subsystem is registered; without it, a Warning and no ingestion
  4. Tool resolution: Tool names (strings) resolved via IToolRegistry.GetToolByNameAsync(name) into IBaseTool instances
  5. Agent creation: Agent instances built with AgentBuilder, resolved tools and their llm: block β€” every profile an agent or a task names must be one the host offers, or the load fails listing them
  6. Task creation: CrewTask instances built with CrewTaskBuilder and validated dependencies
  7. Dependency validation: Circular dependency detection and order validation
  8. Crew creation: Crew instance built with CrewBuilder, process strategy applied
  9. Persistence: Agents, Tasks, Crew stored in the repositories β€” always, so ICrewOrchestrationService.KickoffAsync(crew.Id, …) finds them
  10. Links: the crew's identity and links: block are handed to the EventHub ACL (a declared links: block without AddOrkeonEventHubAcl() logs a Warning: nothing enforces it)

Entry points

CrewFactory exposes three public methods:

/// <summary>
/// Creates a Crew from an already deserialized CrewConfiguration.
/// Used after LoadFromFile/LoadFromDirectory.
/// </summary>
public async Task<Crew> CreateFromConfigAsync(
    CrewConfiguration config,
    CancellationToken ct = default)
{
    // Validates the config, resolves the tools, creates agents/tasks/crew
}

/// <summary>
/// Creates a Crew directly from a YAML file.
/// Single-file mode (agents + tasks in the same file).
/// </summary>
public async Task<Crew> CreateFromFileAsync(
    string yamlFilePath,
    CancellationToken ct = default)
{
    // Deserializes YAML β†’ CrewYamlConfig β†’ calls CreateFromConfigAsync
}

/// <summary>
/// Creates a Crew from a YAML directory.
/// Per-entity layout (config.yaml + agents/ + tasks/) or flat crew.yaml + agents.yaml + tasks.yaml
/// </summary>
public async Task<Crew> CreateFromDirectoryAsync(
    string directoryPath,
    CancellationToken ct = default)
{
    // Loads the directory's layout β†’ calls CreateFromConfigAsync
}

Tool resolution

The tool names specified in agents[].tools[] are resolved at construction time via IToolRegistry.GetToolByNameAsync(toolName). What happens when a tool is missing depends on CrewFactoryOptions.StrictTools (config key Orkeon:CrewFactory:StrictTools): the runners (orkeon run) default it to true and CrewFactory then throws with the list of missing tools; the library default is false β€” the tool is skipped with a Warning log and the crew loads without it.

Example error (strict mode):

Crew configuration references unknown tool(s): web_scraper, custom_analyzer. Available tools: file_read, file_write, http_api, ...