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. Defines what scientific result is produced. | An ELISA assay, from sample preparation to detection |
| Phase | A logical stage of the scientific intent. Always ends in a stable checkpoint state. | Sample preparation, washing, detection |
| Step | The smallest scientific unit operation. Runs on exactly one device and is highly reusable. | 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