Table of Contents

Class WorkflowOrchestrator

Namespace
LMKit.Agents.Workflows
Assembly
LM-Kit.NET.dll

Runs a WorkflowDefinition. The workflow is compiled onto the orchestration nodes (SequentialNode, ParallelNode, ConditionalNode, and nodes for agent, tool, loop, approval and hand-off steps), so it runs with the orchestrators' events and spans, and its state lives in an AgentRunState: every step's output, its position, and its timeline.

public sealed class WorkflowOrchestrator : OrchestratorBase, IOrchestrator
Inheritance
WorkflowOrchestrator
Implements
Inherited Members
Extension Methods

Examples

var workflow = WorkflowDefinition.FromJson(File.ReadAllText("triage.json"));
var orchestrator = new WorkflowOrchestrator(workflow, (name, revision) => agents[name]);
WorkflowResult result = await orchestrator.RunAsync("My order arrived broken.");
if (result.Status == AgentExecutionStatus.AwaitingApproval)
{
    AgentRunToolCall pending = result.RunState.PendingRound.First(c => c.AwaitingApproval);
    result = await orchestrator.ResumeAsync(result.RunState,
        new AgentRunInput { Approvals = { ToolApprovalDecision.Approve(pending) } });
}

Remarks

A workflow stops for people: at an approval step, or inside an agent step whose agent needs approval for a call or asks the user a question (DeferToolApprovals is turned on for its agents). The result then carries the run state, with what it waits for in PendingRound or Question exactly as an agent run does, so the same approval handling serves both. ResumeAsync(AgentRunState, AgentRunInput, OrchestrationOptions, CancellationToken) continues it: the steps already done are replayed from their recorded outputs, never run again.

The host resolves names: resolveAgent turns an agent name (and revision) into an Agent, resolveTool a tool name into an ITool.

Constructors

WorkflowOrchestrator(WorkflowDefinition, Func<string, int?, Agent>, Func<string, ITool>)

Initializes a new instance.

Fields

ApprovalGateName

The name of the pending call an approval step stops on.

CompensatingKey

The metadata entry of a run that failed and is undoing its completed steps, holding the error it failed with: a run resumed while it is set finishes its compensations instead of running again.

Properties

AgentStepRunner

Gets or sets the host's own runner of agent steps; null runs each step's agent from resolveAgent. A host whose agents carry more than a definition (an API key's grants, knowledge, memory, its approval rules) runs them here, and returns the agent's result: its stop for a person (RunState) stops the workflow, which hands that run back through StoppedRun on resume.

ApprovalTimeout

Gets or sets how long an approval step waits before it counts as denied; null waits without a deadline.

Definition

Gets the workflow this orchestrator runs.

MaxParallelism

Gets or sets the most branches of one parallel step that run at once; the others start as running ones finish, in order. Null runs every branch at once. A host bounds the fan-out of one run here, so a workflow with many branches cannot take every worker of the host.

Name

Gets the name of this orchestrator.

ParkRetriesLongerThan

Gets or sets the longest wait the play sits through itself, a retry's or a wait step's. A longer wait parks the run: the play stops with the run Suspended and ResumeAfterUtc set to the attempt's due time, and the host resumes it then (ResumeAsync(AgentRunState, AgentRunInput, OrchestrationOptions, CancellationToken)). Null (the default) sits through every wait. A step inside a parallel branch always waits, as a branch cannot stop.

ResolveWorkflow

Gets or sets how the host finds the workflow a workflow step runs: its name and a revision (null for the current one) to the definition, its Revision set; null when there is none. Null fails every workflow step. A child workflow runs with this orchestrator's resolvers, runners and policies, under the same identity.

RunStore

Gets or sets where the run is checkpointed after every step and at every stop, so a lost process resumes from the last step done; null keeps the state only in the result.

ToolNeedsApproval

Gets or sets whether a tool step's tool needs a person's approval before it is called; null calls every tool step directly. A tool that needs one stops the workflow with the call pending (PendingRound), exactly as an agent's call that needs approval.

Methods

DeliverEvent(AgentRunState, string, string, string)

Delivers an event to a run that waits for it: when the run is in AwaitingEvent for this event and correlation key, the payload is kept for the waiting step and the run becomes resumable (Suspended); resume it to go on. False, and nothing changed, when the run waits for anything else.

ExecuteCoreAsync(OrchestrationContext, OrchestrationOptions, CancellationToken)

Core orchestration logic implemented by derived classes.

ExpireWait(AgentRunState, DateTime)

Ends the wait of a run whose event deadline passed: the run becomes resumable, and the waiting step fails as a timeout when it resumes (its error steps then apply). False when the run does not wait for an event, or its deadline has not passed.

PrepareRetry(WorkflowDefinition, AgentRunState, string, IReadOnlyDictionary<string, string>, IReadOnlyDictionary<string, bool>, string)

Sets a failed run up to resume from its failing step (what RetryAsync(AgentRunState, string, IReadOnlyDictionary<string, string>, IReadOnlyDictionary<string, bool>, string, OrchestrationOptions, CancellationToken) plays): the run is suspended again with no step to resume at, so the resumed play replays every completed step from its recorded output and makes the failing step again. The attempts of every step not completed are cleared (its retry policy applies anew); error steps that already ran replay their record should the step fail again, so nothing they sent is sent twice. A write recorded as possibly made is settled by reconciled when it names it (true: it happened, its step completes on that; false: it did not, it is sent again); otherwise it is left in doubt, so the resumed play sends it again only under the same idempotency key to a tool that honors keys, and otherwise waits for a person to say.

ResumeAsync(AgentRunState, AgentRunInput, OrchestrationOptions, CancellationToken)

Continues a workflow that stopped for a person with what unblocks it: decisions on the calls it waits for (an approval step's included), the answer to its question, or the outcome of a write. Steps already done replay their recorded output.

RetryAsync(AgentRunState, string, IReadOnlyDictionary<string, string>, IReadOnlyDictionary<string, bool>, string, OrchestrationOptions, CancellationToken)

Resumes a failed run of this workflow from its failing step: the steps it completed replay their recorded output and never run again, the failing step is attempted afresh (its retry policy anew), with the input and variables corrected when given. See PrepareRetry(WorkflowDefinition, AgentRunState, string, IReadOnlyDictionary<string, string>, IReadOnlyDictionary<string, bool>, string) for what is changed and how a write in doubt is settled.

RunAsync(string, IReadOnlyDictionary<string, string>, OrchestrationOptions, string, CancellationToken)

Runs the workflow on an input.

Share