UniteLabs

What is a workflow?

Workflows are the core automation building block in UniteLabs: reproducible, versioned processes that coordinate instruments, data, and scientific logic.
Prefer to start from a working example? Clone the workflow template: reference workflows (sanity check, liquid handling, HITL) you can run in simulation and deploy as-is.

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:

ConceptRoleExample
WorkflowThe top-level process, defined by the scientific result it produces.An ELISA assay, from sample preparation to detection
PhaseA group of steps that ends in a stable state a run can resume from.Sample preparation, washing, detection
StepA single action on one device. It completes or fails as a whole.Shake a plate, seal a plate, aspirate 50 µl
ActionA 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

w01-hello-world/src/w01_hello_world/workflow.py
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