Skip to main content

Executing Workflows

The SDK builds workflow definitions; the Culvii platform runs them. You author a workflow with @culvii/kit, deploy it with @culvii/cli, and the platform handles runtime execution, pausing, and state management.

Inspecting the definition​

Convert your workflow into the JSON format the platform expects. This is useful for testing and debugging the shape you're about to deploy.

// Get the raw serialized definition
const definition = workflow.toJSON();

// Or get the validated runtime shape (throws if a connection points
// at a step that isn't in the workflow)
const runtimeShape = workflow.toRuntimeWorkflow();

Deploying your workflow​

You don't serialize and upload the workflow by hand. Instead, construct your Workflow in a file the CLI can discover (a .culvii.ts file, or a file listed under entrypoints: in culvii.yaml) and deploy it:

culvii deploy --env sandbox --workspace-slug my-workspace

The CLI evaluates your entrypoints, collects every resource (Workflow, MultiAgentEngine, Surface) you construct, validates the definitions, and sends them to the platform. Construct resources inside named functions called at the bottom of the file; culvii dev and culvii deploy discover resources when their constructors run, rather than relying on export as a substitute.

Pausing and resuming​

Set pauseAfterExecution: true on a step's params (or attach a Surface to its wait slot, which sets that flag for you) and the platform pauses the run there instead of continuing. It's durable: state is held for as long as it takes, whether that's seconds or weeks.

Resuming isn't something you build. A person approves or rejects the paused step from the Console's Inbox, and the run continues or stops from there. If your workflow is called as a tool by an agent, the parent agent execution also suspends durably until the workflow finishes (see Durable workflow tool execution).