π«π· 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 (SystemTemplatereplaces the default role section of the agent's system prompt,ResponseTemplateis appended to it as the expected response format, andPromptTemplatewraps the task's prompt at each{{ .Prompt }}and is refused byBuild()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.WithToolor.AllowDelegation()CrewTaskBuilder(Orkeon.Domain.Task): configures description, expected output, priority, dependencies, output JSON schema, async mode (.Async()β honoured by a sequential crew, refused byCrewBuilder.Build()outside Sequential and Parallel), human interventionCrewBuilder(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'smanager_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 ownretry:, 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.yamlis preferred overcrew.yamlwhen both are present; a missing settings file raisesFileNotFoundException(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 vialoader.Validate(config). - Mixing the two layouts (e.g. both
agents.yamland anagents/directory) raisesInvalidOperationExceptionrather than picking a silent precedence. - Entity files may end in
.yamlor.yml; the same stem under both extensions raisesInvalidOperationException(Keep one.). - The folder's settings file carries crew settings only: an
agents:ortasks: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
- YAML β CrewYamlConfig: YAML deserialization into configuration models
- CrewYamlConfig β CrewConfiguration: Mapping of the YAML models to the application DTOs with basic validation (errors throw
InvalidOperationException, warnings are logged) - RAG collections: the collections a
rag:block declares are ingested (incrementally) β when the RAG subsystem is registered; without it, a Warning and no ingestion - Tool resolution: Tool names (strings) resolved via
IToolRegistry.GetToolByNameAsync(name)intoIBaseToolinstances - Agent creation:
Agentinstances built withAgentBuilder, resolved tools and theirllm:block β every profile an agent or a task names must be one the host offers, or the load fails listing them - Task creation:
CrewTaskinstances built withCrewTaskBuilderand validated dependencies - Dependency validation: Circular dependency detection and order validation
- Crew creation:
Crewinstance built withCrewBuilder, process strategy applied - Persistence: Agents, Tasks, Crew stored in the repositories β always, so
ICrewOrchestrationService.KickoffAsync(crew.Id, β¦)finds them - Links: the crew's identity and
links:block are handed to the EventHub ACL (a declaredlinks:block withoutAddOrkeonEventHubAcl()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, ...