π«π· Version franΓ§aise
See also: ProcessTypes comparison guide Β· YAML schema Β· Back to index
Autonomous agentic orchestration
Overview
Orkeon provides an autonomous orchestration mode (ProcessType.Autonomous): for each task, a manager LLM picks the agent that claims it; when that agent fails and allows delegation, the task is handed to a peer over an agent-to-agent channel. All execution is constrained by a multi-dimensional AgentExecutionBudget that guarantees termination.
Experimental API. The budget types,
IAgentChanneland its records,AutonomousProcessStrategyandSpawnAgentToolcarry[Experimental("ORKEXP002")]: code that uses them must acknowledge the diagnostic (see experimental APIs). Running a YAML crew withprocess: autonomousneeds nothing.
Unlike the Sequential mode, where the declared order and the task's agent: decide, the Autonomous mode lets the manager LLM decide who does what, and gives a failed task a second chance with a peer. The orchestrator enforces the budget and collects the results.
Positioning relative to the other strategies
| Strategy | Routing decision | Delegation | Dynamic spawn | Multi-dimensional budget | A2A communication |
|---|---|---|---|---|---|
| Sequential | Declared agent, else selector | Via delegate_work_to_coworker (agents with allowDelegation) |
No | No | No |
| Hierarchical | Manager LLM | No (manager review instead) | No | No | No |
| Graph | Declared agent, else selector | Via delegate_work_to_coworker |
No | No (circuit breaker) | No |
| Autonomous | Manager LLM | On failure, to a peer (bounded depth) | Via SpawnAgentTool (host-registered) |
Yes (5 dimensions) | Request/Response |
Architecture
Domain layer β Execution budget
| Class | File | Role |
|---|---|---|
AgentExecutionBudget |
Autonomous/AgentExecutionBudget.cs |
Multi-dimensional budget: tool calls, delegation depth, wall time, tokens, spawns |
BudgetSnapshot |
Autonomous/AgentExecutionBudget.cs |
Immutable snapshot for logging and telemetry |
BudgetExhaustedException |
Autonomous/AgentExecutionBudget.cs |
Typed exception with BudgetDimension (ToolCalls, DelegationDepth, WallTime, Tokens, SpawnedAgents) |
BudgetDimension |
Autonomous/AgentExecutionBudget.cs |
Enum of the 5 budget dimensions |
The limits are init-only; the counters are thread-safe (Interlocked). Each Record* call (RecordToolCall, RecordDelegation, RecordSpawn, RecordTokens(n)) checks the wall time, increments its counter and throws BudgetExhaustedException when the counter goes past its limit. ThrowIfExhausted() is the pre-flight check that consumes nothing, AssertWallTime() checks the clock alone, and IsExhausted reports whether any dimension is spent. The clock is injectable (TimeProvider) for tests. PauseWallClock() stops the wall clock until the handle it returns is disposed (pauses nest): ctx.llm.act holds one while the permission gate waits for an operator's answer, so an approval that takes minutes does not end an agent whose own run stays within MaxWallTime.
Domain layer β ProcessType
ProcessType.Autonomous is a member of the value object, and IProcessStrategy has a dedicated entry point:
Task<CrewOutput> ExecuteAutonomousAsync(
Crew crew,
AgentExecutionBudget budget,
IReadOnlyDictionary<string, string>? inputVariables = null,
CancellationToken cancellationToken = default);
Application layer β A2A communication
| Class | File | Role |
|---|---|---|
IAgentChannel |
Interfaces/Services/IAgentChannel.cs |
Bidirectional request/response channel between agents |
AgentChannelRequest |
Interfaces/Services/IAgentChannel.cs |
Request with correlation ID, intent, payload, optional metadata (Create(from, to, intent, payload)) |
AgentChannelResponse |
Interfaces/Services/IAgentChannel.cs |
Correlated response (Ok(...) / Fail(...)) with success/error |
NullMemoryScope |
Context/NullMemoryScope.cs |
No-op singleton for contexts without memory |
IAgentChannel supports three operations:
- RequestAsync: request/response with a timeout (30 s by default); a target that does not answer in time raises
TimeoutException, a target with no registered handler gets a failed response - RegisterHandler: per-agent handler registration (returns an
IDisposablethat unregisters it) - BroadcastAsync: notification to the other agents of a crew, no response expected;
InMemoryAgentChannelreaches the agents registered withRegisterCrewMember(crewId, agentId)
Infrastructure layer β Autonomous strategy
| Class | File | Role |
|---|---|---|
AutonomousProcessStrategy |
Crew/Strategies/AutonomousProcessStrategy.cs |
Implements IProcessStrategy.ExecuteAutonomousAsync |
InMemoryAgentChannel |
Communication/InMemoryAgentChannel.cs |
In-process implementation of the A2A channel (lock-free, ConcurrentDictionary), registered as the scoped IAgentChannel |
SpawnAgentTool |
Tools/SpawnAgentTool.cs |
Tool that lets an agent spawn a sub-agent |
DelegateWorkTool |
Tools/DelegateWorkTool.cs |
Takes an optional AgentExecutionBudget and calls RecordDelegation() before each delegation |
Wiring
| Place | Role |
|---|---|
ProcessStrategyFactory |
"Autonomous" β AutonomousProcessStrategy |
SequentialCrewOrchestrator |
Dispatches "Autonomous" to ExecuteAutonomousAsync with the crew's budget (crew.Budget.ToExecutionBudget()) |
AddOrkeonInfrastructure() |
Registers AutonomousProcessStrategy and IAgentChannel β InMemoryAgentChannel (scoped) |
Execution flow
ββββββββββββββββββββββββββββββββββββββββββββββββββββ
β AutonomousProcessStrategy β
β β
crew tasks βββΊ β register every agent on the IAgentChannel β
(dependency β for each task: β
order) β 0. budget.AssertWallTime() β
β 1. manager.AssignTaskAsync (LLM) β agent β
β 2. budget.RecordToolCall() β
β 3. ExecuteTaskAsync(agent, task) β
β 4. failed + AllowDelegation + depth + a peer: β
β ββ budget.RecordDelegation() β
β ββ channel.RequestAsync("delegate", β
β β first other agent, timeout 2 min) β
β ββ peer executes under a child budget β
β 5. BudgetExhausted in the task β partial β
β output "[BUDGET EXHAUSTED] β¦", stop β
β BudgetExhausted between tasks β stop the loop β
ββββββββββββββββββββββββββββββββββββββββββββββββββββ
Details that matter when sizing a run:
- Assignment goes through
IManagerAgent(LlmBasedManager), which calls the crew's manager LLM, resolved once per run as in the Hierarchical mode: the providerCrewBuilder.WithManagerLlmsets (C#), else the host's default profile β an autonomous crew has no manager agent:managerAgent:(.manager(agent)in.ork.ts,.WithManager(agent)in C#) is refused when the crew is loaded or built. A task'sagent:is not consulted. An LLM error falls back to the first agent. - Tool calls: the strategy records one
RecordToolCall()per task handed out (the assignment); the agent's own tool calls inside its loop are not counted against the budget.MaxToolCallstherefore bounds the number of tasks attempted. - Delegation depth:
RecordDelegation()increments a crew-wide counter that is never decremented, soMaxDelegationDepthbehaves as the number of delegations allowed in the run. The delegate is the first other agent in the crew's order; it takes the task itself over β its plan too, when the crew plans β, in the context of the attempt that failed, derived from it: the crew's id and memory scope, the run's input variables and the outputs so far, plusdelegation_contextandautonomous_child_budget_snapshot. It recalls the crew's memory like any execution that answers a task, its output β when it succeeds β is the task's result, stored once under the peer withmemory: true, and it does not delegate further. The agent that failed fails the task (AgentFailedTaskEvent), the task is assigned to the peer, and completes under it (Events). - Tokens:
MaxTokensConsumedcovers the whole run. The tokens of a direct execution are recorded on the crew's budget when it returns, a failed attempt's included; those of a delegated execution once on each budget of the child's chain and of the crew's (RecordChildTokens): a budget both chains share is counted once, so each token counts once per budget. Work whose tokens pass the budget, direct or delegated, keeps its output: the task is recorded with it, then the run stops on the budget like any other exhaustion. A failed direct attempt that spent the budget is not handed to a peer. The refusal readsToken budget exhausted: <sum> tokens sent and received over <n> calls (limit <limit>). - Outcome: the crew output concatenates the task outputs. A task that failed β directly, with no peer to delegate to, or delegated to a peer who failed too β fails the crew, and the tasks that depend on it are skipped without being claimed. An exhausted budget fails the crew too, its error opening with
Execution budget exhausted: <dimension>and naming every task it never reached;ICrewExecutionHookreceivesFailedwith that reason (Canceledis kept for an actual cancellation).orkeon runexits 2 in both cases.
Multi-dimensional budget
The budget controls 5 independent dimensions. Each dimension has a thread-safe counter and a limit. Exhausting any dimension throws BudgetExhaustedException.
| Dimension | Default | Strict | Permissive | Description |
|---|---|---|---|---|
| MaxToolCalls | 15 | 8 | 50 | Maximum number of tool calls |
| MaxDelegationDepth | 2 | 1 | 4 | Maximum delegation depth (AβBβC = 2) |
| MaxWallTime | 5 min | 2 min | 15 min | Maximum wall-clock time |
| MaxTokensConsumed | 16,000 | 8,000 | 64,000 | Running sum of tokens (prompt + completion of every call recorded) |
| MaxSpawnedAgents | 3 | 1 | 10 | Maximum number of spawned sub-agents |
AgentExecutionBudget has a sixth limit, MaxContextTokens (default int.MaxValue, no limit): the tokens counted with the context counted once, reported under the Tokens dimension (BudgetDimension keeps its 5 members) and propagated to child budgets. It is set by the contextTokens key of an .ork.ts budget β the procedural crewBuilder().budget(...) and the budget option of crew.runAgent / ctx.delegate (scripting DSL); the crew budget: YAML has no such key, and an autonomous crew's .ork.ts budget refuses it.
Presets
#pragma warning disable ORKEXP002
// Production: conservative limits
var strict = AgentExecutionBudget.Strict;
// Development: loose limits
var permissive = AgentExecutionBudget.Permissive;
// Custom
var custom = new AgentExecutionBudget
{
MaxToolCalls = 20,
MaxDelegationDepth = 3,
MaxWallTime = TimeSpan.FromMinutes(10),
MaxTokensConsumed = 32_000,
MaxSpawnedAgents = 5
};
// A budget built in code rather than the crew's: call the strategy directly
var strategy = serviceProvider.GetRequiredService<AutonomousProcessStrategy>();
var output = await strategy.ExecuteAutonomousAsync(crew, custom, inputVariables: null, ct);
#pragma warning restore ORKEXP002
KickoffAsync does not take a budget: a crew run through ICrewOrchestrationService (the runner, the host) spends the crew's own budget β YAML budget: (schema), crewBuilder().budget({...}) in .ork.ts, CrewBuilder.Budget(new CrewBudget { ... }) in C#. A crew that sets none runs with no token cap and no wall time, under the structural limits of 50 tasks handed out, 4 delegations and 10 spawns (CrewBudget.DefaultToolCalls, DefaultDelegationDepth, DefaultSpawnedAgents): tokens and time are bounded only when the author asks, so an ordinary crew is never cut short by a figure it did not choose. A key left out takes the same default. A budget given to a crew of another process is refused when the crew is loaded or built, as is a limit below 1. Calling ExecuteAutonomousAsync directly skips what the orchestrator adds around a run (planning, checkpointing, the crew's state transitions).
Child budgets
When the strategy delegates, or SpawnAgentTool spawns, the sub-agent receives a derived child budget:
var childBudget = parentBudget.CreateChildBudget();
// MaxToolCalls = max(1, parent.Max - parent.Current)
// MaxDelegationDepth = max(0, parent.Max - parent.Current - 1)
// MaxWallTime = parent.MaxWallTime - parent.Elapsed
// MaxTokensConsumed = max(100, parent.Max - parent.Current)
// MaxSpawnedAgents = max(0, parent.Max - parent.Current)
A child budget is an independent copy of the parent's remaining allowance, with its own counters: two children derived one after the other each receive the full remainder. The parent's cap is held where the consumption is recorded on it too β the tokens of a delegated execution, and each spawn. A budget may also charge another one (ChargedTo, set by the charge: "crew" option of the scripting DSL): every tool call, token and spawn recorded on it is recorded there too, CreateChildBudget() hands that charge on to the child (it does not charge the parent itself), and IsExhausted is true when the budget itself or the one it charges is spent.
A2A communication (IAgentChannel)
The bidirectional channel lets agents communicate in request/response mode:
// Agent A asks Agent B to clarify
var request = AgentChannelRequest.Create(
from: agentA.Id,
to: agentB.Id,
intent: "clarify",
payload: "Which data format for the report?");
var response = await channel.RequestAsync(request, timeout: TimeSpan.FromSeconds(30));
if (response.Success)
Console.WriteLine($"Response: {response.Payload}");
Intents
The intent is a free string. Inside an autonomous run, the handler each agent registers understands:
| Intent | Handling |
|---|---|
delegate |
Executes the payload as a task under a child budget and returns its output (or Budget exhausted: β¦) |
anything else (clarify, β¦) |
Acknowledged: Agent <role> acknowledges: <intent> |
broadcast |
The intent BroadcastAsync stamps on its notifications |
The InMemoryAgentChannel implementation is in-process and lock-free. For a multi-host deployment, implement IAgentChannel with Redis Streams or a message broker.
SpawnAgentTool β Agent self-spawn
A tool (spawn_agent) that lets an agent create a specialized sub-agent on the fly.
The class ships in Orkeon.Infrastructure but neither the strategy nor any shipped
composition root provides it: its constructor takes the parent agent's id, the crew id,
the AgentExecutionBudget it enforces and an IAgentFactory (plus, for a synchronous
spawn, an IAgentExecutionService), so a host that wants self-spawn builds one per agent
and adds it to that agent β see the tool inventory. The budget it
enforces is the one the host hands it, not the run's budget.
// The agent's LLM generates this tool call:
{
"tool": "spawn_agent",
"parameters": {
"role": "data_analyst",
"goal": "Analyze Q4 sales trends",
"task": "Produce a CSV report of sales by region",
"wait_for_result": true,
"allow_delegation": false
}
}
role, goal and task are required; backstory, allow_delegation and wait_for_result are optional. Each spawn calls RecordSpawn() on the budget (a spent budget refuses the call). The spawned agent is created with MaxIterations = 5 and a child budget (passed in the spawn request metadata and in the execution context). With wait_for_result: true (the default) the tool executes the task and returns its output; false only creates the agent.
Observability
Output metadata
The CrewOutput in Autonomous mode includes budget metadata, next to the token telemetry:
{
"process_type": "autonomous",
"agent_count": 3,
"budget_tool_calls": "12/50",
"budget_delegation_depth": "1/4",
"budget_tokens": "9200/64000",
"budget_spawned": "0/10",
"budget_exhausted": false
}
BudgetSnapshot
budget.ToSnapshot() returns an immutable BudgetSnapshot at any time (ToolCalls/MaxToolCalls, DelegationDepth/MaxDelegationDepth, TokensConsumed/MaxTokensConsumed, SpawnedAgents/MaxSpawnedAgents, Elapsed/MaxWallTime, IsExhausted), loggable and serializable. Charged holds the snapshot of the budget this one charges (ChargedTo), and IsExhausted is also true when that one is spent, even if every dimension of this snapshot is under its limit.
Structured logging
All key events are logged via LoggerMessage:
Starting autonomous execution for crew {CrewId} (budget: {MaxToolCalls} tool calls, depth {MaxDepth})Agent {AgentId} claimed task {TaskId}: {Reason}Delegation: {From} β {To} for task {TaskId} (depth: {Depth})Task {TaskId} completed (success: {Success}, budget: {Snapshot})Budget exhausted for crew {CrewId}: dimension={Dimension}, {Message}Autonomous execution completed for crew {CrewId} in {Duration} (tool calls: {ToolCalls}, delegation depth: {Depth})SpawnAgentToollogs each spawn (parent, child id, role) and the completion of a synchronous spawn
Like every mode, the strategy also reports through ICrewExecutionHook: the task start when an agent claims it, the task completions and the crew outcome when the run settles.
YAML configuration
# Flat root β no crew: wrapper; agents: is a mapping keyed by agent id.
name: research-team
process: autonomous # β enables the autonomous mode
goal: "Produce a complete research report"
agents:
researcher:
role: Researcher
goal: "Find reliable sources"
allowDelegation: true # a failed task of this agent is handed to a peer
tools: [web_search]
analyst:
role: Analyst
goal: "Analyze and synthesize the data"
allowDelegation: true
tools: [json_tool, csv_reader]
writer:
role: Writer
goal: "Write the final report"
allowDelegation: false
spawn_agent is not listed: the YAML loader resolves tool names against the tool registry, where no SpawnAgentTool is registered by default (an unknown name is skipped with a warning, or fails the load in strict-tools mode).
Note: the crew's budget is YAML
budget:(tokens,wallTimeSeconds,toolCalls,delegationDepth,spawnedAgents); in the scripting DSL,crewBuilder().budget({...})sets it in both shapes β the declarative shape of aprocess("autonomous")crew, the procedural shape (await crew.run()) β and the declarative shape of another process refuses it, as YAML does, as it refuses a limit below 1. Defaults are under Presets.
Delegation: the autonomous strategy delegates through the
IAgentChannel; there is no task delegator service.
Complementarity with the other modes
| Need | Recommended mode |
|---|---|
| Linear pipeline, maximum determinism | Sequential |
| Centralized manager, quality review | Hierarchical |
| Independent tasks, parallelism | Parallel |
| Retry of flaky tasks, bounded run | Graph |
| LLM-driven assignment, second chance with a peer, budget-bounded run | Autonomous |
The Autonomous mode is the least deterministic. For sensitive production workloads, prefer Sequential or Hierarchical and reserve Autonomous for cases where letting the manager distribute the work brings more value than the cost of non-determinism (exploratory research, creative writing, complex multi-domain problem solving).
Tests
| Test file | Coverage |
|---|---|
Orkeon.Infrastructure.Tests/Strategies/CovAutonomous_AutonomousProcessStrategyTests.cs |
Entry points, assignment fallback, delegation over the channel, tool-call and wall-time exhaustion, token telemetry, channel handlers |
Orkeon.Domain.Tests/Autonomous/AgentExecutionBudgetTimeProviderTests.cs |
Wall-time budget with a controllable clock |
Orkeon.Infrastructure.Tests/Communication/CovStubs_InMemoryAgentChannelTests.cs |
Request/response, timeout, missing handler, broadcast |
Orkeon.Infrastructure.Tests/Tools/SpawnAgentTool/SpawnAgentToolTests.cs |
Spawn recorded on the parent budget, child budget propagation (metadata, context variables), token accounting |
Orkeon.Infrastructure.Tests/Orchestration/CovAutonomous_SequentialCrewOrchestratorTests.cs |
Dispatch of the six modes (Autonomous under the crew's budget, uncapped when it sets none) |
See also: ProcessTypes comparison guide Β· Graph orchestration Β· YAML schema Β· Back to index