Agent Mesh — Workflows¶

Target

This page describes intended behaviour or structure. No implementation is claimed unless a section is explicitly marked Current implementation or Evidence.

Two lifecycles, one authority¶

Lifecycle	Owner	Vocabulary
Run, step, attempt (authoritative)	Run Control (BC-03)	ADR-0014: Accepted, Running, WaitingForApproval, Cancelling, Completed, Failed, Cancelled; attempt outcomes Succeeded, Failed, TimedOut, Cancelled, Uncertain
Attempt execution (runtime view)	`AgentRuntimeService` (BC-06)	Claimed, Running, WaitingForTool, WaitingForDecision, Paused, then the same terminal outcomes
Workflow run (projection)	`WorkflowEngineService` (BC-38)	Pending, Running, WaitingForTimer, WaitingForHuman, Compensating, Completed, Failed, Cancelled

The runtime vocabularies project onto Run Control's; they never contradict it. When they disagree after a failure, Run Control's journal wins and the runtime re-projects.

Attempt execution¶

sequenceDiagram
    participant RC as RunControlService
    participant W as AgentRuntimeWorker
    participant A as AttemptGrain
    participant E as Executors (model, tools, knowledge)
    RC-)W: AttemptDispatched (lease, fencing token, snapshotId)
    W->>A: activate, StartAttempt
    A->>A: LoadRelease, BuildContext, checkpoint 1
    loop plan, call, observe, verify
        A->>E: call with fencing token and receipt
        A->>A: checkpoint after observed outcome
    end
    A->>RC: ReportAttemptOutcome (outcomeHash)
    RC-)W: AttemptOutcomeRecorded

Hold "Alt" / "Option" to enable pan & zoom

Rules: a checkpoint precedes every gated call; corrections are bounded by the contract; the outcome is reported once and idempotently; the lease is renewed every 15 seconds and a failed renewal pauses the attempt at the next checkpoint.

Release loading¶

Releases arrive as AssetReleasePublished and are verified ahead of dispatch by the cache warmer; at dispatch the attempt verifies again against its adapter version. Hash mismatch or adapter incompatibility fails the attempt with an explicit reason (ReleaseLoadRejected). Deprecation and revocation apply the in-flight policy (finish, drain, revoke) to running attempts. See release loading.

Human decisions¶

Decision	Who owns the record	How it reaches the attempt
Approval of a gated action (exact proposal version)	Run Control `ApprovalRequest`	`ApprovalDecided` event; the attempt resumes or fails
Missing input	runtime `DecisionRequest` of kind Input	`Runtime.AnswerDecision` from the Studio BFF
Escalation with options and a recommendation	runtime `DecisionRequest` of kind Escalation	`Runtime.AnswerDecision`; the chosen option is recorded as a call

An attempt waiting for a decision keeps its lease (renewed) and its checkpoint; the input timeout fails the attempt with class policy-denied.

Cancellation¶

Run Control records intent and calls Runtime.Interrupt; the attempt stops at the next safe point, settles in-flight calls (observed or Uncertain), emits AttemptCancellationObserved and reports Cancelled. Nothing is rolled back by the runtime; completed effects stay visible through receipts, and compensation, if declared, is the workflow engine's job.

Sub-agent delegation¶

A supervisor attempt may submit child runs (same scope, same budget, depth-limited) when the task's complexity justifies it. Each child is a run with its own approvals and receipts; the supervisor waits for the child's terminal event as a call of kind SubAgent. Delegation is justified by the workflow or agent contract, never improvised beyond MaxSubAgentDepth.

Workflow run projection¶

sequenceDiagram
    participant RC as RunControlService
    participant E as WorkflowRunGrain
    RC-)E: RunAccepted
    E-)RC: WorkflowRunStarted, StepReady (first steps)
    RC-)E: AttemptOutcomeRecorded
    E->>E: Advance (idempotent on outcome sequence), conditions, timers, fan-out, join
    E-)RC: StepReady (next) or WorkflowRunCompleted or WorkflowRunFailed

Hold "Alt" / "Option" to enable pan & zoom

Compensation: on a step failure with policy Compensate the engine plans the compensation steps of every succeeded step in reverse order and emits them as StepReady; the run ends Failed with compensated: true or, if a compensation fails, with an operator follow-up.

Workflow definitions¶

The definitions the engine executes are modelled: one per coordinator realized as a workflow, 25 in all, each with its DAG, steps, gates, compensation and events on a definition page and in the workflows catalog (D54). A definition names agents by id; an agent's role card lists the definitions whose steps it runs. All definitions are Draft until their evaluation gate (ADR-0021) and every agent they name are Published.

Recovery¶

Loss	Recovery
Worker replica	grains re-activate on another replica; attempts resume from a compatible checkpoint; in-flight calls become `Uncertain`
Control plane connectivity	attempts pause; Run Control reconciles expired leases; no outcome is invented
Timer reminder	the stuck-run reconciler fires due timers; a late timer whose step advanced is a no-op
Engine state	re-projected from Run Control's journal (`lastOutcomeSequence`)
Adapter upgrade	incompatible checkpoints fail the attempt with class infrastructure; Run Control starts a new attempt

There is no replay. See failure and recovery for the failure taxonomy and ADR-0014.

Overview · AgentRuntimeService · WorkflowEngineService · Control plane workflows