Table of Contents

πŸ‡«πŸ‡· 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, IAgentChannel and its records, AutonomousProcessStrategy and SpawnAgentTool carry [Experimental("ORKEXP002")]: code that uses them must acknowledge the diagnostic (see experimental APIs). Running a YAML crew with process: autonomous needs 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 IDisposable that unregisters it)
  • BroadcastAsync: notification to the other agents of a crew, no response expected; InMemoryAgentChannel reaches the agents registered with RegisterCrewMember(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 provider CrewBuilder.WithManagerLlm sets (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's agent: 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. MaxToolCalls therefore bounds the number of tasks attempted.
  • Delegation depth: RecordDelegation() increments a crew-wide counter that is never decremented, so MaxDelegationDepth behaves 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, plus delegation_context and autonomous_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 with memory: 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: MaxTokensConsumed covers 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 reads Token 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; ICrewExecutionHook receives Failed with that reason (Canceled is kept for an actual cancellation). orkeon run exits 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})
  • SpawnAgentTool logs 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 a process("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