Skip to main content

Workflow Studio (Production Guide)

Workflow Studio is the production workflow authoring and control surface behind /workflow/builder.

What You Actually Get​

  • Canvas-first authoring (React Flow) with tasks, edges, module stacks, and inspector-driven edits
  • Undo/redo history and persisted canvas recovery for interrupted sessions
  • Module-aware composition using catalog metadata + backend metadata fetch
  • Runtime controls for start/stop/status via WorkflowCommandService
  • Save hardening with graph validation, atomic save path, optimistic-lock conflict detection, and fallback persistence

Routes and Operating Context​

  • /workflow: workflow hub
  • /workflow/builder: primary builder UI
  • /workflow-designer/:workflowId: targeted workflow editing context
  • /admin/ops: admin operations

All core workflow authoring routes are authenticated surfaces.

Save Model (Important)​

Workflow Studio validates graph shape before save, including:

  • cycle detection
  • orphan task detection
  • conditional-edge checks
  • task-without-module warnings

Primary save path uses WorkflowGraphSaveService (/v1/vaiworkflow/saveGraph) with:

  • optimistic-lock conflict handling (409)
  • retry/backoff for transient failures
  • validation-error short-circuiting

When atomic graph save is unavailable, the UI falls back to legacy persistence to avoid data loss during active operations.

Runtime Control APIs in Use​

Common command endpoints behind the UI include:

  • GET vaiworkflow/start/{workflowId}
  • GET vaiworkflow/stop/{workflowId}
  • GET vaiworkflow/status/{executionId}
  • POST vaiworkflow/execute/{workflowId}

These are consumed through the typed Redux service layer.

Practical Build Sequence​

  1. Create/load workflow in /workflow/builder.
  2. Add tasks and connect flow edges.
  3. Attach ExecModules per task.
  4. Validate graph and save.
  5. Execute with runtime controls.
  6. Observe behavior in workflow monitors and Swarm Ops.

Common Failure Modes​

  • Conflict on save: another client modified the workflow; reload then reapply changes.
  • Graph validation block: remove cycles or fix conditional edge config.
  • Module persistence error: retry save; staged module data is retained for recovery.

For deeper command-assisted edits, pair this page with SageChat + Command System.