Skip to main content

Workflow and agent lifecycle

A workflow or agent moves through the same basic arc: it starts as an ephemeral draft tied to your culvii dev session, becomes a permanent versioned record when you deploy, and can be marked active so it actually runs. There's no draft state in production. Once you deploy, everything from there on is versioned.

Draft: what culvii dev creates​

While culvii dev is running, every save updates a draft scoped to your session (sessionId). Drafts have no version number and no audit record. They're not real deployments yet, just a live preview so you and your team can watch a run in the Console while you iterate. When the session ends, the draft is orphaned; it leaves nothing permanent behind.

Deploying: how a version gets created​

culvii deploy --env sandbox --workspace-slug procurement

This validates the definition, checks workspace access, and writes an immutable record with an incrementing version number: v1 on the first deploy, v2 on the next, and so on. A deployed version can't be edited; to change it, deploy again.

Multiple versions of the same workflow or agent can exist side by side in a workspace and environment, but only one can be active at a time. For a workflow, that's the version that actually fires on triggers, things like cron schedules, webhooks, and event subscriptions. For an agent, that's the version a core.agent step resolves to when it invokes the agent by its reference key. Deploying a new version doesn't activate it automatically; that's a separate step in the Console (or the platform API), so a bad deploy doesn't silently start taking over from a working one.

What this buys you in practice​

  • Iterating fast doesn't create noise. You can save a file two hundred times in a culvii dev session and the platform ends up with one draft, not two hundred versioned records.
  • Deploys are deliberate, activation more so. Most teams wire culvii deploy to CI on merge, then activate manually (or via a separate, reviewed step) once sandbox looks right.
  • Rollback doesn't need a rebuild. If the active version misbehaves, activate an older one from the Console.

Surfaces don't work this way​

A surface also gets an ephemeral draft from culvii dev and an immutable version from every culvii deploy, but it has no active/inactive exclusivity at all. There's no single version that's "the live one." Every deployed version stays independently resolvable: an unpinned reference always follows whatever the latest published version is, and a pinned reference keeps using its specific version number forever, even after newer ones ship. Nothing about deploying v5 changes what v3 does for something still pinned to it. See Surfaces overview for the full model.

What's not there yet​

There's no formal state-machine API for workflow or agent lifecycle (no status enum you can query). The model above is what the underlying data actually tracks, described in plain terms rather than named states. If you're building automation against lifecycle transitions, don't hardcode assumptions about exact status strings; ask us what's stable to depend on for your use case.

See Two version-control systems for how this relates to git.