π«π· Version franΓ§aise
YAML reference β Complete schema
This document is the single source of truth for the Orkeon YAML schema. The specialized documents (FSM, Graph, Autonomous) refer back here for the schema.
Complete configuration schema
The YAML structure follows this schema. Key naming: the loader (YamlDotNetSerializer)
matches keys in camelCase (the canonical form, the one YamlCrewExporter writes β see
Export) and falls back to snake_case for the same property β expectedOutput and expected_output, llm_override and
llmOverride are equivalent everywhere. Every key is read or refused at load: a key no model carries (or a retired one) fails the
load with its file, line and path, and the nearest key (Did you mean 'expectedOutput'?);
CrewYamlKeyCheck runs before the deserialization. Only the names you choose stay free: the ids under
agents: and tasks:, the tool names under toolRules:, the collection names under rag.collections:, the keys and values of context:, the
question names under decision.questions: and decision.fallback:, the option names under a question's choice:, and the
keys of when:. A merge
key (<<:) is refused, and so is an anchor on an unknown key: share text under anchors:. The same models
serve the single-file layout and the multi-file layouts (crew.yaml + agents.yaml +
tasks.yaml, or config.yaml + agents/ + tasks/) described in
YAML and Builders; a top-level anchors: mapping of
named multi-line strings is expanded before parsing (YamlAnchorPreprocessor).
# Complete CrewYamlConfig schema
name: string # Crew identifier (required); scopes the crew's long-term memory
goal: string # Goal (required)
process: string # "sequential" (default) | "hierarchical" | "parallel" | "consensual" | "graph" | "autonomous" β case-insensitive; an unknown value fails the load
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: the crew stores the result of each task and recalls the closest ones before each task (embedder required at kickoff); false: nothing is stored or recalled
memoryProvider: string # Requires memory: true (refused otherwise). "InMemory" | "Redis" | "Sqlite" | "ChromaDb" | "Pinecone" | "LanceDb" β case-insensitive (aliases "in-memory", "chroma", "lance"); an unknown type fails the load, listing the known types. The TYPE only: the connection comes from the host section (Orkeon:Redis, Orkeon:Sqlite, β¦). Unset: the host's default store (Memory:Provider)
planning: bool # default: false. true: before the first task, a planner (the host's default profile) writes a step-by-step plan per task, which the task reads in its prompt, in every mode; it changes neither the order nor the agents
maxRpm: int # default: none β at most N model requests per minute for the whole crew, all its agents and its manager together (parallel waves included); one more waits its turn. CrewAI's max_rpm (max_rpm: is accepted). 0 or less fails the load
budget: {tokens, wallTimeSeconds, toolCalls, delegationDepth, spawnedAgents} # process: autonomous only β see Autonomous budget below; default: no token or time cap, 50 / 4 / 10
managerAgent: string # The key of one of the crew's agents (any other name fails the load, listing them). Hierarchical: the manager β required (omitted, the load fails); it assigns and reviews on its own llm: block, profile and model. Consensual: the arbiter of the ManagerDecision fallback (idle, with a warning at the start of the run, under another fallback). Any other process: refused at load
graph: {β¦} # Graph mode: nodes, edges and the circuit-breaker settings (see the dedicated section)
llm: # Crew-default LLM, merged FIELD BY FIELD under each agent's own llm: (same shape as agents.<id>.llm)
profile: string # Host LLM profile (Llm:Profiles:<name>) for every agent β unknown β the load fails, listing the host's profiles
model: string
max_tokens: int # Positive; omitted = the inherited cap, 0 or less fails the load naming the crew
temperature: float
links: # EventHub ACL (optional) β who this crew may talk to on the hub
- to: string # The target crew's name:, verbatim β or "client:<name>" for an external peer (e.g. a desktop front-end)
direction: string # "outbound" (default) | "inbound" | "bidirectional" (alias "both") β an unreadable value drops the entry with a warning
allowed_topics: [string] # Omitted or empty = every topic
mounts: # The virtual roots the crew uses (optional) β selects and validates, never restricts
- /output # a root a settings entry (or a --mount) must provide; refused in one line when nothing does
- 01J9Z3K4M5N6P7Q8R9S0T1V2W3|/data # a root pinned to ONE settings entry by its id, when several entries declare it
announce_mounts: bool # default: true β every agent with a file-system tool lists its virtual paths in its system prompt (alias announceMounts); an agent's own key wins
rag: # Crew-level RAG configuration (optional)
provider: string # Removed: the load refuses it and points to Orkeon:Rag:Provider β the store is the host's
collections:
<collection_name>:
sources: [string] # Files, globs, directories or URLs β relative to the crew's folder unless absolute β ingested when the crew is created
chunking: # Omitted β the ingestion pipeline's defaults
strategy: string # default: "recursive"
max_tokens: int # default: 512 β tokens per chunk (Γ4 characters)
overlap: int # default: 64 β token overlap between chunks
defaults:
profile: string # The retrieval profile of every knowledge attachment that names none (see Knowledge & RAG configuration)
agents:
<agent_id>: # Key = unique agent identifier
role: string # Agent role (defaults to the agent key)
goal: string # Agent's personal goal (required)
backstory: string # Context and expertise (multi-line recommended)
tools: [string] # Tool names registered in IToolRegistry (an unknown name fails the load under Orkeon:CrewFactory:StrictTools, the runners' default)
allowDelegation: bool # default: true β allows delegation to other agents
maxIter: int # default: 20 β the turns the agent may take on a task (C# and .ork.ts too). 0 or less fails the load
maxRpm: int # default: none β at most N model requests per minute for this agent; one more waits its turn. The host's RateLimiting:AgentRequestsPerMinute bounds it too, the stricter winning. 0 or less fails the load
maxExecutionTime: int # default: none β the seconds a task may take on this agent (alias max_execution_time); 0 or less, or above 4294967 (about 49.7 days), fails the load, and so does a limit on the hierarchical manager
permissionMode: string # default: none (Orkeon:Security:PermissionGate:DefaultMode) β default, acceptEdits, bypassPermissions, plan or dontAsk (C# AgentBuilder.PermissionMode): the mode the permission gate reads for this agent's tool calls, once Orkeon:Security:PermissionGate:Enabled is true; any other value fails the load
working_root: string # default: none β a virtual path (alias workingRoot, C# AgentBuilder.WorkingRoot) under a mount that confines this agent's file tools and shell_command to it; refused at run start, naming the root, when no mount holds it
filesystem: # default: none β the only virtual paths this agent's tools may touch (C# AgentBuilder.FileSystem); each entry narrows its mount, never widens it. A list: a lone path or map fails the load naming the agent; no value, ~ or null is no declaration
- string # a path: the mount's rights there
- path: string # or a path with
access: string # "ro" | "rw" | "rwnd" β refused at run start, naming the agent and the entry, above the mount's rights or under no mount; an empty list, an unknown key or access fails the load
announce_mounts: bool # default: the crew's announce_mounts β list this agent's virtual paths and working root in its system prompt (alias announceMounts, C# AgentBuilder.AnnounceMounts)
verbose: bool # default: false β detailed logs for this agent (tool calls, tool results, model responses, at Information, category Orkeon.Verbose)
llm: # Omitted (and no crew llm:) β the runner's Llm settings section
profile: string # Host LLM profile (Llm:Profiles:<name>): the provider this agent runs on; "default" = the Llm section
model: string # LLM model id β omitted β the profile's own model
temperature: float # Sent whatever its value β omitted = the profile's, else none is sent and the model applies its own
maxTokens: int # Output token pin, positive β omitted = the model's documented maximum; 0 or less fails the load
topP: float # Nucleus sampling, sent whatever its value β omitted = the profile's, else none is sent (Mistral writes 1)
thinking: # Reasoning control (capability-gated per provider)
enabled: bool
effort: string # "low" | "medium" | "high" | "xhigh" | "max", exact case β any other value fails the load (a provider sends the nearest level its field knows)
budget_tokens: int # Honoured by Qwen and OpenRouter; other providers warn
responseFormat: string # "text" (= provider default) | "json_object" | "json_schema" β any other value is forwarded as-is with a warning
responseSchema: # With responseFormat: json_schema (a schema alone implies json_schema)
name: string # default: "response"
schema: string # The JSON Schema as a JSON string, e.g. '{"type":"object"}'
strict: bool # default: true
cache: # Explicit prompt caching (Anthropic); off unless a breakpoint is asked
system: bool # default: false
tools: bool # default: false
ttl: string # "5m" | "1h"; omitted = vendor default. Without system or tools it caches nothing and fails the load
guardrails: # Operational rules injected into the agent's system prompt (optional)
preset: string # "analysis" | "strict" | "creative" β any other name fails the load
header: string # Section header β used only without a preset (every preset brings its own)
rules: [string] # Global numbered rules
toolRules: # Rules rendered only when the agent has the tool; a tool name ignores case, and one written under two keys fails the load
<tool_name>: [string]
knowledge: # Knowledge (RAG) collections attached to the agent (optional); an unknown key of an entry is refused, a malformed value stays a warning
- string # Short form: collection name with default options
- collection: string # Long form (required key)
top_k: int # default: 5 β chunks retained per query
min_score: float # Minimum relevance score in [0, 1]
profile: string # This attachment's retrieval profile β else rag.defaults.profile, else Orkeon:Rag:Profile (see Knowledge & RAG configuration)
max_context_tokens: int # default: 2000 β cap on injected context tokens
tasks:
<task_id>: # Key = unique task identifier
description: string # Detailed task description (required)
expectedOutput: string # Expected result format/content (required)
agent: string # Key of the agent assigned to the task (a key matching no agent fails the load, listing the crew's agents)
dependencies: [string] # Keys of prerequisite tasks (guarantees ordering; an unknown key fails the load, listing the crew's tasks; so does a cycle)
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
retry: # default: none β the task runs once. A failed attempt runs the WHOLE task again (see "Task retry")
attempts: int # required, 1 or more β runs in all, the first one included
backoffMs: int # default: 0 β base wait before a new attempt, in milliseconds
backoff: string # "fixed" (default) | "exponential" (doubles at each retry, capped at 5 minutes)
humanInput: bool # default: false β requests human intervention; with checkpointing the question is durable: the run can stop on it (exit 75) and resume with --input
context: {key: value} # Additional context data
tools: [string] # Tools ADDED to the agent's own for this task only (never replacing them) β resolved like an agent's tools: an unknown name fails the load under StrictTools
deliverable: # Output-file contract (ignored without a path)
path: string # Virtual path, e.g. "/output/report.md"
source: string # "tool_call" (default β the agent writes the path itself and needs a tool that writes that format; the prompt names the one it holds, the format's own first; the load warns when no agent can) | "final_message" (the framework writes the final answer) | "structured_output" (JSON written by the framework, constrained by the schema as json_schema where the provider declares it, as a GBNF grammar where Llm:Grammar is on, and always parse-checked) | "none" β any other value fails the load
format: string # "markdown" (default) | "json" | "text"
sanitize: bool # default: true β strips trailing template tokens (final_message)
schema_path: string # Virtual path of a JSON Schema file (structured_output needs it or schema_inline)
schema_inline: string # The JSON Schema as a JSON string β alternative to schema_path
llm_override: # Task-level LLM override (cascade crew β agent β task)
profile: string # This task runs on another host LLM profile than its agent's
response_format: string # Same values as llm.responseFormat
response_schema: {name, schema, strict} # schema is a JSON string
temperature: float
max_tokens: int # Positive; omitted = the inherited cap, 0 or less fails the load naming the task
top_p: float
thinking: {enabled, effort, budget_tokens}
cache: {system, tools, ttl} # Same shape as the agent's cache: β replaces the agent's block whole; a block with no breakpoint turns the agent's cache off for this task
guardrails: # Task-level guardrails, same shape as the agent block (optional)
preset: string # "analysis" | "strict" | "creative" β any other name fails the load
header: string
rules: [string]
toolRules:
<tool_name>: [string]
decision: # Makes the task a decision task: no agent, answered by the decision model β see Decision tasks and conditions below. Together with agent: refused at load
questions: # Required, at least one; the key is the question's name
<question>:
choice: {<option>: string} # One option among up to 255, each with its description
score: [string] # An ordered scale of up to 10 levels
noul: string # A yes-no question: the statement
instructions: string # Optional, for choice and score
minConfidence: float # default: 0.5, in [0, 1] β under it, an option condition selects nothing
state: [string] # Keys of the tasks whose output the model judges; default: the outputs of the dependencies that ran
longContext: bool # default: false β asks for the model's long context
fallback: {<question>: string} # Answers used without a request when the decision circuit is off
when: # Runs the task only when a decision task answered as written (one decision task per when:)
<task>.<question>: [string] | ">= 0.7" # An option list (choice), or a threshold: a probability (yes-no) or a level position (score)
<task>.<question>.<option>: ">= 0.25" # The probability of one option of a choice
<task>: otherwise # Alone: holds when no sibling condition on that task holds
Validation happens at load time (CrewDefinitionValidator): a crew needs a name, a goal, at least one agent (each
with a goal) and at least one task (each with a description and an expectedOutput); circular
dependencies, a mounts: item listed twice or two ids selecting the same root fail the load. So
does a circuitBreaker: key, at the root or on a task: the block was removed (see "Removed: circuitBreaker" below), and the load names the graph block
instead of ignoring it. And so does a task's asyncExecution: true outside process: sequential and
process: parallel: the four other modes order their tasks themselves, and the load names every task
that asks for it rather than ignore the flag (see Asynchronous tasks).
A maxRpm of 0 or less β on the crew or on an agent β and a maxIter of 0 or less fail the load too,
naming the crew or the agent: leave maxRpm: out for no limit, maxIter: out for the default (20).
A max_tokens of 0 or less β on the crew's llm, an agent's
llm or a task's llm_override β fails the load too, naming the crew, the agent or the task: omit the key to keep
the inherited cap. The host's own caps on model calls β which bound an
agent's maxRpm, the stricter winning β are the settings of
RateLimiting.
An agent's maxExecutionTime (or max_execution_time) is whole seconds: 0 or less, a decimal, a value above the
ceiling (4294967 s, about 49.7 days) and a limit on the managerAgent of a hierarchical crew fail the load, naming
the agent. A task past its limit ends ExecutionTimeExceeded at the latest at the end of the call in progress;
time spent waiting for a human does not count.
A task's retry: without attempts, with attempts below 1, a negative backoffMs, a backoff other than fixed or exponential, or on a decision task, fails the load too, naming the task and the key (see Task retry).
A message names an agent or a task by its key β Agent 'researcher' must have a goal. β, a
configuration built in code by its identifier.
Decision tasks and conditions
A task that carries a decision: block is a decision task: it has no agent, no LLM call and
writes no text. At run time it sends its state and all its questions to the decision model in one
request (see Decision models), and
its output is the answers. A task that carries a when: block runs only when a decision task
answered as written, and is skipped otherwise.
agents:
reader: { role: Reader, goal: Read tickets }
engineer: { role: Engineer, goal: Fix defects }
finance: { role: Finance, goal: Handle refunds }
tasks:
ticket:
description: Read the support ticket
expectedOutput: A summary of the ticket
agent: reader
triage:
description: Sort the ticket
expectedOutput: The category and whether a refund is asked
dependencies: [ticket]
decision:
questions:
category:
choice:
bug: a defect in the product
feature: a request for a new capability
billing: a question about an invoice
refund_requested:
noul: the customer asks for a refund
minConfidence: 0.6
fix_bug:
description: Fix the defect or plan the feature
expectedOutput: A fix or a plan
agent: engineer
when:
triage.category: [bug, feature]
refund:
description: Handle the refund
expectedOutput: A refund decision
agent: finance
when:
triage.category: [billing]
triage.refund_requested: ">= 0.7"
manual_triage:
description: Route the ticket to a person
expectedOutput: A hand-over note
agent: reader
when:
triage: otherwise
summary:
description: Summarise what was done
expectedOutput: A short report
agent: reader
dependencies: [fix_bug, refund, manual_triage]
The decision: block.
questionsis required and holds at least one question. A question declares exactly one kind:choice(a map from option to description, up to 255 options),score(an ordered list of up to 10 levels) ornoul(the statement of a yes-no question, Jev's name for it).instructionsis optional on a choice and a score. Question names are unique.minConfidenceis the confidence floor, a number in [0, 1]; it defaults to 0.5.min_confidenceis read the same way, as every key of the file.statelists the keys of the tasks whose output the model judges; without it the model reads the outputs of the task's dependencies that ran, in order. A listed task is added to the task'sdependencieswhen it is not there.longContext(defaultfalse) asks for the model's long context; it is never requested on its own.fallbackmaps a question to the answer used when the decision circuit is off: an option of a choice, a level of a score,yesornoof a yes-no (quote"no", which YAML reads as a boolean). A question without a fallback answer selects no option. See the fallback.- A decision task still needs a
descriptionand anexpectedOutputlike any task, and the crew still needs one agent, even when no task uses it.
The when: block. A when: names one decision task; every clause is <task>, <task>.<question>
or <task>.<question>.<option>, where <task> is the key of the decision task. Several clauses are
written in one block and all must hold. The grammar:
| Clause | Holds when |
|---|---|
<task>.<question>: [a, b] |
The question is a choice, the chosen option is one of the list and the confidence is at or above minConfidence. |
<task>.<question>: ">= 0.7" |
The question is a yes-no (its probability of a yes, in [0, 1]) or a score (the model's weighted score on the positions of the levels, 0 to n-1) and the comparison holds. The floor does not apply. |
<task>.<question>.<option>: ">= 0.25" |
The probability of that option of a choice satisfies the comparison, even when the option is not the chosen one. The floor does not apply. |
<task>: otherwise |
No sibling condition on that decision task holds, including when the confidence is under the floor. |
A threshold is an operator (>=, >, <=, <) and a number, written as a quoted string: a
probability in [0, 1] on a yes-no or an option, a level position from 0 to the number of levels minus
one on a score ("> 1.5" on [low, medium, high] is above the middle level).
Several tasks whose conditions hold for the same decision all run (a fan-out); a task that depends on
several branches runs when at least one of them ran. The decision task named by a when: is added to
the task's dependencies when it is not there. A task whose condition does not hold, or whose every
dependency was skipped by a condition, is skipped: it leaves no output, and the crew still succeeds.
Where it runs. Decision tasks and when: are supported in process: sequential, parallel and
graph. The other processes refuse them at load (Task 'triage' declares a decision or a condition, which the Hierarchical process does not support.); a crew built in C# that reaches one of them fails
before its first task with the same message.
What is refused at load. A task is named by its declared key, the key of the YAML map, in every
message, in the form Task '<key>' <part> β¦ where the part is decision,
decision.questions.<name>, decision.fallback or when. The load fails on:
- a task with both an
agent:and adecision:, a decision with no question, a choice of more than 255 options, a score of more than 10 levels, aminConfidenceoutside [0, 1] or that is not a number, alongContextthat is not a boolean; - a question that declares more than one of
choice,scoreandnoul; - a fallback that names an unknown question, or an answer the question does not have;
- a
when:on a task that is not a decision task, or that names an unknown question or option, or with a threshold outside its range (a probability in [0, 1], a score position from 0 to n-1) or not written as an operator and a finite number; otherwisewritten beside other clauses, a secondotherwisetask on one decision task, anotherwisewith no sibling condition on that decision task;- an option clause with a list on an option (
triage.category.bug: [bug]), which takes a threshold string only; - a decision or a
when:in a process other than the three above.
With the decision circuit off, the run is also refused before its first task when a decision task has
neither a fallback nor an otherwise task.
Guardrails configuration
Guardrails are operational rules rendered into the executing agent's system prompt. They can be
declared on an agent (apply to every task the agent runs) and/or on a task (apply only to that
task). When both are present, both apply β the agent's guardrails render first, then the task's as a
separate section. preset (analysis / strict / creative) seeds a base set of rules; explicit
rules/toolRules are merged on top, and toolRules for a given tool are only emitted when the
executing agent actually holds that tool for the task β its own tools plus the task's tools:. A preset header takes precedence over a custom header.
A preset other than these three β a typo β fails the load, naming the agent or the task by its key and
the three presets; so does a tool written under two keys of toolRules (file_write and File_Write):
a tool name ignores case.
Knowledge & RAG configuration
Two complementary blocks. The crew-level rag: block declares the collections
(ingestion sources, chunking) and crew-wide defaults. The agent-level knowledge: block
attaches collections to an agent with its retrieval options. At execution-context assembly
time each attached collection is queried with the task input through the retrieval half of its
profile pipeline β the attachment's profile, else rag.defaults.profile, else
Orkeon:Rag:Profile β and the results are injected into the agent's user prompt as numbered,
cited excerpts (IKnowledgeContextAugmenter, honouring top_k, min_score and
max_context_tokens). Both halves need the RAG subsystem (AddOrkeonRag(configuration)), which
every runner host registers (orkeon run in all its forms, orkeon-host): when the crew is
created (CrewFactory), the declared collections are ingested incrementally
(IRagCollectionsBootstrapper β an unchanged source is not re-embedded;
CrewFactoryOptions.PrepareRagCollections = false skips it, as --validate does). On a host
without the subsystem, a declared rag: block and each agent's knowledge: log a warning and
inject nothing. Parsing the YAML itself never triggers ingestion. The document store is the
host's (Orkeon:Rag:Provider, see RAG pipeline); a rag.provider
key is refused at load, with the sentence that points to Orkeon:Rag:Provider.
What a sources entry means: a path that does not start with / is relative to the
crew's folder β /crew under orkeon run crew.yaml or a crew directory, so
./data/faq.md next to the crew file is /crew/data/faq.md β and an absolute one is a virtual
path (/kb/faq.md, a mount of yours). A glob (*, **, ?) is expanded through the VFS the
way rag_ingest, orkeon rag ingest and rag.ingest expand it; a directory stands for every
file below it; an http(s):// address and a plain file reach the loaders as written. A glob or a
directory that yields no file, a relative source of a crew read from a string (no folder to be
relative to) and a glob outside every mount are each a load warning naming the collection β
the crew still loads; a file that is not there is reported by the ingestion. A file two entries
name is ingested once.
Short form β attach collections with default options:
rag:
collections:
produits:
sources: ["./data/catalogue/**/*.pdf", "./data/faq.md"]
agents:
support:
role: "Customer support agent"
goal: "Answer product questions"
knowledge: [produits, procedures]
Long form β per-collection retrieval options (mixable with the short form in the same list):
rag:
collections:
procedures:
sources: ["./docs/procedures/"]
chunking: { strategy: recursive, max_tokens: 512, overlap: 64 }
defaults: { profile: balanced }
agents:
expert:
role: "Domain expert"
goal: "Provide sourced answers"
knowledge:
- collection: procedures
profile: quality
top_k: 8
min_score: 0.35
max_context_tokens: 1500
Keys accept snake_case (the form used above) and camelCase. A malformed knowledge entry (missing
collection, non-numeric top_k, β¦) is skipped or downgraded with a warning β it never
crashes the loader. The fluent equivalent is AgentBuilder.WithKnowledge("produits") /
WithKnowledge("produits", opts => { opts.TopK = 8; opts.Profile = "quality"; }) (cumulative).
Task retry
tasks:
fetch:
description: Fetch the quotes
expectedOutput: A table of quotes
agent: trader
retry:
attempts: 3 # required β 3 runs in all: the first, then at most two retries
backoffMs: 250 # default 0
backoff: exponential # fixed (default) | exponential: 250 ms, then 500 ms, ... never more than 5 minutes
A task that fails runs again, in every orchestration mode: one decorator, between the checkpoint and the execution core, applies the policy, so the strategies never retry and the six modes behave alike. Graph has no retry loop of its own, and maxRetryCycles is refused at load.
- A new attempt replays the whole task, model calls and tool calls included, the tool calls that already succeeded too. Nothing deduplicates them: a task whose tools write (a file, an e-mail, a payment) must be safe to run twice, and that is the crew author's to guarantee.
- Never retried: a cancellation, a refusal of the guardian (
GuardianBlocked), an exhausted budget. A refusal of the permission gate is a tool result inside an attempt, not a task failure. Retries of an invalid output stay inside one attempt. A decision task runs no agent and cannot declareretry:(the load fails, naming the task). - Retried on purpose: an execution timeout (
ExecutionTimeExceeded) and a provider failover chain that ran out of profiles (FallbackExhausted) both count as failures and are retried, after the backoff, because either can be transient. The cost is bounded: at mostattemptstimes the whole failover chain for each turn of the task. - What a failed attempt leaves behind: its tool calls (a file written, a message sent), what a tool wrote to memory, the cost it metered and the
tool.*andcost.updatedevents it emitted stay, and the callbacksOnTaskStarted/OnTaskCompletedfire once per attempt. The task's result goes to the crew's memory and its deliverable (final_message,structured_output) is written only by an attempt that produced a final answer, so a retry replaces them rather than duplicating them; a file the agent writes itself withfile_writeis replaced only if the next attempt writes the same path. - Resume: only the attempt that ended the task is checkpointed. A run stopped between two attempts, or whose last attempt failed, holds no checkpoint for that task, and
orkeon run --resumeruns it again from attempt 1. - What is left after the last attempt is the last failure, exactly as if the task had run once: the same failed result or the same exception.
- The wait between two attempts comes from
backoffMsandbackoff, on the host'sTimeProvider, and ends at once when the run is cancelled. - What a watcher sees: each retry emits a
task.startedcarryingattempt(the strategy's own start is attempt 1; see the run event bus);task.completedcomes once, for the attempt that ended the task. The checkpoint of a task that succeeded on its third attempt recordsRetryCount: 2, and a resumed run answers it from there without asking the model, replaying itsRetryCount. - Provider failover is a different layer. A failover (where one is configured) switches to the next provider inside one model call;
retry:runs the whole task again. They combine: a call that fails every provider of its chain fails the attempt,retry:then runs the task again, and that attempt walks the chain afresh, so a task makes at mostattemptstimes the chain's length of model calls per turn. - Graph budgets count the attempts: when no bounds are given, the visits default to the sum over the tasks of
1 + retries(retries=attempts - 1), that isnodes Γ (1 + retries)when every task retries alike (ADR-018), and the transitions to twice that plus one.
Graph configuration
With process: "graph", a graph: block describes the state graph the crew runs and bounds it (ADR-018); without one, or with a block that holds only budgets, the crew runs one node per task, chained in execution order:
process: graph
graph:
start: triage # optional: the first node by default
nodes: # optional: absent = one implicit node per task, its id the task's name
- { id: triage, task: triage }
- { id: fix, task: fix }
- { id: escalate, task: escalate }
edges:
- { from: triage, to: fix, when: { triage.category: [bug] } }
- { from: triage, to: escalate } # no `when`: the "otherwise"
- { from: fix, to: END }
- { from: escalate, to: END }
circuitBreakerPreset: strict # "strict" (default) | "permissive" | "default"
maxTransitions: 50 # default: computed, 2 x visits + 1
maxVisits: 5 # visits of ONE node - default: computed, sum over the tasks of 1 + their retries
maxTotalDurationSeconds: 600 # total duration (overrides the preset)
- Nodes. A node is
{id, task}:tasknames a task of the crew,STARTandENDare refused as ids. A task is run by one node at most; whennodesis given, a task no node names is refused.edgeswithoutnodesgives one implicit node per task. A node is revisited by an edge leading back to it: on a revisit the latest output and the latest decision win. A node whose task fails ends the run: there is no routing on failure (a retry is the task'sretry:). - Edges. Several
edgesfrom onefromare one conditional edge, evaluated in the order declared: the first whosewhenholds wins, and the edge withoutwhenis the "otherwise". Afromthat carrieswhenedges is a decision task and has exactly one edge withoutwhen; an ordinary task has exactly one edge. Thewhenkeeps the grammar of the task-level one, with its<task>.prefix:<task>.<question>: [option, ...],<task>.<question>: ">= 0.7",<task>.<question>.<option>: ">= 0.25"; the task is thefromtask, and its questions are checked at load.otherwiseis not written: an edge withoutwhenis it. - Refused at load, each message naming the node: a
whenon afromthat is not a decision task, a decision with no edge withoutwhen, two edges withoutwhenfrom one node, several edges on an ordinary task, an orphan node, a node with no way toEND, an edge to an unknown node, agraph:outsideprocess: graph, and a task-levelwhen:ordependencies:in a crew that has nodes or edges (the edges order the tasks, a second router would contradict them). The topology faults come fromGraphTopologyValidator, all at once, and the export checks the same rules before it writes. - Budgets.
maxVisitsis the Domain'sMaxStateVisits, counted per node: a node entered more often than that trips the breaker. Left unset,maxVisitsis the sum over the tasks of1 + retriesandmaxTransitionstwice that plus one; an explicit value wins. - Removed (
[breaking]). ThegraphConfig:block (its budgets moved intograph:,maxStateVisitsbecomingmaxVisits),maxRetryCyclesand anymaxCycles: a bound on cycles ismaxVisits, and a retry is the task'sretry:. A crew that still writesgraphConfigis refused at load, pointing tograph:; amaxRetryCyclesormaxCycleskey is refused at load as a key Orkeon does not read. - Execution. The Domain engine runs every crew of the Graph process, with a
graph:block or without;JsStateGraphruns only thestateGraph(...)of a.ork.tsscript. A resumed run walks the graph again: the executions of a task that already ended are answered from the checkpoint, keyed<task>#<n>by their order, so a node entered twice has two entries. A decision node's answer is checkpointed the same way (<task>#<n>) and replayed on resume, never asked again: a model asked twice could answer otherwise and send the resumed run down another route. The export writesgraph:back, so import, export and import give the same graph.
graph: is the only circuit-breaker setting a crew carries (CircuitBreakerPolicyFactory.ResolveGraph). The graph engine enforces three limits only: transitions, visits of one node, total duration (GraphRunner); a state timeout or a degraded mode has no effect on a graph run.
Removed: circuitBreaker
The circuitBreaker: block β at the crew root and on a task β is gone, and a crew that still
writes one is refused at load with a message naming the graph block. The task block configured a
task state machine that no execution path ran, along with three guard limits (maxRetries,
maxToolCallsPerRound, maxValidationRetries) read by nothing. The crew block was read by the
Graph mode alone, where the graph: block carries the same preset and the same three effective limits.
What bounds a task is its agent loop: the agent's maxIter, the stop after three identical
consecutive tool errors, and the output-validation retries. An agent with two iterations left is told so once, while it can still act (nothing is sent when maxIter is 2 or less); one that reaches maxIter gets a last tool-free turn that asks it to state what it could not do, and its task keeps Success but is flagged endedOnIterationCap. This holds for the main agent loop; the native tool-calling and legacy text fallback loops do neither: they still end on the cap, without the note and without the flag. What bounds a graph run is
graph: (above). The generic state-machine engine and CircuitBreakerPolicy stay β the
Graph mode, orkeon forge and the corrective RAG graph use them (see FSM).
The tool_call deliverable
With source: tool_call (the default) the agent writes the file itself. The prompt always names the path:
Deliverable: write the final result to '<path>' using the <tool> tool. when the agent's toolbelt, its
own tools plus the task's, holds a built-in tool that writes that path, the tool of its format first
(docx_writer for a .docx, file_write for a text file; the writers), and
Deliverable: write the final result to '<path>'. otherwise, so an agent is never told to call a tool it
does not have, nor file_write for a binary file. With source: final_message the
prompt says the framework writes the final answer as-is to the path, so the agent gives the complete
content and does not write the file itself; source: structured_output adds no line.
When a tool_call task succeeds, the framework checks through the virtual file system that the file was
written by the task during the run: it reads the file's state (existence, size, last write time) once,
when the task's first attempt of the run starts, and again when each attempt ends. A retry, a hierarchical
revision or another ballot of a vote that keeps the file an earlier attempt of the same task wrote is not
flagged. A file absent at the end, or present but unchanged since that first start (a file left by an
earlier run), leaves the task a success but flags it deliverableMissing
(TaskResult.DeliverableMissing): a warning names the task (its key, else the start of its description),
the agent and the path, AUTO_SUMMARY.md shows β completed without writing its deliverable (β completed on its iteration cap without writing its deliverable when the task also ended on its iteration cap), the
task.completed event carries deliverableMissing: true and run.finished counts it in
missingDeliverables (run event bus). A file system that gives no size or write time
falls back on existence alone. The check is best-effort: a file system that cannot answer leaves the flag
false, a task run without a file system is not checked, and a cancellation during the check cancels the
task as any other. Only a task that succeeded is flagged: a failed task, a hierarchical task the manager
rejected to the end included, never is, and the failed output of such a hierarchical task names no
deliverable path to the tasks after it. In a consensual vote the file is judged on the whole vote: a
candidate that wrote it counts, whichever answer the vote retains.
A resumed task replays the flag and the path from its checkpoint (a checkpoint written before them replays
false and none); when the file the checkpoint names is gone at resume, the replay hands no path to the
tasks after it, and a tool_call task reports its deliverable missing (a file the framework wrote, with
final_message or structured_output, only loses its path).
A decision task runs no agent and writes no file: a deliverable: declared on one is never written, and
the load check reports it once, whatever the source, in a YAML crew, a crew.ork.ts and under --validate
alike (deliverables checked at load).
When the output of a previous task is cut to fit the prompt of a later one and the file of its
deliverable is known to exist (written by the framework for final_message and structured_output,
found by that check for tool_call, in every mode, an autonomous takeover included), the cut text ends
with [full result in '<path>': read it with file_read]; a previous output left out entirely is named by
[result of task <id> in '<path>': read it with file_read]. Both pointers are written only to an agent
whose toolbelt holds file_read; an agent without it gets the cut text alone. An output without a known
file is cut as before.
Removed: outputFile
A task's outputFile: key is gone, and a crew that still writes one is refused at load with a
message pointing to the replacement: the task's deliverable: block (above), e.g.
deliverable: { path: /output/report.md }. With the default source: tool_call the agent is told to
write that path; with source: final_message the framework writes the final answer there. Loading checks
that a tool_call deliverable can be written (below).
Deliverables checked at load
A tool_call deliverable that no agent able to run its task can write is reported when the crew loads
(#392): a warning names the task, the path and the agents, and the crew still loads. orkeon run --validate prints it as one WARNING: line per task (cli); a run flags a
file that was not written all the same (the tool_call deliverable).
- The agents judged are those the process may give the task to: the agent the task names in a
sequential,parallelorgraphcrew (every agent when it names none, picked in turn at run time); every agent but themanagerAgentin ahierarchicalorconsensualcrew; every agent in anautonomouscrew. The warning comes only when none of them can write the file. - An agent can write the file when its toolbelt, its own tools plus the task's, holds a built-in tool
that writes that path:
docx_writerfor a.docx,xlsx_writerfor a.xlsx,image_generationfor a.png,.jpg,.jpegor.webp,firefox(its screenshot) for a.png, andfile_writefor any text file, never a binary one. A path is binary when its extension, whatever its case, names an office document (.docx,.xlsx,.pptx,.odt,.pdf,.epuband their kin), an image, an archive, audio or video, a database or data file (.sqlite,.db,.parquet), a font or an executable: the final answer's text cannot be one, so no source but a writer of its format delivers it. A format that is plain text (.rtf,.svg,.csv,.html) is not binary:file_writewrites it. The editors (edit_file,edit_batch,structural_rewrite) change a file that exists, the downloaders (drive_download,email_save_attachment) name the file themselves, andshell_commandnames no path: none of them counts. - No warning when the toolbelt holds a tool Orkeon does not ship (an MCP server's, a script's, a plugin's): the check cannot know what it writes. Nor for an agent whose model runs its own tools.
- A decision task that declares a
deliverable:gets its own finding, whatever the source: a decision runs no agent and writes no file, so the remedy is to remove the block or move it to a task that runs an agent. The writer check skips it. - Paths that load without the check are listed in the limitations:
a crew built in C# with
CrewBuilder, a procedural.ork.tsunder--validate, which is not loaded as a crew, and an agent whose model runs its own tools (a Microsoft Agent Framework agent), which counts as able to write.
A C# host runs the same check with DeliverableToolCheck.Check(tasks, agents, processType, managerAgentId) (Orkeon.Application.Crew), which returns one DeliverableToolFinding per task, its
Message the text of the warning and its Kind (DeliverableFindingKind.NoWriter or DecisionTask) what
it reports. DeliverableToolCheck.IsBinary(path), WritersOf(path), PreferredWriterOf(path) and
WriterHeldFor(toolNames, path) give the rule the check, the prompt and the forge share. CrewFactoryOptions.WarnOnDeliverableTools (default true) turns the
load warning off; --validate does, to print each finding once.
Autonomous budget
budget: bounds the run of a process: autonomous crew (#218):
process: autonomous
budget:
tokens: 400000 # running sum of prompt + completion of every call; none by default
wallTimeSeconds: 1800 # none by default
toolCalls: 80 # tasks handed out; 50 by default
delegationDepth: 2 # delegations in the run; 4 by default
spawnedAgents: 3 # agents spawned through spawn_agent; 10 by default
Every key is optional, and a key left out takes its default: a crew without budget: has no token
cap and no wall time, so an ordinary crew is never cut short by a figure it did not choose. A limit of
0 or less, or a budget: on a crew of another process β the only one that spends it is
autonomous β fails the load, naming the crew. The export writes the block back, the wall time in
whole seconds. The same budget is CrewBuilder.Budget(new CrewBudget { ... }) in C# and
crewBuilder().budget({ tokens, wallTime, toolCalls, delegationDepth, spawnedAgents }) in .ork.ts
(see the Autonomous orchestration guide).
Export
YamlCrewExporter β which AddOrkeonYaml() registers β writes a CrewConfiguration back to YAML:
ExportToString, ExportToFileAsync, or ExportToDirectoryAsync for the flat crew.yaml +
agents.yaml + tasks.yaml triplet. Loaded again, the file gives the same configuration β every key
the loader reads β and its own export is the same text, byte for byte. Keys are written in camelCase,
and a key nothing sets is not written at all.
- Under the author's keys. A crew loaded from YAML keeps the key of each agent and task
(
researcher,collect): the export writes each one under it, and every reference βagent:,dependencies:,managerAgent:β by it. A configuration built in C# or by a.ork.tsscript has no keys: its agents and tasks are written under their identifiers. Two entries under one name, or a reference that names no entry, fail the export with anInvalidOperationExceptionthat names them: the loader would refuse the file. - What the loader made of your file, not your file. The export writes what the configuration
carries: a guardrails
preset:comes back as theheader,rulesandtoolRulesit brought, the crew'sllm:as the block each agent got from it, under each agent, andanchors:as the text they stood for. A knowledge attachment that only names its collection is written in the short form, any other in the long form. - A relative source follows the file. A
rag:source is written as it was, so./data/faq.mdis read against the folder the exported file is loaded from (see Knowledge & RAG configuration): export next to the data, or write absolute sources. The folder the crew was read from is not a key, and is not written; neither is anything the schema above has no key for.
YAML models
All the YAML models live in Orkeon.Infrastructure.Configuration (src/core/Orkeon.Infrastructure/Configuration/Yaml/YamlConfigModels.cs); YamlCrewMapper turns them into the Domain CrewConfiguration and CrewDefinitionValidator checks it. They include:
CrewYamlConfig(complete crew definition) andCrewSettingsYamlConfig(the crew settings file of the multi-file layouts βcrew.yamlorconfig.yaml)AgentYamlConfig(role, goal, backstory, tools, limits)TaskYamlConfig(description, expected output, dependencies, tools, deliverable, LLM override, guardrails)LlmYamlConfig(profile, model, temperature, max tokens, topP, thinking, responseFormat/responseSchema, cache) withThinkingYamlConfig,ResponseSchemaYamlConfig,CacheYamlConfigLlmOverrideYamlConfig(the task-levelllm_override:block)DeliverableYamlConfig(the task-leveldeliverable:block)GuardrailsYamlConfig(agent- and task-levelguardrails:)LinkYamlConfig(the crew-levellinks:ACL)CrewYamlConfig.Mounts/CrewSettingsYamlConfig.Mounts(the crew-levelmounts:block β/rootor<ulid>|/rootitems) βCrewConfiguration.Mounts(MountReference)AgentYamlConfig.Filesystem(path or{path, access}items) βAgentConfiguration.FileSystem(FileSystemScopeEntry);AgentYamlConfig.AnnounceMounts, else the crew'sannounce_mountsβAgentConfiguration.AnnounceMountsGraphYamlConfig(start, nodes, edges, circuitBreakerPreset and its limits) withGraphNodeYamlConfig,GraphEdgeYamlConfigRagYamlConfig(collections + sources/chunking, defaults β withRagCollectionYamlConfig,RagChunkingYamlConfig,RagDefaultsYamlConfig) βRagCrewConfigAgentYamlConfig.Knowledge(short/long form entries) βKnowledgeAttachment
There is no framework-level "predefined configuration" object: a host composes its own settings through AddOrkeonInfrastructure / AddOrkeonApplication and its appsettings.json.
See also: YAML and Builders Β· FSM orchestration Β· Graph orchestration Β· Autonomous orchestration Β· Back to index