Workflows
How a workflow chains skills into a runnable protocol, and what to understand before you build one.
A workflow is a graph that chains skills into a protocol. It lives in your project as a single JSON file at workflows/<id>.json, and it holds two lists: nodes and edges. Nodes are the steps. Edges connect one node to the next and carry a condition that the executor reads to decide which way to go (default, on_success, on_failure, and a few branching variants).
There are five node types: start, end, skill, loop, and conditional. In practice most workflows are a linear chain: a start node, a run of skill nodes wired one to the next, then an end node. Loop and conditional nodes exist for protocols that repeat a section or branch on a result, but you do not need them to build something that runs. A skill node names a skill_id from your skill catalog and supplies a parameters object for it.
Inputs are references, not literals
A workflow declares an inputs array. Each input has a name, a type (string, int, float, object, or structured), and a flag for whether it accepts multiple values. A skill node's parameter can then bind to one of those inputs by reference instead of holding a fixed value. The reference is written as {"$input": "volume"}, and the executor resolves it to a real value at run time.
This is the whole reason one workflow can serve many runs. Hard-code volume: 5 into a node and the workflow means one thing forever. Bind that parameter to an input and the same graph runs against a different plate, a different volume, or a different destination, with the value supplied when someone presses run.
A workflow does not contain a bench
A workflow names skills. It does not contain objects. The objects come from the world you run it against, and inputs typed object are filled from that world's object list when the run is set up. This separation is deliberate: the same workflow can run against a simulated bench and a physical one, or against two labs with different hardware layouts, without you editing the graph. Build the graph once, then point it at whichever world describes the bench in front of you.
Canvases
By default, the app generates an input form from your inputs array. Once a workflow has more than a couple of inputs, or the inputs are structured data that a flat form handles poorly, you can replace that form with a canvas: a React component stored under your project's canvas/ folder and referenced from the workflow's canvas_ui block. The canvas emits values matching the same input schema, so nothing about the graph changes.
Making one
Run zeon new workflow my_workflow inside a project. That scaffolds workflows/my_workflow.json with the start and end nodes in place, ready for you to add skill nodes. To add a canvas later, run zeon new canvas my_workflow, which writes the component file and patches the canvas_ui block for you.
Skill nodes reference skills by
skill_id. If the skill does not exist in your project or catalog, the node will fail at run time rather than at save time. Confirm your skills are in place before wiring them together.
Where to read next
Build the graph: add skill nodes, wire edges, declare inputs, and bind parameters to them.
Replace the generated input form with a custom React screen.
Every field in the file, including node shapes and edge conditions.
The other half: the bench that supplies objects to your run.
Pick a world, fill the inputs, and watch it execute.
Updated 3 days ago