RFC-0022 · Multi-Agent Workflow Orchestration
Versioned draft snapshot
RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.
Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.
| Status | Draft corpus. Reference catalogs and RDF projections have generation drift checks; Gnomon proofs and projection semantics remain unverified for release. |
|---|
View the generated reference catalog →
Read design questions and decisions →
Reference catalog: the diagnostics, linked-RFC graph, defined terms, and normative-rule index for this RFC are in the reference catalog, generated from the structured Lean module. This document carries the prose: design rationale, entity-shape definitions in context, and migration notes.
1. Scope
This RFC defines the workflow declaration kind: a named composition of Gnomon agents with explicit coordination semantics, data flow contracts, and error handling.
This RFC covers:
- The
workflowdeclaration — syntax and semantics - Sequential, parallel, conditional, and loop coordination patterns in the
.gnmDSL - Typed data flow between agents: outputs of one agent as inputs to the next
- Error handling and compensation: what happens when a sub-agent step fails
- Human-in-the-loop gates: workflow pause pending human approval
- Observability: how workflow execution appears in the RFC-0010 event log
- Diagnostic codes in the M22xxx range
This RFC does not cover:
- Individual agent declarations — those are defined in RFC-0009
- Agent runtime binding (endpoint, model, health check) — those are defined in RFC-0015
- Workflow scheduling or cron-triggered invocation (deferred to a future RFC)
- Cross-module workflow composition: a workflow may only reference agents declared within its own module or its imported modules
- Long-running human workflows lasting more than a configurable platform timeout (implementation-defined ceiling; this RFC defines the pause/resume semantics but not timeout policy)
2. Goals
- A
workflowdeclaration MUST be fully static: all coordination structure, data flow types, and error policies are known at compile time. - Sequential and parallel composition MUST be expressible without boilerplate. The compiler MUST verify that data flow types are consistent between steps.
- Human-in-the-loop gates MUST be first-class: a workflow that requires human approval before proceeding is not a special case but a standard coordination pattern.
- Workflow execution MUST be fully observable via the RFC-0010 event log. Every step start, step outcome, gate open/close, and workflow terminal state MUST produce a structured event.
- A failed sub-agent step MUST NOT produce silent data corruption. The workflow MUST define an explicit error policy for each step; absence of a policy is a compile error.
- The
workflowdeclaration MUST NOT introduce new agent capabilities. Each step invokes an existing agent declaration with its existing permission set (RFC-0009). Workflows are orchestrators, not capability escalators.
Linked References
The cross-RFC dependency graph is rendered in reference catalog § Linked References. Out-of-KG pointers to legacy code or external resources, when present, remain in this document under “Source-tree references” below.
3. The workflow Declaration
3.1 Syntax
workflow-decl ::= { decl-modifier } "workflow" IDENT "{" workflow-body "}"
workflow-body ::= "description:" STRING NEWLINE
"trigger:" trigger-decl NEWLINE
"steps:" step-list
[ "onError:" error-policy NEWLINE ]
[ "timeout:" DURATION NEWLINE ]
trigger-decl ::= "procedure" IDENT (* fired via a declared procedure *)
| "event" IDENT (* fired by an event log event *)
| "manual" (* invoked programmatically *)
step-list ::= step-decl+
step-decl ::= sequential-step
| parallel-step
| conditional-step
| loop-step
| gate-step
sequential-step ::= "step" IDENT "{" step-body "}"
parallel-step ::= "parallel" "{" sequential-step+ "}"
conditional-step ::= "if" condition-expr
"then" "{" step-list "}"
[ "else" "{" step-list "}" ]
condition-expr ::= condition-expr "and" condition-expr
| condition-expr "or" condition-expr
| "not" condition-expr
| "(" condition-expr ")"
| field-path ( "==" | "!=" | "<" | ">" | "<=" | ">=" ) literal
field-path ::= IDENT ( "." IDENT )*
literal ::= STRING | NUMBER | "true" | "false"
loop-step ::= "repeat" int-literal "{" step-list "}"
gate-step ::= "gate" IDENT "{" gate-body "}"
step-body ::= "agent:" IDENT NEWLINE
"inputs:" input-map NEWLINE
"outputs:" output-bind NEWLINE
[ "onError:" error-policy NEWLINE ]
[ "timeout:" DURATION NEWLINE ]
gate-body ::= "description:" STRING NEWLINE
"approvedBy:" IDENT (* actor declaration *)
input-map ::= "{" { IDENT ":" value-ref } "}"
output-bind ::= "{" { IDENT ":" IDENT } "}" (* bind output field to workflow variable *)
value-ref ::= "trigger." IDENT (* field from trigger input *)
| IDENT "." IDENT (* output field from a previous step *)
| literal
error-policy ::= "fail" (* halt workflow, mark failed *)
| "continue" (* log and continue to next step *)
| "retry" int-literal (* retry step N times before failing *)
| "compensate" IDENT (* invoke a named compensation step *)
3.2 Canonical Example
workflow CustomerOnboarding {
description: "Runs document verification, risk scoring, and advisor assignment in sequence."
trigger: procedure SubmitApplication
steps:
step VerifyDocuments {
agent: DocumentVerificationAgent
inputs: { applicationId: trigger.applicationId }
outputs: { verificationResult: verifyResult }
onError: retry 2
}
if verifyResult.status == "approved"
then {
step ScoreRisk {
agent: RiskScoringAgent
inputs: { applicationId: trigger.applicationId, verifyData: verifyResult.data }
outputs: { riskScore: riskScore }
onError: fail
}
gate ManagerApproval {
description: "Senior manager must approve high-risk applications."
approvedBy: Manager
}
step AssignAdvisor {
agent: AdvisorAssignmentAgent
inputs: { applicationId: trigger.applicationId, riskScore: riskScore }
outputs: {}
onError: fail
}
}
else {
step NotifyRejection {
agent: NotificationAgent
inputs: { applicationId: trigger.applicationId, reason: "documents-failed" }
outputs: {}
onError: continue
}
}
}
4. Coordination Patterns
4.1 Sequential Steps
Steps listed in sequence are executed in declaration order. Each step MUST complete before the next begins. The outputs of step N are available as inputs to step N+1 and any subsequent step.
4.2 Parallel Steps
Steps inside a parallel {} block are dispatched concurrently. The workflow waits for all parallel steps to complete before proceeding to the next declaration. If any parallel step fails and its error policy is fail, the workflow halts after all in-flight parallel steps settle (no cancellation mid-flight; this may be revisited in a future RFC).
Output bindings from parallel steps MUST use distinct variable names. A naming collision in parallel output bindings is a compile error M22202.
4.3 Conditional Steps
if … then … else … evaluates a boolean condition over a workflow variable or step output. The condition expression uses a restricted subset of the Transform Expression Language (RFC-0021). Workflow conditionals support the following RFC-0021 TEL subset: field access paths (e.g., step.output.status), equality and comparison operators (==, !=, <, >, <=, >=), logical connectives (and, or, not), and string/number/boolean literals. Arithmetic operators and string manipulation functions are NOT permitted in workflow conditionals.
The then branch is required; the else branch is optional. A conditional without else has an implicit no-op else. The compiler emits M22203 (warning) for a conditional whose then branch can produce outputs that subsequent steps depend on, but whose else branch produces no such outputs. This is a likely author mistake.
4.4 Loop Steps
repeat N { … } executes the enclosed step list exactly N times. N MUST be a positive integer literal; it cannot be a workflow variable. This restriction ensures the loop bound is statically known and the workflow is provably finite.
4.5 Human-in-the-Loop Gates
A gate step pauses the workflow until a human actor (identified by their actor declaration from RFC-0008) approves or rejects the continuation.
- While a gate is open, the workflow is in the
waitingstate. No further steps are executed. - The
approvedByfield identifies the actor declaration whose principals may approve or reject the gate. - Approval transitions the workflow to the
runningstate and proceeds to the next step. - Rejection transitions the workflow to the
rejectedterminal state. - Gate events MUST appear in the RFC-0010 event log with full actor identity and timestamp.
5. Typed Data Flow
Every step declares its inputs and outputs. The compiler resolves all data flow at compile time:
- Each
inputsbinding references eithertrigger.<field>or<step>.<field>. - The compiler looks up the type of the referenced field from the triggering action or from the agent’s
outputsdeclaration (RFC-0009). - The type is matched against the agent step’s expected input type.
- Any type mismatch produces compile error M22204.
Workflow variables (the values bound in outputs) are immutable once written. A step cannot overwrite a workflow variable produced by a prior step. Attempting to bind to an already-bound variable produces M22205.
6. Error Handling
Each step declares an onError policy. A missing onError at step level, combined with no workflow-level onError default, is compile error M22206.
6.1 Error Policies
| Policy | Behavior |
|---|---|
fail | Halt the workflow, mark it failed. No subsequent steps execute. Emit a workflow failure event. |
continue | Log the step failure, mark the step failed, and proceed to the next step. |
retry N | Re-invoke the agent step up to N additional times. If all retries fail, apply the next policy level (workflow onError, or fail). |
compensate <step> | On failure, invoke the named compensation step before halting. The compensation step MUST be a sequential-step declared in the same workflow. |
6.2 Compensation Steps
A compensation step is a regular step declaration, but it is invoked by the error policy, not as part of normal sequential flow. Compensation steps SHOULD be idempotent. The compiler verifies that a compensate <step> reference resolves to a declared step within the workflow; an unresolved reference is M22207.
7. Observability
Every workflow state transition MUST be recorded as a structured event in the RFC-0010 event log. The following events are normative:
| Event | Emitted when |
|---|---|
workflow.started | Workflow is triggered and begins execution |
workflow.step.started | A step begins dispatch |
workflow.step.completed | A step completes successfully |
workflow.step.failed | A step fails (includes error policy applied) |
workflow.step.retrying | A step retry is initiated |
workflow.gate.opened | A gate is reached and the workflow enters waiting |
workflow.gate.approved | A gate is approved by a human actor |
workflow.gate.rejected | A gate is rejected; workflow transitions to rejected |
workflow.completed | Workflow completes all steps successfully |
workflow.failed | Workflow halts due to a fail error policy |
workflow.rejected | Workflow halts due to gate rejection |
Each event MUST include: workflow ID, workflow name, step name (if applicable), actor identity (for gate events), timestamp, and any diagnostic codes raised.
8. Security
- No capability escalation. A
workflowdeclaration MUST NOT grant any step agent capabilities beyond those declared in the agent’s ownpermissionsblock (RFC-0009). The orchestrator has no permission surface of its own. - Gate actor verification. The
approvedByactor in a gate MUST be validated at runtime against the authenticated identity of the approving principal. Unauthenticated or impersonated approvals MUST be rejected and logged as M22208. - Data flow isolation. Workflow variables are scoped to the workflow execution instance. They MUST NOT be readable by other workflow instances or by code outside the workflow execution context.
- Trigger authorization. The principal that fires the workflow trigger MUST be authorized to invoke the trigger’s underlying action (RFC-0008 §6.25). An unauthorized trigger attempt is rejected before the workflow begins.
9. Failure Modes
| Scenario | Outcome | Diagnostic |
|---|---|---|
| Step agent has no resolved binding in active environment | Workflow fails at that step | M22200 |
| Parallel step outputs bind to same variable name | Compile error | M22202 |
| Conditional output referenced by subsequent step but missing from one branch | Compile warning | M22203 |
| Data flow type mismatch between step output and next step input | Compile error | M22204 |
| Step attempts to rebind an already-bound workflow variable | Compile error | M22205 |
Step missing onError and no workflow-level default | Compile error | M22206 |
compensate references an undeclared step | Compile error | M22207 |
| Gate approval attempted by unauthenticated or wrong-actor principal | Runtime rejection, logged | M22208 |
| Loop count is zero or negative | Compile error | M22209 |
| Workflow trigger references an undeclared action | Compile error | M22210 |
Workflow trigger references an action directly; MUST reference a procedure | Compile error | M22214 |
Unresolved actor reference in gate approvedBy declaration | Compile error | M22215 |
draft agent referenced in workflow step in a ciState: ready bundle | Compile error | M01502 (RFC-0015) |
10. Invariants
- Static data flow. All input/output bindings in a workflow are resolved and type-checked at compile time. No runtime type errors can occur in data flow for a statically validated workflow.
- Bounded step count. All loop bounds are static integer literals. Combined with the absence of unbounded recursion in the DSL, every workflow execution has a finite bound on dispatched steps. This does not guarantee wall-clock termination: a human gate can remain open until a decision or a platform timeout outside this RFC.
- Complete error policy coverage. Every step MUST have an error policy — either at the step level or via a workflow-level default. A workflow with an uncovered step cannot compile.
- Full event log coverage. Every workflow state transition produces an event in the RFC-0010 event log. There are no silent transitions.
- No cross-instance variable sharing. Workflow variables are isolated to the instance. Two concurrent executions of the same workflow cannot observe each other’s variables.
- Gate actor binding. The
approvedByactor reference in a gate MUST resolve to a declared actor (RFC-0008). An unresolved actor reference is a compile error (M22215). - No permissions beyond declared agents. A workflow can only invoke agents it references by name. It cannot dynamically select agents at runtime, nor can it grant an agent temporary escalated permissions.
11. Diagnostic Codes (M22xxx)
All diagnostics introduced by this RFC occupy the M22200–M22299 range.
| Code | Severity | Summary |
|---|---|---|
| M22200 | Error | Workflow step references an agent with no resolved binding in the active environment. |
| M22201 | — | Reserved. |
| M22202 | Error | Parallel step output bindings use the same variable name (naming collision). |
| M22203 | Warning | Conditional step: subsequent step depends on a variable only bound in one branch. |
| M22204 | Error | Data flow type mismatch: step output type is not assignable to next step input type. |
| M22205 | Error | Step output attempts to rebind an already-bound workflow variable. |
| M22206 | Error | Step has no onError policy and no workflow-level default is declared. |
| M22207 | Error | compensate error policy references an undeclared workflow step. |
| M22208 | Error | Gate approval rejected: actor identity does not match the approvedBy declaration. |
| M22209 | Error | Loop step has a zero or negative repeat count. |
| M22210 | Error | Workflow trigger references an action that is not declared. |
| M22211 | — | Reserved. |
| M22212 | — | Reserved. |
| M22213 | — | Reserved. |
| M22214 | Error | Workflow trigger references an action directly; MUST reference a procedure. |
| M22215 | Error | Unresolved actor reference in gate approvedBy declaration (compile error). |