WorkflowDefinition schema

The workflow document type, validated against the published JSON schema.

Example

workflow.json

{
  "kind": "WORKFLOW",
  "schemaVersion": 1,
  "id": "quick-start",
  "name": "Quick Start",
  "description": "A single agent step that completes immediately — the shortest runnable workflow.",
  "steps": [
    {
      "kind": "STEP",
      "stepId": "greet",
      "name": "Greet",
      "behaviour": {
        "type": "AGENT",
        "agentRef": "quick-start-agent",
        "transition": "AUTO"
      }
    }
  ]
}

Properties

Property	Type	Required	Description
kind	const WORKFLOW	yes	—
schemaVersion	const 1	yes	Workflow definition format version this document is authored against. Required; consumers accept only schema versions they know and reject anything else. The framework's supported version is the single compatibility contract across framework, catalog, and builder releases.
id	string	yes	Unique workflow identifier. Must match the workflow directory name stem.
name	string	yes	Human-readable workflow name.
description	string	no	Optional workflow description.
uuid	string (uuid)	no	Optional stable workflow identity for server-side cost estimates (independent of directory id).
steps	array of Executable	yes	—
requirements	array of WorkflowRequirement	no	Central, self-targeting requirement declarations. Opaque to the framework; interpreted by the configured RequirementResolver keyed on requirement type.

Definitions

WorkflowRequirement

Property	Type	Required	Description
id	string	yes	Unique requirement id within the workflow.
type	string	yes	Opaque requirement type; interpreted by the configured RequirementResolver. Not interpreted by the framework core.
scope	enum (WORKFLOW, STEP, STEP_ACTION)	yes	—
stepId	string	no	Target step id when scope is STEP or STEP_ACTION.
action	string	no	Opaque target action when scope is STEP_ACTION.
required	boolean	no	Whether the workflow cannot run unless this requirement resolves.
default	object	no	Optional opaque default payload; carried as raw JSON and never interpreted by the framework.
resolution	enum (INSTALL, RUN_START, INSTALL_OR_RUN_START, DEFERRED)	yes	—

Executable

No properties.

StepDefinition

Property	Type	Required	Description
kind	const STEP	yes	—
stepId	string	yes	—
name	string	yes	—
behaviour	StepBehaviour	yes	—
contextMapping	ContextMapping	no	—
stepPrompt	string	no	Optional prompt content for the step; may be blank depending on behaviour.
maxUserPromptRounds	integer	no	Maximum blocking USER_PROMPT pauses for this step before the run fails.
modelTier	enum (LITE, STANDARD, POWERFUL, null)	no	Optional capability tier overriding the agent tier for this step. A raw model pin always wins over the tier. Null inherits the agent tier.
estimatedInputTokens	integer	no	Optional execution-estimation hint: expected input tokens consumed by this step. Advisory only; never affects runtime behaviour.
estimatedOutputTokens	integer	no	Optional execution-estimation hint: expected output tokens generated by this step. Advisory only; never affects runtime behaviour.

BlueprintRef

Property	Type	Required	Description
kind	const BLUEPRINT_REF	yes	—
blueprintId	string	yes	—

StepBehaviour

Property	Type	Required	Description
type	enum (AGENT, SPAR, WORKFLOW, INPUT, RESOURCE, BRANCH, FAIL, RETRY_PREVIOUS, VALIDATE, ASSIGN_CONTEXT, AGGREGATE)	yes	—

AgentBehaviour

Property	Type	Required	Description
type	const AGENT	yes	—
agentRef	string	yes	—
transition	StepTransition	yes	—
retryPolicy	RetryPolicy	no	—

SparBehaviour

Property	Type	Required	Description
type	const SPAR	yes	—
agentRef	string	yes	—
sparConfig	SparConfig	yes	—
transition	StepTransition	yes	—
retryPolicy	RetryPolicy	no	—

WorkflowBehaviour

Property	Type	Required	Description
type	const WORKFLOW	yes	—
workflowRef	string	yes	—
transition	StepTransition	yes	—

InputBehaviour

Property	Type	Required	Description
type	const INPUT	yes	—
artifactId	string	yes	—
transition	StepTransition	yes	—

ResourceBehaviour

Property	Type	Required	Description
type	const RESOURCE	yes	—
resourcePath	string	yes	Resource path resolved by the runtime resource resolver under allowed roots.
contextKey	string	yes	Context key under which the resource content is stored.
transition	StepTransition	yes	—

BranchBehaviour

Property	Type	Required	Description
type	const BRANCH	yes	—
contextKey	string	yes	—
branches	object	no	—
predicates	array of BranchPredicate	no	Ordered predicates evaluated before the exact-match branches; first match wins.
defaultBranch	Executable	no	—
failOnUnmatched	boolean	no	When true, an unmatched value with no defaultBranch fails the run instead of completing.

BranchPredicate

Property	Type	Required	Description
kind	enum (MEMBER_OF, EMPTY)	yes	—
members	array of string	no	—
target	null | Executable	no	—

FailBehaviour

Property	Type	Required	Description
type	const FAIL	yes	—
reason	string	yes	—

RetryPreviousBehaviour

Property	Type	Required	Description
type	const RETRY_PREVIOUS	yes	—
retryStepId	string	yes	—
retryMode	enum (SINGLE_STEP, FROM_STEP)	yes	—
maxAttempts	integer	yes	—
fallback	Executable	yes	—

ValidateBehaviour

Property	Type	Required	Description
type	const VALIDATE	yes	—
validatorId	string	yes	Id of the ArtifactValidator applied to the captured artifacts.
requiredArtifacts	array of string	yes	Allowlist of artifact paths that must be exactly present (no unexpected files).
contextEqualityContracts	array of ContextEqualityContract	no	—

ContextEqualityContract

Property	Type	Required	Description
artifactPath	string	yes	—
jsonPointer	string	yes	—
contextKey	string	yes	—

AggregateBehaviour

Property	Type	Required	Description
type	const AGGREGATE	yes	—
aggregatorId	string	yes	Id of the registered ContextAggregator applied over this step's declared contextMapping input keys.
outputContextKeyPrefix	string	yes	Prefix every field returned by the aggregator is written under, joined with '.'.
transition	StepTransition	yes	—

AssignContextBehaviour

Property	Type	Required	Description
type	const ASSIGN_CONTEXT	yes	—
contextKey	string	yes	—
value	ScalarContextValue	yes	—

ScalarContextValue

Property	Type	Required	Description
type	enum (STRING, NUMBER, BOOLEAN)	yes	—
value	object	yes	—

StepTransition

No properties.

SparConfig

Property	Type	Required	Description
challengerAgentId	string	yes	—
maxRounds	integer	yes	—
resolutionPrompt	string	yes	—

RetryPolicy

Property	Type	Required	Description
allowRetry	boolean	no	—
allowRetryFromPrevious	boolean	no	—
maxAttempts	integer	no	—

ContextMapping

Property	Type	Required	Description
inputKeys	array of string	no	—
outputKeys	array of string	no	—