Table of Contents

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

ProcessTypes comparison guide

Prerequisites: Overview and YAML and Builders


Overview

Orkeon offers 6 orchestration strategies via the ProcessType value object (Domain layer). Each strategy defines how agents coordinate to execute a Crew's tasks. The choice of ProcessType is the architectural lever with the biggest impact on the behavior of a multi-agent system.

// Orkeon.Domain.SharedKernel.ValueObjects.ProcessType (sealed record)
ProcessType.Sequential    // Linear pipeline
ProcessType.Hierarchical  // Manager + workers
ProcessType.Parallel      // Dependency waves, concurrent inside a wave
ProcessType.Consensual    // Every agent runs every task, then a vote
ProcessType.Graph         // State graph with a circuit breaker
ProcessType.Autonomous    // Self-organization under a budget

In YAML the mode is process: (case-insensitive, sequential when absent); an unknown value fails the load and names the six valid ones (YamlCrewMapper.ParseProcessType). With the Fluent Builder, CrewBuilder has .Sequential(), .Hierarchical(manager), .Parallel() and .Consensual(); Graph and Autonomous go through .Process(ProcessType.Graph) / .Process(ProcessType.Autonomous).

Implementation architecture

ICrewOrchestrationService.KickoffAsync (SequentialCrewOrchestrator)
     β”‚  planning (when enabled, held in the run's plan scope), then a switch on crew.ProcessType
     β–Ό
IProcessStrategyFactory.CreateStrategy(ProcessType)   (ProcessStrategyFactory, Infrastructure)
     β”‚
     β”œβ”€β”€ SequentialProcessStrategy      ← ExecuteSequentialAsync
     β”œβ”€β”€ HierarchicalProcessStrategy    ← ExecuteHierarchicalAsync(manager id)
     β”œβ”€β”€ ParallelProcessStrategy        ← ExecuteParallelAsync
     β”œβ”€β”€ ConsensualProcessStrategy      ← ExecuteSequentialAsync
     β”œβ”€β”€ GraphProcessStrategy           ← ExecuteSequentialAsync
     └── AutonomousProcessStrategy      ← ExecuteAutonomousAsync(crew.Budget)

IProcessStrategy (Domain) has four entry points β€” ExecuteSequentialAsync, ExecuteHierarchicalAsync, ExecuteParallelAsync, ExecuteAutonomousAsync. SequentialCrewOrchestrator picks the entry point from ProcessType.Value; Graph and Consensual reuse the sequential one, and a strategy throws NotSupportedException on the entry points it does not serve. The strategies are registered as scoped services by AddOrkeonInfrastructure() (Consensual through AddOrkeonConsensus(), which it calls).

What every strategy shares:

  • Task order β€” the modes that hand tasks out one after another (all but Parallel) run them in the order resolved by CrewTaskSequencer: a stable topological sort on the declared dependencies (detailed under Sequential). A plan never changes it, in any mode.
  • Planning β€” planning: true (YAML), .Planning(true) (C#) or crewBuilder().planning() (.ork.ts) has a planner write a step-by-step plan for each task before the first one runs, and each task reads its own plan in its prompt β€” in all six modes. The plan changes neither the order of the tasks nor who runs them. See Planning below.
  • Lifecycle hooks β€” every mode reports through ICrewExecutionHook (OnTaskStartedAsync, OnTaskCompletedAsync, OnCrewCompletedAsync, OnCrewFailedAsync), on every exit including cancellation; this is what feeds AUTO_SUMMARY.md, the orkeon run --events stream and the host's progress.
  • Outcome β€” a failed task fails the crew and skips its dependents, in every mode (detailed under Sequential): Success = false, an Error naming every failed and skipped task, a Failed hook, exit code 2.
  • Token telemetry β€” the real token usage (prompt, completion, cache hits/misses when the provider reports them) travels in the CrewOutput metadata; CrewOutput.TokensUsed stays null when nothing was measured.

Who runs a task that names no agent

A task-level agent: is a decision, not a hint: Sequential, Parallel and Graph always honour it. For a task without one, those three modes ask TaskAgentSelector, driven by OrkeonApplicationOptions.AgentSelectionStrategy:

Value Behavior
FirstFit (default) Round-robin over the crew's agents
Embedding Semantic match between the task and each agent profile (needs a real embedding provider β€” see limitations): the provider is local BGE (AddOrkeonLocalEmbeddings()), else the remote Orkeon:Embeddings configuration, else the first use fails and the task falls back to round-robin with a warning
Skill Lexical (Jaccard) match on role/goal/backstory keywords, no embedding provider

A selection that fails, or names an agent the crew does not carry, falls back to round-robin with a warning. Hierarchical and Autonomous let the manager LLM choose (a task's agent: is not consulted there); Consensual runs every task with every agent.

Planning (planning: true)

planning: true (YAML), .Planning(true) (C#) or crewBuilder().planning() (.ork.ts) β€” CrewAI's planning=True, off by default. Before the first task, a planner writes a step-by-step plan for each task, and each task then reads its own plan in its prompt.

  • On which model β€” the provider CrewBuilder.WithPlanningLlm sets (C#; it needs .Planning(): a planning provider for a crew that does not plan is refused when the crew is built), else the host's default profile β€” the Llm section: the planner stays there whatever profiles the agents name. One call per run, at temperature 0.3, metered as operation: planning in cost.updated β€” the C# provider like a provider the host registers β€”, and cancelled with the run.
  • What it reads β€” the crew's goal, a line on how the mode orders the tasks and picks their agents, the run's variables (initial_context included), and each task by number, in the order the run takes them: its description and expected output with the variables in them, as its agent reads them; its dependencies, by number; and its agent β€” role, goal, the names of the tools it holds for the task β€” where the mode runs a task on the agent it names (Sequential, Parallel, Graph). Elsewhere the planner is told what the mode does instead β€” "assigned by the manager" (Hierarchical, Autonomous), "every agent answers" (Consensual), "chosen at run time" (a task that names no agent) β€” and the crew's agents are listed once. Never an id: the planner answers by number. Bounded (PlanningDefaults): a description to 1,500 characters, an expected output to 500, an agent's goal to 300, 15 tool names per agent, the variables to 2,000 in all β€” a cut text ends with […]. No backstory, knowledge or memory.
  • What it writes β€” {"plans": [{"task": 1, "plan": "1. …"}]}: at most 8 numbered steps per task, naming the tools to use where a tool helps. The reply's shape is constrained as far as the provider can (json_schema, else json_object, else the prompt alone) and read tolerantly β€” a fence or a sentence around the object.
  • Where it goes β€” into the task's user prompt, after the task (description, expected output, deliverable) and before the context variables, under Plan for this task, from the crew's planner β€” follow it where it helps; the task above prevails:, cut at 2,000 characters. The Guardian screens it with the rest of the prompt, and each task's plan is logged on one line at Information (--verbose 1). The task itself is never changed: the knowledge query, the stored memory and the manager's prompts read the task, not its plan. The run holds its plan in a scope of its own (CrewPlanScope), read where every mode's executions compose their prompt β€” two runs of one crew never read each other's.
  • In every mode β€” Sequential, Parallel and Graph (each attempt): the task's agent. Hierarchical: the worker the manager assigns, and each revision it asks for; the manager's own prompts are unchanged. Consensual: every candidate answer β€” a ballot, a task of its own, does not. Autonomous: the agent that claims the task, and the peer it is handed to after a failure, which takes the task itself over.
  • It changes neither the order nor the agents β€” with or without a plan, a crew runs the same tasks, in the same order, on the same agents.
  • When it goes wrong β€” the plan is advice. A reply that cannot be read is asked for once more, with what could not be read, then the crew runs without a plan, with a warning β€” which says so when the reply stopped at the profile's MaxTokens. A task the plan leaves out runs without one, with a warning that names it; a number given twice keeps its first plan and an unknown number is ignored, each with a warning. Only a provider that fails β€” a refused key, an unreachable endpoint β€” fails the run, before its first task, with the provider's reason.
  • On the echo provider β€” the one a host without an Llm section runs on, which replays its prompt instead of answering it (LlmProviderCapabilities.ReplaysPrompt) β€” planning is skipped with a warning (planning skipped β€” the echo provider cannot plan, with the remedy, orkeon init), and the crew runs to the end like any keyless run.
  • Cost β€” one call per run (two after an unreadable reply), so one per input under KickoffForEachAsync and one per message in orkeon-host, its prompt growing with the crew; and each task's plan travels with every turn of that task's agent loop, which the 2,000-character bound contains.
  • Streamed too β€” a streamed run (KickoffStreamingAsync, a C# API) is the same run: it plans, and each task reads its plan, like KickoffAsync.

Key classes: CrewPlanner and PlanningContext (Domain), ExecutionPlanParser, CrewPlanScope and AgentPromptComposer.


Quick comparison matrix

Criterion Sequential Hierarchical Parallel Consensual Graph Autonomous
Execution model Linear Linear + manager review Dependency waves, concurrent inside a wave Every agent per task + peer ballots Linear, or the nodes and edges of graph: (conditional edges, loops) Manager-assigned, delegation on failure
Agent choice Declared, else selector Manager LLM Declared, else selector All agents Declared, else selector Manager LLM
Task dependencies Order + skip on failure Order + skip on failure Waves + skip on failure Order + skip on failure Order + skip on failure Order + skip on failure
A failed task fails the crew βœ… (dependents skipped) βœ… (dependents skipped) βœ… (dependents skipped) βœ… (dependents skipped) βœ… after its retries (dependents skipped) βœ… (dependents skipped; an exhausted budget too)
Circuit breaker β€” β€” β€” β€” βœ… 3 mechanisms β€”
Execution budget β€” β€” β€” β€” β€” βœ… 5 dimensions (crew budget:)
Automatic retry β€” Up to 2 re-executions after review β€” Voting rounds β€” One delegation to a peer
A task's retry: βœ… βœ… βœ… βœ… βœ… βœ…
A task's asyncExecution: true βœ… Runs alongside the next tasks Refused at load Accepted, no effect of its own Refused at load Refused at load Refused at load
Decision tasks and when conditions βœ… Refused at load βœ… Refused at load βœ… Refused at load
Manager (managerAgent:; C# WithManagerLlm) Refused at load βœ… An agent (required) or, in C#, an LLM: it assigns and reviews Refused at load βœ… An agent: the ManagerDecision arbiter (an LLM is refused) Refused at load An LLM only: the default profile, or C# WithManagerLlm (an agent is refused)
planning: true: each task reads its plan βœ… βœ… The worker, each revision βœ… βœ… Each candidate βœ… Each attempt βœ… The claimer, the peer
Complexity ⭐ ⭐⭐ ⭐ ⭐⭐⭐ ⭐⭐ ⭐⭐⭐⭐
Relative LLM cost Low Medium Low High Low to medium Medium
Main use case ETL pipelines QA, review loops Fan-out + synthesis Multiple independent attempts Flaky tasks worth retrying Exploration, R&D

Decision tasks and when conditions are described in Decision models and ADR-016: Sequential, Parallel and Graph run them, the other three modes refuse a crew that uses them when it is loaded (a crew built in C# before its first task).


1. Sequential β€” Linear pipeline

Principle

Tasks execute one by one β€” except a task with asyncExecution: true, which runs alongside the tasks after it (see Asynchronous tasks). Each task receives the outputs of the tasks that ran before it as context. Agent assignment follows the rule above: the task's agent: when declared, otherwise the configured selector (round-robin by default).

Execution order β€” with or without a plan, which never changes it: the tasks run in a stable topological order on their declared dependencies β€” a task runs after every task it depends on, and wherever the dependencies allow it the declared order is kept, so a crew that declares no dependency runs exactly as written. This holds in every layout: the multi-file layout (tasks/*.yaml) lists the tasks in the ordinal order of their file names, and the sort puts consolidate.yaml after the extract.yaml it depends on. A dependency naming an unknown task id is ignored; a cycle never fails the crew β€” the declared order is kept for the tasks caught in it and a warning names them. The same rule orders the hierarchical, consensual, graph and autonomous modes, which also hand their tasks out one after another; the parallel mode keeps its own semantics (dependency waves, and a cycle is refused).

Failure handling (every mode): a task whose declared dependency did not succeed β€” failed, or skipped in its turn β€” is skipped, never run on a context that says Task failed: … where its input should have been: it shows as ⊘ skipped in AUTO_SUMMARY.md and as a task.completed event with skipped: true, the tasks that do not depend on it still run, and the crew fails naming every failed and skipped task. The rule is the same in the six modes: a crew with a failed task returns Success = false, its hook hears Failed with the same reason, and orkeon run exits 2. A mode that tolerates a failure β€” Graph and its retries, Autonomous and its delegation β€” does so before the task counts as failed. A task whose agent loop reached its iteration cap and answered on the tool-free turn after it keeps Success and shows as ⚠ completed on its iteration cap, next to ⊘ skipped, with endedOnIterationCap: true on its task.completed event. A task that succeeds without writing its tool_call deliverable keeps Success too and shows as ⚠ completed without writing its deliverable, with deliverableMissing: true (The tool_call deliverable); a failed task never carries that flag, a Hierarchical task the manager rejected to the end included, and a Consensual task judges the file on the whole vote, so a candidate that wrote it counts whichever answer is retained. A task that did both shows as ⚠ completed on its iteration cap without writing its deliverable. A peer takeover in Autonomous mode carries the deliverable flag and path back (AgentChannelResponse.DeliverableMissing, AgentChannelResponse.DeliverablePath); a channel answered by a script's agent-command handler runs no end-of-task check and answers deliverableMissing: false. The cap flag is carried in every mode, a peer takeover in Autonomous mode included (AgentChannelResponse.EndedOnIterationCap, experimental ORKEXP002); the one exception is a channel answered by a script's agent-command handler, which has no cap information and answers false. delegate_work returns ended_on_iteration_cap for a coworker that ended on its cap. An empty answer on the last allowed iteration takes the same path, and a typed result carries the tokens, the cache tokens, the iterations, the retries and the end date. The native tool-calling and legacy text fallback loops have no tool-free turn: they end on the cap without the flag.

Asynchronous tasks (asyncExecution)

A task with asyncExecution: true β€” CrewAI's async_execution; .Async() on CrewTaskBuilder, .asyncExecution() in a script β€” is launched without being waited for: the next task starts at once, and both run together.

  • A task that depends on it waits for it β€” through dependencies:, the equivalent of CrewAI's context β€” then reads its output; if it failed, that task is skipped like any dependent of a failed task.
  • Its output enters the context once a task has waited for it: a task that does not depend on it starts without it, and every task after that wait reads it, in declared order β€” what a task reads never depends on timing. A task that needs it declares it.
  • The crew waits for every task it launched before it reports β€” nothing outlives the run β€”, and its output stays the last declared task's, not the last one to finish; CrewOutput.TaskOutputs lists the tasks in declared order.
  • A failure is the rule of every mode: the crew fails and the task's dependents are skipped; the tasks already running go to their end, nothing is cancelled in cascade. A cancelled run waits for them to stop, then cancels them.
  • The task starts (TaskStartedEvent, task.started) when it is launched and ends (TaskCompletedEvent or TaskFailedEvent) when the run waits for it; the end hook β€” AUTO_SUMMARY.md, task.completed β€” hears each task as it finishes, in the order the tasks finish. A coworker it delegates to works in its context. There is no concurrency cap: two asynchronous tasks call their LLM at the same time.
process: sequential
tasks:
  research:
    description: "Research the market"
    expectedOutput: "Market findings"
    asyncExecution: true
  survey:
    description: "Survey the customers"
    expectedOutput: "Survey results"
    asyncExecution: true               # runs together with research
  synthesis:
    description: "Write the recommendation"
    expectedOutput: "Recommendation"
    dependencies: [research, survey]   # waits for both, reads both

process: parallel accepts asyncExecution: true without an effect of its own β€” every task of a wave already runs at once. Hierarchical, Consensual, Graph and Autonomous order their tasks themselves (the manager, the vote, the graph, the budget): a crew that sets asyncExecution: true there is refused at load, naming each task, in YAML as in a .ork.ts script, and CrewBuilder.Build() refuses the same in C#. asyncExecution: false, the default, loads everywhere.

Internal mechanism

Task 1 β†’ Agent A β†’ output₁
                      ↓ (enriched context)
Task 2 β†’ Agent B β†’ outputβ‚‚
                      ↓
Task 3 β†’ Agent C β†’ output₃ β†’ final result

Key classes: SequentialProcessStrategy, CrewTaskSequencer, TaskAgentSelector, AgentDelegationToolsProvider (agents with allowDelegation: true receive delegate_work_to_coworker and ask_question_to_coworker)

YAML configuration

# Flat root β€” there is no crew: wrapper key (a crew: key is refused at load as
# unknown), and agents:/tasks: are mappings keyed by id.
name: "pipeline"
goal: "Sequential demo"
process: sequential
tasks:
  collect:
    description: "Collect the data"
    expectedOutput: "Raw data"
  analyze:
    description: "Analyze the data"
    expectedOutput: "Analysis report"
    dependencies: [collect]
  recommend:
    description: "Generate the recommendations"
    expectedOutput: "Action plan"
    dependencies: [analyze]

Fluent Builder configuration

var crew = new CrewBuilder()
    .Sequential()
    .WithAgent(a => a.Role("Collector").Goal("Gather data"))
    .WithAgent(a => a.Role("Analyst").Goal("Analyze data"))
    .WithTask(t => t.Description("Collect").ExpectedOutput("Raw data"))
    .WithTask(t => t.Description("Analyze").ExpectedOutput("Report"))
    .Build();

Advantages

  • Maximum simplicity: no complex configuration, predictable behavior
  • Traceability: each step is clearly identifiable in the logs
  • Cumulative context: each task benefits from the previous results
  • Honest outcome: a failed step fails the crew and stops its dependents (as in every mode)

Drawbacks

  • Little parallelism: the total time is the sum of the tasks, except those marked asyncExecution
  • Single point of failure: one failure blocks the rest of the chain β€” its dependents are skipped, only the independent tasks still run
  • No retry of its own: a task asks for attempts with retry:; nothing is retried otherwise
  • Rigid: the order is fixed, no conditional branching

When to use it

  • ETL pipelines (extract β†’ transform β†’ load)
  • Sequential writing (research β†’ drafting β†’ proofreading)
  • Workflows where each step strictly depends on the previous one
  • Rapid prototyping and POCs

When not to use it

  • Many independent tasks that could all run in parallel β€” Parallel runs each dependency wave at once; asyncExecution suits a few concurrent steps of a pipeline

2. Hierarchical β€” Manager + Workers

Principle

A manager (IManagerAgent, implemented by LlmBasedManager) coordinates the workers. For each task it picks a worker via AssignTaskAsync(), the worker executes, then the manager reviews the output with ReviewOutputAsync().

  • The crew names its manager: managerAgent: in YAML (crewBuilder().manager(agent) in .ork.ts, .Hierarchical(manager) / .WithManager(agent) in C#) β€” that agent is removed from the worker pool. In C#, .WithManagerLlm(provider) (CrewAI's manager_llm) gives the manager a provider of its own: such a crew needs no manager agent, and every agent is then a worker. A crew with neither is refused when it is built, and a managerAgent: that names no agent of the crew fails the load, listing its agents.
  • A manager means something in two other places only: a manager agent arbitrates a Consensual crew's vote, a manager LLM hands an Autonomous crew's tasks out. Sequential, Parallel and Graph have no manager, Autonomous no manager agent and Consensual no manager LLM: such a crew is refused when it is loaded or built, the message naming the key and the mode β€” the agent would only have been one more worker, the provider never called.
  • The manager's decisions go through the LLM the crew gives it, resolved once per run: the provider WithManagerLlm set (C#; metered like a provider the host registers), else the provider the manager agent carries itself (C#: .WithLlm(provider), or a Microsoft Agent Framework agent through .WithAgentFrameworkAgent(agent); metered the same way, named provider:<name>), else the manager agent's own llm: block β€” its profile and model, a model left unset being the profile's own (llm: { profile: claude }) β€” else the host's default profile. A profile the host does not offer fails the crew load, like any agent's. The calls are metered under the manager's role (operation: manager). YAML has no manager_llm key: the manager agent's llm: block is the way.
  • Assignment: the manager LLM answers with JSON; an unparseable answer falls back to a role/keyword heuristic, an LLM error to the first worker. A task's agent: is not consulted.
  • Review: up to 3 reviews per task, so at most 2 re-executions (each with a revision_feedback context variable). A third rejection keeps the last output, prefixed [NEEDS REVISION] and marked failed β€” and the task fails the crew. A review that errors counts as an approval.
  • A task assigned to an agent the crew does not carry never runs, and fails the crew. A task whose dependency failed is skipped without asking the manager.

What the crew remembers (memory: true): the output the manager accepted, once, under the agent it was assigned to β€” never a rejected attempt. Each attempt runs with SimpleExecutionContext.StoreResultInMemory off (it still recalls the crew's memories: it answers the task), and the strategy stores the accepted output through IMemoryCoordinator. Nothing is stored when the manager rejects all three attempts, nor when the worker fails; a review that errors counts as an acceptance, so that output is stored. See Memory system.

Internal mechanism

                  β”Œβ”€ Manager (crew's LLM) ───┐
                  β”‚   AssignTaskAsync()       β”‚
                  β”‚   ReviewOutputAsync()     β”‚
                  β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                           β”‚
            β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
            β–Ό              β–Ό              β–Ό
        Worker A       Worker B       Worker C
        (chosen)
            β”‚
            β–Ό
        Output β†’ Review β†’ approved? β†’ yes β†’ next task
                           β†’ no β†’ re-execute (max 2), then [NEEDS REVISION]

Key classes: HierarchicalProcessStrategy, IManagerAgent, LlmBasedManager, TaskAssignment (TaskId, AssignedAgent, Reason, AssignedAt)

IManagerAgent interface (Orkeon.Application.Interfaces):

  • AssignTaskAsync(task, availableAgents, context, llm, cancellationToken) β†’ TaskAssignment
  • ReviewOutputAsync(output, originalTask, llm, cancellationToken) β†’ bool (approved or not); the token is the run's: Ctrl+C, RunTimeout and /stop stop a review

llm is the ManagerLlm the strategy resolved for the run (ManagerLlmResolver): the chat client the manager asks, the model it asks for, and its name in the log (provider:<name> or profile:<name>). Each of its calls first waits its turn in the manager agent's maxRpm window and in the crew's.

YAML configuration

name: "delivery-team"
goal: "Hierarchical demo"
process: hierarchical
managerAgent: lead          # the key of the managing agent under agents: (there is no manager_llm key)
llm:                        # crew-default LLM applied to agents without their own
  model: gpt-4o
agents:
  lead:
    role: "Tech Lead"
    goal: "Coordinate the delivery"
    llm:                    # the manager assigns and reviews on this LLM:
      profile: claude       # one of the host's profiles (Llm:Profiles:claude),
      model: claude-sonnet-5  # on this model (unset, the crew's gpt-4o would apply)
  dev:
    role: "Senior Developer"
    goal: "Write production code"
  qa:
    role: "QA Engineer"
    goal: "Test and validate"

Advantages

  • Smart allocation: the manager picks the worker best suited to each task
  • Built-in quality control: automatic review loop
  • Traceability: every assignment carries a justification (TaskAssignment.Reason)

Drawbacks

  • Extra LLM cost: one assignment call + one to three review calls per task, on top of the workers
  • Bottleneck: everything goes through the manager (no parallelism)
  • Fixed revisions: 3 reviews per task, hardcoded

When to use it

  • Code review (the manager assigns the most competent reviewer)
  • Projects with heterogeneous specialists (dev, QA, design, writing)
  • Situations where quality matters more than speed

When not to use it

  • Homogeneous tasks (round-robin is enough)
  • Strict LLM cost constraints
  • High-frequency workflows (the manager is a bottleneck)

3. Parallel β€” Dependency waves

Principle

Tasks are grouped into dependency waves. A wave holds every task whose declared dependencies are already satisfied; its tasks run concurrently (Task.WhenAll), and the next wave starts when they are all done, reading their outputs as context. A crew declaring no dependency is a single wave β€” one flat fan-out.

  • A dependency naming a task the crew does not carry counts as satisfied.
  • A dependency cycle is refused: the run fails naming the tasks caught in it.
  • A failed task does not stop its wave siblings; its dependents in the next waves are skipped, and the crew fails naming every failed and skipped task.
  • There is no concurrency cap: every task of a wave calls its LLM at the same time.
  • A task's asyncExecution: true is accepted and changes nothing: its wave already runs at once.

Internal mechanism

Wave 1 ──┬── Task A β†’ Agent 1 ──┐
         └── Task B β†’ Agent 2 ───  (concurrent)
                                β–Ό
Wave 2 ────── Task C (depends on A, B) β†’ reads A + B β†’ final result

Key classes: ParallelProcessStrategy, TaskAgentSelector

YAML configuration

name: "market-scan"
goal: "Parallel demo"
process: parallel
tasks:
  france:
    description: "Analyze the French market"
    expectedOutput: "France report"
  germany:
    description: "Analyze the German market"
    expectedOutput: "Germany report"
  synthesis:
    description: "Compare the two markets"
    expectedOutput: "Comparative summary"
    dependencies: [france, germany]   # second wave, reads both reports

Advantages

  • Speed: total time = sum of the longest task of each wave
  • Simplicity: no coordination beyond the declared dependencies
  • Isolation: one task's failure does not impact its wave siblings

Drawbacks

  • Coarse ordering: a task waits for its whole wave, not only for what it declared
  • API consumption spikes: all the LLM requests of a wave fire at once (rate limiting)
  • No retry unless the task asks: a failed task with no retry: fails the crew, and skips what depends on it

When to use it

  • Independent multi-market or multi-source analyses
  • Batch content generation (one article per market, per language)
  • A fan-out followed by a synthesis: the collectors run together, the synthesis reads them

When not to use it

  • Retry of flaky tasks (give the task a retry:, in any mode)
  • APIs with strict rate limiting

4. Consensual β€” Voting and consensus

Principle

For each task, every agent of the crew executes it (concurrently). Then every agent casts a ballot: it ranks the other agents' successful answers, anonymised under labels (A, B, …). The configured IVotingStrategy tallies the ballots. If no consensus is reached and EnableDiscussion is on, another round runs where each agent sees the others' previous answers (a discussion_context context variable). After MaxVotingRounds rounds without consensus, the FallbackStrategy decides.

Internal mechanism

Task N ──┬── Agent A β†’ answer A ──┐                β”Œβ”€β”€ A ranks the answers of B, C ──┐
         β”œβ”€β”€ Agent B β†’ answer B ──┼── labels A,B,C ┼── B ranks the answers of A, C ──┼── Tally ── Consensus? ── yes β†’ winning answer
         └── Agent C β†’ answer C β”€β”€β”˜                └── C ranks the answers of A, B β”€β”€β”˜                β”‚
                                                                                                    no
                                                                                                     ↓
                                                                     Next round (with discussion_context)
                                                                                                     ↓
                                                                   Rounds exhausted β†’ FallbackStrategy

Registration: AddOrkeonConsensus() (Orkeon.Infrastructure.DependencyInjection) binds ConsensualProcessOptions to the Orkeon:Consensus section, registers IVotingStrategyFactory β†’ VotingStrategyFactory and the IVotingStrategy built from the configured ConsensusType (singletons, TryAdd), IBallotCollector β†’ AgentBallotCollector (scoped), and ConsensualProcessStrategy (scoped). AddOrkeonInfrastructure() already calls it β€” call it yourself only in a host that does not use AddOrkeonInfrastructure(); registering your own IVotingStrategy or IBallotCollector before it replaces the default one.

Key classes: ConsensualProcessStrategy, IBallotCollector / AgentBallotCollector, BallotRequest, BallotCandidate, Ballot, IVotingStrategy, IVotingStrategyFactory / VotingStrategyFactory, Vote, VoteResult, VotingOptions, ConsensualProcessOptions, ConsensusFallback

How a ballot is formed

  • Candidates: only the executions that succeeded. A failed execution is never a candidate β€” its agent still votes, on every answer. A lone successful answer is kept without a ballot; when every execution of a round failed, the task fails with the agents' error, without another round.
  • Anonymised: the answers carry labels A, B, … in an order shuffled per task and per round (deterministic: the same run gives the same labels). A voter sees neither the authors' roles nor their ids, so it votes on the answer, not on the agent.
  • No vote for oneself: an agent ranks the other agents' answers, never its own. A choice's share is therefore counted among the ballots that could name it (Vote.OwnChoice): three agents that give the same answer reach Majority, SuperMajority and Unanimity in round one.
  • Who casts it: the voting agent itself, through IAgentExecutionService β€” its own LLM configuration, and its tokens counted in the task's telemetry. It is asked for a JSON object (response format json_object): {"ranking": ["B", "A"], "abstain": false, "confidence": 0.8, "justification": "…"}. A reply that is not that object, a ranking that names no offered label, a ballot execution that failed, or "abstain": true is an abstention: it is logged and never fails the task.
  • What is counted: Majority, SuperMajority, Unanimity and WeightedConsensus count the first choice; BordaCount counts the whole ranking. The ballot's confidence is read with UseWeightedVotes.
  • Ties: a tie at the top is no consensus. Two agents can only name each other, so their vote always ties β€” a consensual crew needs three agents or more to decide by vote.
  • The manager: a crew's managerAgent (.manager(agent) in .ork.ts, CrewBuilder.WithManager in C#) neither answers nor votes; it only arbitrates under ManagerDecision. Under another fallback β€” AcceptBestScore, the default, or Fail β€” it decides nothing, and the run says so with a warning at its start that names the agent and the host's fallback: set Orkeon:Consensus:FallbackStrategy: ManagerDecision, or remove managerAgent: so that the agent answers and votes. A consensual crew reads no manager LLM: C# WithManagerLlm is refused.

Fallbacks, after MaxVotingRounds rounds without consensus:

  • AcceptBestScore keeps the answer the last count put first, without running anything again. When no ballot of that round named an answer (every voter abstained), the task fails.
  • ManagerDecision: the crew's manager agent ranks the last round's answers, anonymised like the peers saw them, and its first choice is kept; if it abstains, the task fails. A crew without a manager agent is refused at kickoff, before any agent runs, with a message that names the fix (the fallback is a host setting, so the YAML validator cannot see it).
  • Fail fails the task ("Consensus could not be reached for task …").

The retained result is the task's result: when it failed, the crew fails and the task's dependents are skipped; the tasks that do not depend on it still run.

What the crew remembers: the retained answer, once, under the agent that wrote it β€” never a candidate the vote rejected, never a ballot. The candidates and the ballots run with SimpleExecutionContext.StoreResultInMemory off (AgentBallotCollector turns it off for any ballot it casts), and the strategy stores the retained answer through IMemoryCoordinator; a task without a retained answer stores nothing. A candidate recalls the crew's memories before answering β€” it answers the task β€” and a ballot does not (RecallFromMemory off). When the store fails, the retained answer stays the task's result and the failure is a warning, as in the other modes. See Memory system.

Cost: a round costs N executions plus N ballots β€” one short LLM call per voter, whose prompt holds the answers under review, so its input grows with N Γ— the answers' length (a long answer is truncated to fit a task description). Three agents that agree cost 3 executions + 3 ballots per task. A task that never reaches consensus costs MaxVotingRounds Γ— (N + N) calls, plus one manager ballot under ManagerDecision; AcceptBestScore re-runs nothing. The crew's input variables reach every execution and every ballot; earlier tasks' winning outputs are passed as context.

name: review-board
process: consensual
managerAgent: chair             # the arbiter under FallbackStrategy: ManagerDecision (idle, with a warning, under another fallback)

Available consensus types

The voting mechanism is selectable via configuration: Orkeon:Consensus:VotingOptions:ConsensusType (.NET appsettings.json) picks the strategy through IVotingStrategyFactory. Default: Majority. Every type also requires the quorum (QuorumPercent) and a single leading answer; a share is counted among the ballots that could name the answer.

Type Resolved strategy Consensus rule Default threshold
Majority MajorityVotingStrategy Leading share strictly above 50% 50%
SuperMajority SuperMajorityVotingStrategy Leading share β‰₯ ConsensusThreshold 66.7%
Unanimity UnanimityVotingStrategy Every ballot that could name the winner named it 100%
WeightedConsensus WeightedConsensusStrategy Role weight (RoleWeights) Γ— confidence, share above ConsensusThreshold 66.7%
BordaCount BordaCountStrategy Best Borda score over the full rankings; no consensus on a tie at the top N/A

Configuration (.NET, Orkeon:Consensus section)

{
  "Orkeon": {
    "Consensus": {
      "MaxVotingRounds": 3,
      "VotingOptions": {
        "ConsensusType": "SuperMajority",
        "ConsensusThreshold": 75,
        "UseWeightedVotes": true,
        "QuorumPercent": 50,
        "AllowAbstention": true
      },
      "EnableDiscussion": true,
      "FallbackStrategy": "AcceptBestScore",
      "RoleWeights": {
        "Senior Analyst": 2.0,
        "Junior Analyst": 1.0
      }
    }
  }
}
Key Default Effect
MaxVotingRounds 3 Rounds before the fallback; a round is N executions + N ballots
VotingOptions:ConsensusType Majority Voting strategy
VotingOptions:ConsensusThreshold 66.7 Threshold of SuperMajority / WeightedConsensus, as a percentage (0–100) β€” 75% is written 75
VotingOptions:UseWeightedVotes false Weight Γ— the ballot's confidence instead of one vote per ballot
VotingOptions:QuorumPercent 50 Minimum share, in percent, of expressed ballots (not abstentions) among the voters; below it, no consensus
VotingOptions:AllowAbstention true false: an abstention counts as a vote against every answer β€” it stays in every share's denominator and breaks unanimity; with BordaCount, any abstention prevents consensus
EnableDiscussion true Rounds after the first see the other agents' answers
FallbackStrategy AcceptBestScore AcceptBestScore (the last count's leader, nothing re-run), Fail, ManagerDecision (the crew's manager agent chooses; required)
RoleWeights empty Role β†’ weight, read by WeightedConsensus

Advantages

  • Several independent attempts per task, run concurrently
  • A vote on the answers: every agent ranks the others' answers, anonymised; a failed attempt is never retained
  • Configurable voting: 5 strategies, quorum, abstention, role weighting
  • Discussion: agents see each other's answers between rounds

Drawbacks

  • High LLM cost: N executions + N ballots per task and round (+ one manager ballot under ManagerDecision)
  • The judges are LLMs: a ballot is a model's opinion; a blind spot every agent's model shares is not corrected by the vote
  • Two agents always tie: the vote decides from three agents up
  • Configuration complexity: many parameters

When to use it

  • Tasks where independent attempts by several agents are worth their cost
  • Crews where one agent's failure should be absorbed by the others (a failed answer is never a candidate)

When not to use it

  • Factual tasks with a single correct answer
  • LLM budget constraints (multiplied by 2 Γ— N agents Γ— R rounds: answers and ballots)
  • High-frequency workflows (too slow)

5. Graph β€” State graph with a circuit breaker

Principle

The crew runs through a typed state graph (StateGraph<CrewGraphState>) with one node per task (ADR-018): without nodes or edges the nodes are chained in execution order, and a task's attempts are its own retry: (applied below the strategy), not a loop of its node. A 3-mechanism circuit breaker bounds the loop. The graph: block can declare its own nodes and edges β€” conditional edges on a decision task's answers, and loops (see Graph orchestration).

Internal mechanism

START ──→ task 1 ──→ task 2 ──→ … ──→ last task ──→ END

Key classes:

  • StateGraph<TState> β€” Graph definition (nodes + fixed and conditional edges)
  • GraphRunner<TState> β€” Execution engine with circuit breaker
  • GraphProcessStrategy β€” IProcessStrategy implementation
  • CircuitBreakerPolicy β€” Limits (the record shared with the FSM)
  • CrewGraphState β€” Typed state flowing through the graph

CrewGraphState β€” State properties

Property Type Description
ApplicationOutputs / DomainResults IReadOnlyList<…> Accumulated outputs, one per attempt
TotalTokensUsed int Consumed tokens (propagated to the CrewOutput metadata under totalTokens)
PromptTokensUsed / CompletionTokensUsed int Prompt/completion split (0 when the provider does not report it)
CacheHitTokensUsed / CacheMissTokensUsed long Prompt-cache split (0 when unreported)
AgentIndex int Round-robin cursor for tasks without an agent

Circuit breaker β€” 3 protection mechanisms

Mechanism Computed (default) Strict preset Default preset Permissive preset
MaxTransitions (node executions) 2 Γ— visits + 1 50 100 1000
MaxStateVisits (visits of one node) sum of 1 + retries 5 10 50
MaxTotalDuration the preset's (10 min under Strict) 10 min 30 min 2 h

Every entry into a node is one visit of it, counted per node (maxVisits). Without an explicit maxVisits / maxTransitions, both are computed from the crew: the sum over the tasks of 1 + retries visits (the attempts of each task's retry:; tasks Γ— (1 + retries) when they are alike) β€” a loose bound: a node is entered once, its attempts happen inside the visit β€” and twice that plus one transitions, so a healthy crew is never cut short whatever its size, and a real loop still trips the breaker. An explicit value wins (in the graph: block); the preset (circuitBreakerPreset, Strict when absent) then only supplies what is not computed, the total duration first. The FSM's fourth mechanism, the per-state timeout, is not checked by the graph runner. A tripped breaker returns a failed CrewOutput ("Graph execution stopped by circuit breaker: …") with the outputs produced so far.

YAML configuration

name: "review-loop"
goal: "Graph demo"
process: graph
graph:
  nodes:                           # optional: without nodes and edges, one node per task
    - { id: write,   task: write }
    - { id: review,  task: review }     # a decision task: edges leave it on its answers
    - { id: publish, task: publish }
  edges:
    - { from: write,  to: review }
    - { from: review, to: write, when: { review.verdict: [revise] } }
    - { from: review, to: publish }     # no `when`: the otherwise
    - { from: publish, to: END }
  circuitBreakerPreset: "strict"   # or "default", "permissive" β€” supplies the duration
  # Individual overrides possible (visits and transitions are computed otherwise):
  maxTransitions: 75
  maxVisits: 20
  maxTotalDurationSeconds: 1800

A loop is an edge leading back to a node; maxVisits bounds it. See Graph orchestration and the YAML schema for the rules (one "otherwise" edge per decision, no task-level when: or dependencies: beside nodes).

Advantages

  • Retry: a task's own retry: runs before the next task starts, as in every mode
  • Safety: a circuit breaker bounds executions, visits and duration
  • Observability: OnNodeEntered / OnNodeCompleted / OnCircuitBroken events, logged by the strategy; a graph.node.entered run event per node entered
  • Bounds sized to the crew: visits and transitions computed from the task count and the retries

Drawbacks

  • 10-minute default duration: the Strict preset's MaxTotalDuration still bounds the run β€” raise maxTotalDurationSeconds for a long crew
  • YAML routing on decisions only: a conditional edge leaves a decision task on its answers; a routing function needs the C# StateGraph<TState> API

When to use it

  • Pipelines with flaky steps worth retrying (web scraping, unstable APIs)
  • Runs that must be bounded in executions and duration

When not to use it

  • Simple linear pipelines with no step worth retrying (Sequential)
  • Independent tasks (Parallel)

See also: Graph orchestration for the full details.


6. Autonomous β€” Self-organization with budget

Principle

For each task, the manager LLM (LlmBasedManager, as in Hierarchical β€” on the provider CrewBuilder.WithManagerLlm sets in C#, else on the host's default profile: an autonomous crew has no manager agent, and managerAgent: is refused at load) picks the agent that claims it. When that agent's execution fails and the agent allows delegation, the task is delegated to a peer over the A2A channel (IAgentChannel), under a derived child budget. With no peer in the crew, the failure stands. A multi-dimensional budget (5 axes) bounds the run. The API is experimental (ORKEXP002, see experimental APIs).

Internal mechanism

                    β”Œβ”€β”€β”€ AgentExecutionBudget (5 dimensions) ───┐
                    β”‚  tool calls Β· depth Β· wall time            β”‚
                    β”‚  tokens Β· spawned agents                   β”‚
                    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                       β”‚
for each task:  Manager (LLM) ── assigns ──→ Agent A ── executes
                                       β”‚
                          failed + allowDelegation?
                                       β”‚ yes
                                       β–Ό
                  channel.RequestAsync("delegate") ──→ first other agent
                                                        (child budget)

Key classes:

  • AutonomousProcessStrategy β€” Orchestration strategy
  • AgentExecutionBudget β€” Multi-dimensional budget (Domain)
  • IAgentChannel / InMemoryAgentChannel β€” A2A request/response channel
  • SpawnAgentTool β€” Dynamic agent creation (host-constructed, not injected by the strategy)
  • BudgetExhaustedException β€” Thrown when an axis is exhausted

Multi-dimensional budget β€” 5 axes

Dimension Strict Default Permissive Description
MaxToolCalls 8 15 50 Tool calls; the strategy counts one per task handed out
MaxDelegationDepth 1 2 4 Delegation hops; the crew-wide counter is never decremented
MaxTokensConsumed 8,000 16,000 64,000 Tokens recorded against the budget (delegated executions)
MaxSpawnedAgents 1 3 10 Agents created through SpawnAgentTool
MaxWallTime 2 min 5 min 15 min Maximum execution duration

A sixth limit, MaxContextTokens (no limit by default), counts tokens with the context counted once and is reported under the Tokens dimension; the autonomous strategy never sets it: the crew budget: YAML has no key for it and an autonomous crew's .ork.ts budget refuses contextTokens (see Autonomous).

ICrewOrchestrationService runs this mode under the crew's budget (YAML budget:); a crew that sets none has no token cap and no wall time, and keeps the structural limits of 50 tasks handed out, 4 delegations and 10 spawns.

Child budgets: CreateChildBudget() gives the delegate the parent's remaining allowance on each axis (one less delegation level, at least 1 tool call and 100 tokens). Each child budget is an independent copy: two delegates each receive the full remainder.

A2A communication

// Request/Response (default timeout: 30 s)
var request = AgentChannelRequest.Create(
    from: analyst.Id,
    to: researcher.Id,
    intent: "find_data",
    payload: "2025 market statistics");

var response = await channel.RequestAsync(request, timeout: TimeSpan.FromSeconds(30));

// Broadcast (no response expected) to the members registered for that crew
await channel.BroadcastAsync(analyst.Id, crew.Id, "Results available", ct);

YAML configuration

name: "research-team"
goal: "Autonomous demo"
process: autonomous
budget:                   # optional; every key optional, each 1 or more
  tokens: 400000          # running sum of prompt + completion; none by default
  wallTimeSeconds: 1800   # none by default
  toolCalls: 80           # tasks handed out; 50 by default

Advantages

  • LLM-driven assignment: the manager matches each task to an agent
  • Second chance: a failed task is handed to a peer
  • Guaranteed termination: the budget bounds the run β€” the tasks handed out always, tokens and wall time when the crew sets them
  • Budget telemetry: the crew metadata carries the consumption of each axis

Drawbacks

  • Experimental: ORKEXP002, semantics may still move
  • Non-deterministic: the manager's choices vary between runs
  • Budget exhausted = run cut short: the remaining tasks are not executed, and the crew fails naming the exhausted dimension and every task it never reached
  • No token or time cap by default: a crew that must stay within a spend sets budget:

When to use it

  • Exploration (research, R&D, exploratory analysis)
  • Heterogeneous teams where the task-to-agent match is not known in advance

When not to use it

  • Deterministic, well-defined workflows (Sequential or Graph)
  • Regulatory scenarios requiring full traceability of the execution path

See also: Autonomous orchestration for the full details.


Decision tree

Do your tasks have dependencies between them?
β”‚
β”œβ”€β”€ NO
β”‚   └── Do you want several agents to attempt each task?
β”‚       β”œβ”€β”€ YES β†’ Consensual
β”‚       └── NO β†’ Parallel
β”‚
└── YES
    └── Is concurrency all you need β€” independent tasks together, each wave after its dependencies?
        β”œβ”€β”€ YES β†’ Parallel (it runs by dependency waves)
        └── NO
            └── Must the run follow decision edges, be bounded, or hand a failed task to a peer?
                β”‚
                β”œβ”€β”€ NO
                β”‚   └── Do you need a manager to assign and review?
                β”‚       β”œβ”€β”€ YES β†’ Hierarchical
                β”‚       └── NO β†’ Sequential
                β”‚
                └── YES
                    └── Decision edges and bounds, or a peer?
                        β”œβ”€β”€ Decision edges, bounded β†’ Graph
                        └── A peer, LLM-assigned β†’ Autonomous

Combinations and complementarity

ProcessTypes are exclusive at the scale of one crew, but they combine with the other building blocks:

Sequential/Graph + delegation tools: in these two modes, an agent with allowDelegation: true receives delegate_work_to_coworker and ask_question_to_coworker, giving a local hierarchical behavior without a manager.

Graph + FSM: GraphProcessStrategy and the FSM engine share CircuitBreakerPolicy and its presets. The FSM is a generic Domain engine (orkeon forge runs on it); no strategy runs a task through a state machine β€” the agent loop bounds each task.

Scripting DSL: a .ork.ts crew declares its mode with crewBuilder().process("…") (the same six values). The declarative shape (globalThis.crew = crew) runs through the strategies above; the procedural shape (await crew.run()) runs agent bodies in declaration order and only tags the mode β€” see Scripting.


Cost and performance summary

ProcessType Executions (N tasks, M agents) Extra LLM calls Latency Predictability
Sequential N β€” Ξ£(durations) ⭐⭐⭐⭐⭐
Hierarchical N Γ— (1 to 3) N assignments + N Γ— (1 to 3) reviews Ξ£(durations) Γ— 1.5–3 ⭐⭐⭐⭐
Parallel N β€” Ξ£(longest task of each wave) ⭐⭐⭐⭐
Consensual N Γ— M Γ— rounds N Γ— M Γ— rounds ballots (+ N manager ballots under ManagerDecision) Ξ£((max(durations) + max(ballot durations)) Γ— rounds) ⭐⭐⭐
Graph N Γ— (1 + retries) β€” Ξ£(durations of the attempts) ⭐⭐⭐⭐
Autonomous N (+ delegations) N assignments Bounded by the wall time ⭐⭐

Cross references

Topic Document
Architecture and core concepts Overview
Detailed features YAML and Builders
YAML schema (process, graph) YAML schema
FSM (generic Domain engine) ./fsm.md
Graph orchestration ./graph.md
Autonomous orchestration ./autonomous.md
Blueprint for a new ProcessType ../guides/blueprint.md