π«π· 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 declareddependencies(detailed under Sequential). A plan never changes it, in any mode. - Planning β
planning: true(YAML),.Planning(true)(C#) orcrewBuilder().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 feedsAUTO_SUMMARY.md, theorkeon run --eventsstream and the host's progress. - Outcome β a failed task fails the crew and skips its dependents, in every mode (detailed under Sequential):
Success = false, anErrornaming every failed and skipped task, aFailedhook, exit code 2. - Token telemetry β the real token usage (prompt, completion, cache hits/misses when the provider reports them) travels in the
CrewOutputmetadata;CrewOutput.TokensUsedstaysnullwhen 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.WithPlanningLlmsets (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 β theLlmsection: the planner stays there whatever profiles the agents name. One call per run, at temperature 0.3, metered asoperation: planningincost.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_contextincluded), 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, elsejson_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
Llmsection 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
KickoffForEachAsyncand one per message inorkeon-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, likeKickoffAsync.
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'scontextβ 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.TaskOutputslists 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 (TaskCompletedEventorTaskFailedEvent) 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;
asyncExecutionsuits 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'smanager_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 amanagerAgent: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
WithManagerLlmset (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, namedprovider:<name>), else the manager agent's ownllm: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 nomanager_llmkey: the manager agent'sllm: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_feedbackcontext 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)βTaskAssignmentReviewOutputAsync(output, originalTask, llm, cancellationToken)βbool(approved or not); the token is the run's: Ctrl+C,RunTimeoutand/stopstop 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: trueis 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 reachMajority,SuperMajorityandUnanimityin 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 formatjson_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": trueis an abstention: it is logged and never fails the task. - What is counted:
Majority,SuperMajority,UnanimityandWeightedConsensuscount the first choice;BordaCountcounts the whole ranking. The ballot'sconfidenceis read withUseWeightedVotes. - 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.WithManagerin C#) neither answers nor votes; it only arbitrates underManagerDecision. Under another fallback βAcceptBestScore, the default, orFailβ it decides nothing, and the run says so with a warning at its start that names the agent and the host's fallback: setOrkeon:Consensus:FallbackStrategy: ManagerDecision, or removemanagerAgent:so that the agent answers and votes. A consensual crew reads no manager LLM: C#WithManagerLlmis refused.
Fallbacks, after MaxVotingRounds rounds without consensus:
AcceptBestScorekeeps 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).Failfails 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 breakerGraphProcessStrategyβIProcessStrategyimplementationCircuitBreakerPolicyβ 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/OnCircuitBrokenevents, logged by the strategy; agraph.node.enteredrun 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
MaxTotalDurationstill bounds the run β raisemaxTotalDurationSecondsfor 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 strategyAgentExecutionBudgetβ Multi-dimensional budget (Domain)IAgentChannel/InMemoryAgentChannelβ A2A request/response channelSpawnAgentToolβ 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 |