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, export your Workflow from 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 Workflow you construct, validates the definitions, and sends them to the platform. Use culvii dev for local iteration against your dev environment. The platform takes over execution from there.

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 can be called as a tool by an agent, see Tool call timeout before you build a step that waits on a human or a slow external call.