Workflows are the core building blocks of Sim Studio, representing directed acyclic graphs (DAGs) of interconnected blocks that define AI agent behaviors and automation logic. A workflow consists of blocks (individual processing units), edges (connections between blocks), and optional subflows (loop/parallel containers for complex control flow). This page provides an overview of workflow architecture, state management, and the visual editing system.
For information about workflow execution mechanics, see Workflow Execution Engine. For details on real-time collaboration features, see Collaborative Editing. For persistence and deployment, see State Persistence and Deployment & Versioning.
A workflow is represented by the WorkflowState interface, which contains all the information needed to render, execute, and persist a workflow.
| Component | Type | Description |
|---|---|---|
blocks | Record<string, BlockState> | Dictionary of block configurations keyed by block ID |
edges | Edge[] | Array of connections between blocks |
loops | Record<string, Loop> | Dictionary of loop containers keyed by loop ID |
parallels | Record<string, Parallel> | Dictionary of parallel containers keyed by parallel ID |
lastSaved | number | Timestamp of last modification |
deploymentStatuses | Record<string, DeploymentStatus> | Deployment status per workspace |
needsRedeployment | boolean | Flag indicating workflow requires redeployment |
Sources: apps/sim/stores/workflows/workflow/types.ts162-178
Each block in a workflow contains:
Key Fields:
subBlocks: Configuration parameters for the block (e.g., API endpoint, model selection). apps/sim/stores/workflows/workflow/types.ts80outputs: Declared output fields that other blocks can reference via {{blockName.output}}. apps/sim/stores/workflows/workflow/types.ts81data.parentId: Reference to parent loop/parallel container (if nested). apps/sim/stores/workflows/workflow/types.ts47locked: Protection flag preventing editing by non-admins. apps/sim/stores/workflows/workflow/types.ts91Sources: apps/sim/stores/workflows/workflow/types.ts76-91 apps/sim/stores/workflows/workflow/types.ts45-68
Edges define the execution flow between blocks. Each edge specifies:
Handle Types:
source: Default outputsuccess: Successful execution patherror: Error handling pathcondition-{id}: Conditional routing (from condition/router blocks). apps/sim/lib/workflows/dynamic-handle-topology.ts1-50Sources: apps/sim/stores/workflows/workflow/types.ts162-178
Sim Studio uses a multi-store Zustand architecture to separate concerns and optimize rendering performance.
Sources: apps/sim/stores/workflows/registry/store.ts70-75 apps/sim/stores/workflows/workflow/store.ts114-117 apps/sim/stores/workflows/subblock/store.ts1-20
Manages workflow metadata and navigation state across all workflows in a workspace.
Key Responsibilities:
resetWorkflowStores. apps/sim/stores/workflows/registry/store.ts36-51Sources: apps/sim/stores/workflows/registry/store.ts70-121
Stores the complete state of the currently active workflow, including all blocks, edges, and subflow configurations.
Key Actions:
batchAddBlocks(): Add multiple blocks atomically, remapping IDs if necessary. apps/sim/stores/workflows/workflow/store.ts204-223batchRemoveBlocks(): Remove blocks and their descendants recursively. apps/sim/stores/workflows/workflow/store.ts315updateNodeDimensions(): Syncs ReactFlow measured dimensions back to the store. apps/sim/stores/workflows/workflow/store.ts123-152batchUpdatePositions(): Update block positions (for drag operations). apps/sim/stores/workflows/workflow/store.ts194Sources: apps/sim/stores/workflows/workflow/store.ts114-243
The workflow editor uses ReactFlow for the interactive canvas, with custom node and edge components.
Sources: apps/sim/app/workspace/[workspaceId]/w/[workflowId]/workflow.tsx:5-16, apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/workflow-block/workflow-block.tsx:40-53
The canvas renders three types of nodes, defined in the nodeTypes constant:
| Node Type | Component | Purpose |
|---|---|---|
workflowBlock | WorkflowBlock | Standard blocks (Agent, API, Function, etc.). apps/sim/app/workspace/[workspaceId]/w/[workflowId]/workflow.tsx:41-41 |
subflowNode | SubflowNodeComponent | Loop and parallel containers. apps/sim/app/workspace/[workspaceId]/w/[workflowId]/workflow.tsx:32-32 |
noteBlock | NoteBlock | Annotation-only blocks for documentation. apps/sim/app/workspace/[workspaceId]/w/[workflowId]/workflow.tsx:39-39 |
Sources: apps/sim/app/workspace/[workspaceId]/w/[workflowId]/workflow.tsx:1-100
Sim Studio implements real-time collaborative editing using a Socket.io-based operation queue with optimistic updates and server confirmation.
The useCollaborativeWorkflow hook provides high-level functions that wrap store mutations with operation queue emission. It handles event listeners for moves, parent updates, and diff operations. apps/sim/hooks/use-collaborative-workflow.ts34-113
Key Features:
useOperationQueue to manage outgoing changes and confirm/fail status. apps/sim/hooks/use-collaborative-workflow.ts143-148workflow-operation events to apply changes from other users. apps/sim/hooks/use-collaborative-workflow.ts161-175workflowId to prevent cross-workflow updates. apps/sim/hooks/use-collaborative-workflow.ts167-173Sources: apps/sim/hooks/use-collaborative-workflow.ts34-113 apps/sim/socket/constants.ts11-19
Workflows can be executed via the REST API or directly from the UI using the useWorkflowExecution hook.
The execution endpoint POST /api/workflows/[id]/execute handles both synchronous and asynchronous execution.
Execution Parameters:
input: Data passed to the Start block. apps/sim/app/api/workflows/[id]/execute/route.ts:81-81stream: Whether to stream execution events via SSE. apps/sim/app/api/workflows/[id]/execute/route.ts:79-79runFromBlock: Support for partial re-execution/debugging using a sourceSnapshot. apps/sim/app/api/workflows/[id]/execute/route.ts:94-115Sources: apps/sim/app/api/workflows/[id]/execute/route.ts:76-116
The DAGExecutor (aliased as Executor) orchestrates the execution flow. apps/sim/executor/index.ts6
Key Components:
BlockExecutor: Resolves inputs via VariableResolver, calls handlers, and persists outputs. apps/sim/executor/execution/block-executor.ts51-63WorkflowBlockHandler: Manages nested/child workflow execution, including call chain validation and depth limits. apps/sim/executor/handlers/workflow/workflow-handler.ts38-60useWorkflowExecution Hook: The UI entry point that manages execution state, console logging, and stream reconnection. apps/sim/app/workspace/[workspaceId]/w/[workflowId]/hooks/use-workflow-execution.ts:104-162Sources: apps/sim/executor/execution/block-executor.ts51-210 apps/sim/executor/handlers/workflow/workflow-handler.ts63-195 apps/sim/app/workspace/[workspaceId]/w/[workflowId]/hooks/use-workflow-execution.ts:1-150
Workflows are the fundamental abstraction in Sim Studio, implemented as:
WorkflowState.WorkflowRegistry, WorkflowStore, SubBlockStore).Executor using BlockExecutor and specific BlockHandler implementations.isBlockProtected. apps/sim/app/workspace/[workspaceId]/w/[workflowId]/utils/index.ts:65-65For execution mechanics, see Workflow Execution Engine. For deployment and versioning, see Deployment & Versioning.
Refresh this wiki