Workflows

TL;DR

• A type is a capability; a run is one execution. Types have dotted names and typed schemas. Runs have a workflow_id, a state, and a history.
• Three kinds of type: state_machine (atomic, PENDING → COMPLETED | FAILED), data (read-only lookups, safe to start), and dag (multi-step, layers of steps).
• The engine is event-sourced. A run is an append-only log of transitions, so history is complete and recovery is deterministic.
• Compositions are your logic. Chain existing types with explicit input mapping, validate against the live catalog, compile to a normal DAG. No code.
• The same loop everywhere. Discover, schema, prerequisites, start, watch, recover, whether from the console, an SDK, or an assistant over MCP.

Types vs runs

Types: registered capabilities

A type is a named, typed capability the platform knows how to run. Atomic types are named {provider}.{service}.{operation} and grouped into namespaces you can browse. Each type declares:

• A typed input and output schema, validated before a run starts and before a result is accepted.
• Prerequisites: what must exist first, most often a cloud connection. When a schema reports has_prerequisites: true, fetch the setup guide before starting.
• Metadata an assistant uses to choose well: workflow_kind (state_machine, data, or dag), featured (a human-runnable entry point; internal *.prepare and *.finalize sub-steps are not), and scope (organization, library, or none).

The catalog is the source of truth. Never invent a type name. Quote the exact name the engine returns.

list_workflow_namespaces()
list_workflow_types(prefix="aws.s3.")
get_workflow_schema("aws.s3.create_bucket")          → fields, read_only, has_prerequisites
get_workflow_prerequisites("aws.s3.create_bucket", variant="aws")

Runs: executions with a workflow_id

A run is one execution of a type. You start it with inputs, get back a workflow_id, then watch it to a terminal state, inspect its history, or retry it if it failed.

start_workflow("aws.s3.create_bucket", { "bucket": "my-bucket", "connection_uuid": "…" })
  → { "workflow_id": "wf_8f3c…", "status": "PENDING" }

watch_workflow("wf_8f3c…")          → blocks until COMPLETED or FAILED
get_workflow_history("wf_8f3c…")    → full append-only transition log

The event-sourced state machine

Every run, atomic or composed, executes on one event-sourced state machine. A run is not a row mutated in place. It is the replay of an append-only sequence of transitions. Current state is derived from history. Two properties follow:

The 3-state pattern

Atomic workflows follow one predictable shape. A run enters PENDING, auto-advances to execute its single operation, and lands in exactly one terminal state.

This uniformity is the point. Because every primitive obeys the same contract, the console, SDKs, and AI assistants treat every capability identically: discover it, start it, watch it to one of two terminal states.

DAGs: multi-step workflows

Real processes are many steps with data threaded between them. A DAG workflow arranges atomic steps in layers: layers run in order; steps within a layer can run together. Each step still obeys the 3-state contract, so a DAG is a composition of primitives, not a different runtime. Ask get_workflow_dag(type) for the layer and step structure.

A DAG step that fails on a fixable precondition can park in remediation_pending instead of compensating. The run's state_data.remediation envelope names the fix. Apply it, then call resolve_workflow(workflow_id, "remediated") and the engine re-runs only the failed step. Resolve "denied" to compensate and fail.

Middleware, plugins, and RBAC

Every transition runs through a middleware pipeline with a plugin system, so validation, authorization, and observability live in one place. RBAC is enforced in the engine through declared capability metadata. Permissions are checked the same way for every run, whether it started from the console, an SDK, the API, or an assistant over MCP. There is no back door.

Concurrency

To keep a single run's transitions serialized, the engine takes a per-run lock. No two workers can advance the same run into conflicting states. Concurrency safety is by construction.

Async

Work that takes time never blocks your call. The engine publishes a workflow.transition message; a dedicated consumer picks it up and advances the run out of band. You start a run and watch it. There is no queue to provision.

Retries, recovery, and stuck runs

The MCP prompt template diagnose_workflow_run walks exactly this sequence for a given workflow_id.

Compositions: virtual workflows

The platform ships thousands of capabilities, but your business logic is the order you run them in and the data you thread between them. Compositions (virtual workflows) express that by chaining existing workflows, with no code.

You declare which workflows run, in what order, with which inputs. The platform validates that against the live catalog and compiles it into a regular engine DAG. From then on a composition runs, is watched, and is retried like any other run.

The three building blocks

Input mapping

Every step input is explicit about its source. There is no implicit global scope and no runtime string templating. Three sources:

Because mappings are explicit, the whole composition is type-checked before it runs. Errors are precise (which step, which reason) rather than runtime surprises.

Validate, compile, stamp, run

Authoring is a deterministic pipeline driven by the composition.save workflow: validate the definition, compile it to a DAG, stamp the compiled cache, and the type becomes runnable as virtual.<uuid>@<version>.

1. Structure: layers are acyclic, step names are unique.
2. References: every referenced type exists in the installed catalog.
3. Compatibility: every input mapping resolves to a compatible source field and type.

Authoring shape

You author the definition. Each step points at a real workflow type and declares an input_mapping from each parameter to its source (input, step, or static):

{
  "name": "vw_demo",
  "version": "1.0",
  "layers": [
    { "name": "layer_1", "steps": [
        { "name": "s1", "workflow_type": "aws.s3.create_bucket",
          "input_mapping": { "bucket": { "source": "input", "field": "bucket_name" } } }
    ] },
    { "name": "layer_2", "steps": [
        { "name": "s2", "workflow_type": "aws.s3.put_bucket_tagging",
          "input_mapping": {
            "bucket":  { "source": "step",   "step": "s1", "field": "bucket_name" },
            "tagging": { "source": "static", "value": { "TagSet": [{ "Key": "env", "Value": "demo" }] } }
          } }
    ] }
  ]
}

The compiled form is a server-owned cache: the per-step input_mapping becomes input, a step source becomes state_data, the workflow is marked type: "dag", and a metadata block with content_hash and compiled_format_version is stamped on. The definition stays the durable source of truth; the engine can always recompile from it.

Validation returns two lists of plain strings, precise enough to feed straight back into an authoring loop:

{
  "errors": [
    "step 's2': unknown workflow type 'aws.s3.put_bucket_taging'; did you mean 'aws.s3.put_bucket_tagging'?"
  ],
  "warnings": []
}

Why this is how apps express logic

A composition is just another workflow type, which means it can be exposed to your app's end-users through App Enablement. A signed-in user invokes it; Orkestia runs it scoped to that user. Your app's business logic lives on the platform with no backend of your own and no database credentials in your code.

Ask your AI assistant

List the workflow types under "aws.s3." with their workflow_kind, and tell me which ones are featured entry points.

Show me the DAG structure of <dag_workflow_type> as layers and steps.

Read concept://dag, then design a composition that creates a bucket, enables versioning, and applies a tag. Validate it but do not save it.

Workflow <workflow_id> failed. Read its history with state data and tell me the failing step and the reason.

For AI agents

Where this fits

Next

• Build a composition step by step: Virtual workflows guide.
• Let AI design one: Building with DGI.
• Drive capabilities from an assistant: Connect an AI assistant and MCP integration.
• The complete catalog: reference.orkestia.dev and the workflow types registry.