Skip to main content

Workflow Configuration & Lineage Model

A runnable workflow isn't a single record — it's the apex of a lineage of configuration that resolves, at launch, into an immutable snapshot. Understanding that lineage explains both how operator control works and how validity is derived rather than stored.

The two configuration chains​

A workflow references two bundles:

  • a workflow configuration set — a list of agent assignments, each binding an agent to a model, a prompt, a temperature, and a max-tokens value. Prompts resolve through the three-layer model (family → prompt → active version), so an assignment pins the active version at run time.
  • a service configuration set — a list of service assignments, each binding a service to a method, headers, and variable values.

The workflow also carries its own metadata: the engine it runs on, its guardrails (max cost, max time), its eligible input statuses and single resulting status, and any system-wide config overrides.

Validity is derived from upstream state​

No one marks a configuration "valid." Validity is computed from the health of everything it depends on: a workflow configuration set is valid only if every agent in it is enabled, each assigned model is enabled, and each assigned prompt version (and its family) is enabled. Disable anything upstream and the derived validity flips — which is the disable-cascade seen from the configuration's side. The core exposes a single service, getAvailableWorkflows(workspaceId), that folds all of this together (enablement, entity-type match, status eligibility, dependency validity, a valid engine) — and plugins must use it rather than querying workflow rows directly.

Lineage collapses into a snapshot at launch​

At launch, this whole lineage is resolved and frozen. The core assembles the workflow_config_snapshot (agents/models/prompts) and service_config_snapshot (services with compiled URLs and headers) and stores them immutably on the execution. From then on the run reads the snapshot, not the live configuration — which is why editing a config never affects a run in flight, and why a retry reproduces the original exactly by replaying the same snapshots.

For traceability, the execution also keeps foreign keys back to the config rows it came from — but those are lineage/audit pointers; the snapshot is the source of truth for what actually ran.