Docs Versioned Workflow Definitions

Versioned Workflow Definitions

A Workflow Definition is a versioned graph for repeatable autonomous work. It names exact capability versions and may carry versioned secret or connection references. Saving a draft does not execute anything.

Use the lifecycle in this order:

  1. create a draft;
  2. edit it with revision compare-and-swap;
  3. run a dry-run, which resolves the exact references without executing nodes;
  4. publish that exact revision.

Published versions are immutable. To change a published workflow, create a new semantic version. This keeps review records, audit evidence, and external authoring clients bound to the definition they reviewed. Runtime schedule and mission binding is not available yet.

Build it in the UI

Open Autonomous missions → Builder. The tab lists the workspace’s workflows with their version and status; New workflow starts a draft.

  1. Give the workflow an identifier and a version (1.0.0 is suggested).
  2. Pick a capability from the catalogue and press Add step. The first step becomes the entry; every next step continues the chain with a default transition, so a linear workflow needs one click per step. Capabilities you cannot use are shown disabled with the reason.
  3. For a branch, press Add transition: it proposes a way out that cannot close a loop. A step has one default transition; every other one needs a condition.
  4. Under Connections and secrets of a step, add a connection as id@revision and a secret by store, key and version.
  5. Save (Ctrl+S). Mistakes are listed above the graph while you edit — the step or branch at fault is outlined — and saving waits until they are fixed.
  6. Dry run checks capabilities, connections and secrets and shows the cost upper bound and any blockers.
  7. Publish becomes available after a successful dry-run of the saved draft, to members allowed to deploy. A published version is read-only; New version copies it into the next patch version as a draft.

The JSON button shows the same definition as text: copy it into the CLI or an SDK, or paste an edited one back with Apply JSON.

The examples use localhost:5770. Replace it with your Mockarty address. Use a concrete workspace namespace; * is never accepted for authoring.

Minimal definition

{
  "contractVersion": "mockarty.workflow/v1",
  "namespace": "sandbox",
  "id": "release-check",
  "version": "1.0.0",
  "status": "draft",
  "entryNode": "inspect",
  "nodes": [
    {
      "id": "inspect",
      "capability": {"key": "mission.inspect", "version": "1.0.0"}
    }
  ],
  "transitions": []
}

Capability identity uses the exact version returned by the capabilities catalogue. Secrets are referenced by store, key, and positive version; their values are never embedded in a definition. A connection is referenced as id@revision; dry-run accepts it only while that revision is the connection’s current one in the same workspace, so a rotated or revoked connection blocks publication until the definition points at the new revision.

Transition conditions use the versioned mockarty.expr/v1 expression contract. Dry-run compiles their syntax and rejects malformed delimiters, strings, or expressions; it does not execute a condition or a workflow node.

REST API

Create a draft:

curl -fsS -X POST http://localhost:5770/api/v1/namespaces/sandbox/workflow-definitions \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @workflow.json

Keep the returned revision. Resolve the exact draft, then publish the same revision:

curl -fsS -X POST \
  http://localhost:5770/api/v1/namespaces/sandbox/workflow-definitions/release-check/versions/1.0.0/dry-run \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"expectedRevision":1}'

curl -fsS -X POST \
  http://localhost:5770/api/v1/namespaces/sandbox/workflow-definitions/release-check/versions/1.0.0/publish \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"expectedRevision":1}'

Dry-run returns ready, a stable definition digest, resolved references, a cost upper bound, and blockers. It performs no provider call and starts no mission.

CLI

mockarty-cli --namespace sandbox workflow create --file workflow.json
mockarty-cli --namespace sandbox workflow dry-run --id release-check --version 1.0.0 --revision 1
mockarty-cli --namespace sandbox workflow publish --id release-check --version 1.0.0 --revision 1
mockarty-cli --namespace sandbox workflow list --status published

SDKs

Go

created, err := client.WorkflowDefinitions().CreateDraft(ctx, definition)
dryRun, err := client.WorkflowDefinitions().DryRun(ctx, "sandbox", "release-check", "1.0.0", created.Revision)
published, err := client.WorkflowDefinitions().Publish(ctx, "sandbox", "release-check", "1.0.0", created.Revision)

Python

created = client.workflow_definitions.create_draft(definition)
dry_run = client.workflow_definitions.dry_run("release-check", "1.0.0", created["revision"])
published = client.workflow_definitions.publish("release-check", "1.0.0", created["revision"])

Java

JsonNode created = client.workflowDefinitions().createDraft(definition);
JsonNode dryRun = client.workflowDefinitions().dryRun("sandbox", "release-check", "1.0.0", created.path("revision").asLong());
JsonNode published = client.workflowDefinitions().publish("sandbox", "release-check", "1.0.0", created.path("revision").asLong());

MCP tools

Agents use the same authority through workflow_definitions_list, workflow_definition_get, workflow_definition_save, workflow_definition_dry_run, and workflow_definition_publish. Publication still requires the caller’s deployment permission; MCP does not bypass workspace RBAC, licensing, reference checks, or the dry-run gate.

Conflicts and blockers

  • 400 invalid definition: the message names the rule that failed, for example node "deploy" is unreachable from entry or conditional branch "ok" requires an expression.
  • 409 revision conflict: fetch the exact version again before editing.
  • 409 dry-run required: the draft changed after its last successful dry-run, or it still has blockers.
  • 409 immutable: create a new semantic version instead of overwriting the published one.
  • 503 authority unavailable: do not publish from cached or guessed data; restore the dependency and repeat dry-run.

Publishing stores a reviewed, immutable authoring contract. It does not start a mission, and the current Autonomous Missions start flow does not consume a published Workflow Definition yet. See Autonomous Missions for the mission flows that are available now.

Previous
Quality Verdicts