What is a workflow?
A workflow is the top-level executable process you write to achieve a scientific outcome. It coordinates timing, logic, data flow, and physical state across one or more instruments.
The automation hierarchy
UniteLabs workflows are built from four nested concepts:
| Concept | Role | Example |
|---|---|---|
| Workflow | The top-level process, defined by the scientific result it produces. | An ELISA assay, from sample preparation to detection |
| Phase | A group of steps that ends in a stable state a run can resume from. | Sample preparation, washing, detection |
| Step | A single action on one device. It completes or fails as a whole. | Shake a plate, seal a plate, aspirate 50 µl |
| Action | A device endpoint, generated from the device interface. Called inside steps, holds no logic. | shaker.shake_controller.set_rpm(300) |
Once started, a workflow creates a Run: a single execution of that workflow. Keep workflows, phases, and steps under version control in Git. To reuse phases and steps across workflows, collect them in a shared library inside your workflow repository. The workflow template does this in its shared/ package.
A minimal example
from unitelabs.sdk import __version__ as sdk_version
from unitelabs.sdk import get_logger, workflow
@workflow(name="Hello World")
async def hello_world(recipient_name: str = "world") -> None:
"""
Log a greeting and SDK version info to confirm the environment works.
Args:
recipient_name: Name to greet (default: "world").
"""
logger = get_logger()
logger.info(f"Hello, {recipient_name}!")
logger.info(f"UniteLabs SDK: {sdk_version}")
The @workflow decorator registers the function with the workflow engine. Phases are called like regular Python functions; the workflow engine handles scheduling, parallelism, and recovery.
What a workflow is responsible for
- Scientific goal: defined by the result it produces, not the hardware it uses
- Control flow: supports loops, conditionals, and branching
- State ownership: the workflow is the one place that keeps track of sample identity, lineage, and consumed resources across all phases
The Workflow concept page covers these properties in detail. For what happens at execution time, see Runs. For pausing a run to collect manual input, see Human in the Loop.
Run locally or on the platform
The same workflow file runs on your machine and on the platform, without code changes. During development, run it directly from your IDE or terminal. The pyproject.toml defines a script that calls the workflow, so you can run it like this:
uv run workflow
When you're ready for scheduled, tracked, or team-accessible runs, deploy the same file to the platform, with no code changes required. See Deploy a workflow for the deployment steps.
Next steps
- Workflow template: clone the reference workflows and run one in simulation
- Your first workflow: write and run a workflow end to end