Workflow Lifecycle

Every Agent Workflow moves through a defined set of states before it runs in production. This ensures that changes are reviewed before they affect live use.

There is no separate "Approved" state

A staged workflow moves straight to Published the moment a reviewer approves it — there's no intermediate "approved, not yet live" holding state or separate publish step. If you need multi-stakeholder sign-off before that happens, configure an Approval Matrix, which gates the same Approve action behind multiple decisions instead of one.

Status diagram

           ┌──────────────┐
           │    DRAFT     │  ← created here; editor is open
           └──────┬───────┘
                  │ Stage for Review
                  ▼
           ┌──────────────┐
           │  STAGED      │  ← locked for editing; awaiting review
           └──────┬───────┘
          ┌───────┴────────┐
          │                │
  Approve & Publish      Reject
          │                │
          ▼                ▼
   ┌─────────────┐  ┌─────────────┐
   │  PUBLISHED  │  │  REJECTED   │
   └──────┬──────┘  └──────┬──────┘
          │ Revise          │ Revise
          ▼                 ▼
   ┌─────────────────────────────┐
   │            DRAFT            │  ← back to editing
   └─────────────────────────────┘

States

The four real statuses (draft, staged, published, rejected) come straight from the workflow's status column — there is no fifth value.

Status	Who can edit	Who can run	Notes
Draft	Owner or write access	Editors (test runs only)	Default status on creation
Staged	Nobody	Nobody	Locked pending review
Rejected	Nobody until revised	Nobody	Reviewer sent it back with mandatory notes
Published	Nobody until revised	All users with run access	Live version in production

Transitions

Draft → Staged (Stage for Review)

Any editor with write access can stage a workflow for review. This locks the current graph so the reviewer sees exactly what was submitted.

When to stage: When you're satisfied with your changes and want a second pair of eyes before going live.

Graph validation is non-blocking at this step — staging itself isn't gated on it (only the default-skill system-prompt check below can actually block staging). Two independent validators surface warnings so you can fix problems before a reviewer sees them:

In the editor (client-side), the same check that runs before a test Run also runs when you click Stage for Review, and its warnings are shown as a toast:
- Duplicate node IDs
- Edges pointing to a node that no longer exists
- Routing-node (if_else/while_loop/classify) edges whose label doesn't match any current branch, or that have no label at all (an unlabeled edge from a routing node is always followed, regardless of the condition/classification result)
- Non-end nodes with no outgoing edge (dead ends)
- Nodes not reachable from the start node
On the server, every graph save runs the same structural validator used to gate publishing (see below), returning warnings alongside the saved workflow: unknown node types, dangling edge references, missing/duplicate start node, missing end node, nodes disconnected from start, classify nodes with no categories, the graph exceeding WORKFLOW_MAX_NODES (default 500), and syntax errors in if_else/while_loop/transform/set_state expression fields.

These structural problems become a hard block only later, at Staged → Published (Approve) — approving a staged workflow re-runs the server-side validator and rejects the transition with HTTP 422 if any structural problems remain.

Stage gate: default skill must have a system prompt

In addition to graph validation, the API enforces one extra pre-condition at staging time:

The workflow's default skill must have a non-empty system prompt.

If the default skill's system_prompt is blank or contains only whitespace, staging is blocked and the API returns HTTP 422 with the message:

Default skill has no system prompt. Add a system prompt before staging.

This gate only fires when some node in the current graph still actually references the default skill — an unused, orphaned default skill (e.g. every agent node was rewired to a different skill or switched to inline-prompt mode) doesn't block staging.

To fix it: Open the workflow's default skill (shown in the editor sidebar as "Workflow Name [wfid]"), add a meaningful system prompt, save, then retry staging.

Why is this enforced?

The default skill is the primary agent configuration backing your workflow. An empty system prompt means every agent node that inherits the default skill will run without instructions — a near-certain source of unhelpful or incorrect outputs. The gate prevents accidental staging of half-configured workflows.

Staged → Published (Approve) / Rejected (Reject)

Lifecycle managers, space admins, and admins see staged workflows in the Review Queue. They can:

Approve — moves the workflow directly to Published. The structural validator (see above) runs again and blocks the transition with HTTP 422 if it finds any problems. On success, a version snapshot is created automatically, and every skill the graph actually depends on (the default skill plus any skill_id referenced by an agent/classify/guardrails node) is auto-published too — a published workflow can't end up depending on a still-draft skill.
Reject — returns it to Rejected status. The API requires a non-empty notes field explaining why; there's no way to reject silently.

The reviewer cannot edit the graph during this phase — only approve or reject. See Review Queue for the full review interface and the optional multi-stage Approval Matrix.

Rejected → Draft (Revise)

After a rejection, the editor clicks Revise. This unlocks the graph and returns it to Draft status so the team can address the reviewer's feedback.

Published → Draft (Revise)

An admin or space admin can also click Revise on a published workflow to pull it back to Draft for a major revision — the owner/regular editor role that can revise a rejected workflow cannot do this to a published one; that pullback needs space_admin or admin.

Lifecycle actions in the editor

The header bar of the editor shows the current status badge and the available action button:

Current status	Button shown	Who sees it
Draft	Stage for Review	Owner / write access
Staged	Approve & Publish / Reject	`lifecycle_manager`, `space_admin`, `admin`
Rejected	Revise	Owner / write access
Published	Revise	`space_admin`, `admin` only — pulls the workflow back to Draft so it can be edited again

Published → Draft (Revise)

Clicking Revise on a published workflow immediately returns it to Draft status. The workflow remains accessible via the API while revisions are in progress — you must re-publish (stage, then approve again) to make the updated graph live. Existing in-flight runs are not affected.

Publishing creates a version snapshot

Approving a staged workflow automatically creates a version snapshot of the graph before it goes live. You can roll back to any previous version from the Versioning panel.

Moving a published workflow to another environment

Once a workflow is Published, a Promote to catalog… button appears. It copies the workflow into a different catalog or space as a new Draft — see Promote to catalog.

Running workflows by status

Status	Test runs (editor)	Production runs (API)
Draft	✅ Editors can run	❌ Not available
Staged	❌ Locked	❌ Not available
Rejected	❌ Locked until revised	❌ Not available
Published	✅ All users	✅ All users with access

Role reference

Action	Required role
Create a workflow	Workspace > Agent Workflows: Write
Edit graph (Draft status)	Workflow owner or Write access
Stage for review	Workflow owner or Write access — `agent_developer`, `lifecycle_manager`, `space_admin`, or `admin`
Approve & Publish / Reject	`lifecycle_manager`, `space_admin`, or `admin`
Revise a rejected workflow	Workflow owner or Write access
Revise a published workflow	`space_admin` or `admin` only
Run a published workflow	Workflow Run permission

admin additionally has two shortcuts no other role has: staging directly to published (skipping review), and pulling a staged workflow straight back to draft.

See Permissions for configuration details, and Review Queue for the full approve/reject interface and audit log.

Status diagram​

States​

Transitions​

Draft → Staged (Stage for Review)​

Stage gate: default skill must have a system prompt​

Staged → Published (Approve) / Rejected (Reject)​

Rejected → Draft (Revise)​

Published → Draft (Revise)​

Lifecycle actions in the editor​

Running workflows by status​

Role reference​

Status diagram

States

Transitions

Draft → Staged (Stage for Review)

Stage gate: default skill must have a system prompt

Staged → Published (Approve) / Rejected (Reject)

Rejected → Draft (Revise)

Published → Draft (Revise)

Lifecycle actions in the editor

Running workflows by status

Role reference