Table of Contents

πŸ‡«πŸ‡· 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.

  • questions is 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) or noul (the statement of a yes-no question, Jev's name for it). instructions is optional on a choice and a score. Question names are unique.
  • minConfidence is the confidence floor, a number in [0, 1]; it defaults to 0.5. min_confidence is read the same way, as every key of the file.
  • state lists 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's dependencies when it is not there.
  • longContext (default false) asks for the model's long context; it is never requested on its own.
  • fallback maps a question to the answer used when the decision circuit is off: an option of a choice, a level of a score, yes or no of 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 description and an expectedOutput like 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 a decision:, a decision with no question, a choice of more than 255 options, a score of more than 10 levels, a minConfidence outside [0, 1] or that is not a number, a longContext that is not a boolean;
  • a question that declares more than one of choice, score and noul;
  • 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;
  • otherwise written beside other clauses, a second otherwise task on one decision task, an otherwise with 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 declare retry: (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 most attempts times 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.* and cost.updated events it emitted stay, and the callbacks OnTaskStarted/OnTaskCompleted fire 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 with file_write is 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 --resume runs 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 backoffMs and backoff, on the host's TimeProvider, and ends at once when the run is cancelled.
  • What a watcher sees: each retry emits a task.started carrying attempt (the strategy's own start is attempt 1; see the run event bus); task.completed comes once, for the attempt that ended the task. The checkpoint of a task that succeeded on its third attempt records RetryCount: 2, and a resumed run answers it from there without asking the model, replaying its RetryCount.
  • 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 most attempts times 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 is nodes Γ— (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}: task names a task of the crew, START and END are refused as ids. A task is run by one node at most; when nodes is given, a task no node names is refused. edges without nodes gives 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's retry:).
  • Edges. Several edges from one from are one conditional edge, evaluated in the order declared: the first whose when holds wins, and the edge without when is the "otherwise". A from that carries when edges is a decision task and has exactly one edge without when; an ordinary task has exactly one edge. The when keeps 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 the from task, and its questions are checked at load. otherwise is not written: an edge without when is it.
  • Refused at load, each message naming the node: a when on a from that is not a decision task, a decision with no edge without when, two edges without when from one node, several edges on an ordinary task, an orphan node, a node with no way to END, an edge to an unknown node, a graph: outside process: graph, and a task-level when: or dependencies: in a crew that has nodes or edges (the edges order the tasks, a second router would contradict them). The topology faults come from GraphTopologyValidator, all at once, and the export checks the same rules before it writes.
  • Budgets. maxVisits is the Domain's MaxStateVisits, counted per node: a node entered more often than that trips the breaker. Left unset, maxVisits is the sum over the tasks of 1 + retries and maxTransitions twice that plus one; an explicit value wins.
  • Removed ([breaking]). The graphConfig: block (its budgets moved into graph:, maxStateVisits becoming maxVisits), maxRetryCycles and any maxCycles: a bound on cycles is maxVisits, and a retry is the task's retry:. A crew that still writes graphConfig is refused at load, pointing to graph:; a maxRetryCycles or maxCycles key 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; JsStateGraph runs only the stateGraph(...) of a .ork.ts script. 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 writes graph: 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, parallel or graph crew (every agent when it names none, picked in turn at run time); every agent but the managerAgent in a hierarchical or consensual crew; every agent in an autonomous crew. 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_writer for a .docx, xlsx_writer for a .xlsx, image_generation for a .png, .jpg, .jpeg or .webp, firefox (its screenshot) for a .png, and file_write for 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, .epub and 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_write writes 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, and shell_command names 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.ts under --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.ts script 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 an InvalidOperationException that 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 the header, rules and toolRules it brought, the crew's llm: as the block each agent got from it, under each agent, and anchors: 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.md is 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) and CrewSettingsYamlConfig (the crew settings file of the multi-file layouts β€” crew.yaml or config.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) with ThinkingYamlConfig, ResponseSchemaYamlConfig, CacheYamlConfig
  • LlmOverrideYamlConfig (the task-level llm_override: block)
  • DeliverableYamlConfig (the task-level deliverable: block)
  • GuardrailsYamlConfig (agent- and task-level guardrails:)
  • LinkYamlConfig (the crew-level links: ACL)
  • CrewYamlConfig.Mounts / CrewSettingsYamlConfig.Mounts (the crew-level mounts: block β€” /root or <ulid>|/root items) β†’ CrewConfiguration.Mounts (MountReference)
  • AgentYamlConfig.Filesystem (path or {path, access} items) β†’ AgentConfiguration.FileSystem (FileSystemScopeEntry); AgentYamlConfig.AnnounceMounts, else the crew's announce_mounts β†’ AgentConfiguration.AnnounceMounts
  • GraphYamlConfig (start, nodes, edges, circuitBreakerPreset and its limits) with GraphNodeYamlConfig, GraphEdgeYamlConfig
  • RagYamlConfig (collections + sources/chunking, defaults β€” with RagCollectionYamlConfig, RagChunkingYamlConfig, RagDefaultsYamlConfig) β†’ RagCrewConfig
  • AgentYamlConfig.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