Authoring a workflow

Write a workflow graph: start, skill and end nodes, edges, declared inputs, and parameter bindings.

Create one

zeon new workflow my_transfer
created workflow my_transfer
  - workflows/my_transfer.json

Edit workflows/my_transfer.json to get started.

The new file has a start node joined to an end node. Name workflows with lowercase letters, digits and underscores only: the CLI also accepts a hyphen, but the app refuses a workflow_id with one, and a canvas for it does not load.

A complete example

The starter's plate_transfer workflow, the starter project's active workflow, has one skill node:

{
  "workflow_id": "plate_transfer",
  "name": "Plate Transfer",
  "description": "The right arm moves the plate from one plate stand to another.",
  "version": "1.0.0",
  "author": "zeon",
  "created_at": "2026-11-14T00:00:00.000Z",
  "updated_at": "2026-11-14T00:00:00.000Z",
  "simulation_validated": false,
  "objects": [],
  "inputs": [
    {"name": "plate", "type": "object", "is_array": false, "description": "The plate to move", "defaultValue": "wellplate"},
    {"name": "from_stand", "type": "object", "is_array": false, "description": "The stand the plate is on", "defaultValue": "wellplate_stand_1"},
    {"name": "to_stand", "type": "object", "is_array": false, "description": "The stand to put the plate on", "defaultValue": "wellplate_stand_2"},
    {"name": "stand_anchor", "type": "string", "description": "Seat anchor on the destination stand", "defaultValue": "top_center"}
  ],
  "nodes": [
    {"node_id": "start", "type": "start", "label": "Start"},
    {"node_id": "transfer", "type": "skill", "skill_id": "move_plate", "label": "Plate: stand -> stand",
     "parameters": {"plate": {"$input": "plate"}, "source": {"$input": "from_stand"},
                    "destination": {"$input": "to_stand"}, "destination_anchor": {"$input": "stand_anchor"}}},
    {"node_id": "end", "type": "end", "label": "End"}
  ],
  "edges": [
    {"edge_id": "e0", "from_node": "start", "to_node": "transfer", "condition": {"type": "default"}},
    {"edge_id": "e1", "from_node": "transfer", "to_node": "end", "condition": {"type": "on_success"}}
  ],
  "canvas_ui": {"kind": "react", "source_ref": "canvas/plate_transfer_screen.tsx", "enabled": true, "version": 1}
}

workflow_id is the id (lowercase, underscores), name the display name the app shows and zeon run accepts. canvas_ui attaches its input screen (see Canvases). The file is strict JSON: no comments, no trailing commas.

Nodes

typeFieldsMeaning
startnode_id, labelWhere the run begins. One per workflow.
skillnode_id, label, skill_id, parametersRuns the skill skills/<skill_id>/ with the given parameters.
endnode_id, labelWhere the run ends.

label is what the graph and the run log show for the node.

Edges

Each edge goes from_node → to_node and has a condition:

condition.typeFollowed when
defaultAlways (use it on the edge leaving the start node).
on_successThe node before it succeeded.
on_failureThe skill before it raised an exception.

A skill fails by raising. When a skill node fails and has an on_failure edge, the run follows that edge. Without one, a simulated run fails; a run on real hardware stays at the failed step, shown as running and without an error, until Stop ends it. See Running a workflow on real hardware.

Inputs

inputs declares what a run takes:

FieldMeaning
nameStarts with a letter; letters, digits and underscores.
typestring, int, float, object (a world object), or structured (schema-based data).
is_arraytrue when the input takes a list.
descriptionShown next to the field in the app.
defaultValueUsed when a run does not give a value. For an object input, the object's instance id in the world.

A run's values come from the app's Inputs tab or its canvas, or from zeon run NAME -i name=value. An input with no value and no defaultValue is left unbound: the skill parameter it feeds is not passed, and the skill's own default applies. When that skill parameter has no default either, the run is refused before it starts. The app's Run and zeon run behave the same.

An object input's value is the object's instance id. A run also accepts the object's display name, or an object type the loaded world has exactly one instance of, and maps it to the instance id before the run starts. A display name that several objects share is refused with their ids.

Before a run starts, the inputs are checked against the workflow and its skills: a value of the wrong type for an int, float or bool input or skill parameter, a required skill parameter that nothing sets, and a node naming a skill the project does not have are refused, and nothing runs. The message names the node, the skill, the input and its type. zeon run also refuses an -i name the workflow does not declare.

Node parameters

A skill node's parameters map the skill's parameter names (its Python function's arguments) to values:

ValueExampleThe skill receives
A literal"lid": "open", "volume_ul": 50The value.
An input"plate": {"$input": "plate"}The run's value for that input. An object input arrives as a reference to that world object.
An object"plate": {"object_ref": "wellplate"}A reference to the world object with that instance id.

Run it

zeon sync
zeon run "Plate Transfer" --timeout 600

zeon run runs the workflow file as it was last pushed and loaded on your instance. It finds the workflow by workflow_id, file name or display name (case does not matter; when two workflows share a display name, use the id). In the app, select the workflow on the run screen, check the Inputs tab, and click Run.

To give a workflow its own input screen, add a canvas. For every field of the file, see the workflow file reference.


Did this page help you?