k-dense-ai/scientific-agent-skills/opentrons-integration

Opentrons Integration

Overview

Create production-minded Python Protocol API v2 protocols for Opentrons Flex and OT-2. This skill covers protocol structure, hardware and deck configuration, liquid handling, runtime customization, module control, simulation, and safe deployment.

The verified baseline as of 2026-10-01 is:

• opentrons==10.0.0 for reproducible Flex simulation.
• opentrons==9.0.0 for local OT-2 API 2.28 compatibility simulation.
• Flex supports API levels 2.15 through 2.30 on current software.
• OT-2 supports API levels 2.0 through 2.28 on current software.
• API 2.29 and later are Flex-only at this baseline. Keep OT-2 at 2.28 or lower.
• Bundled Flex templates retain API 2.29 because step grouping is their newest

required feature. API 2.30 fixes start-only meniscus aspiration.

• The 10.0.0 library reports a local maximum of 2.31, ahead of the documented

robot maximum 2.30. Do not infer robot support from that constant.

Read references/sources.md for the upstream documentation used for this snapshot. Recheck the official versioning page before targeting newer robot software.

Safety Boundary

Opentrons protocols control physical equipment. Never treat successful Python syntax or local simulation as permission to run on a robot.

Before live execution:

1. Simulate locally with the same pinned opentrons version used for authoring.
2. Import the protocol into the correct Opentrons App and require successful

analysis.

1. Verify robot model, software, pipettes, mounts, modules, adapters, labware

definitions, deck fixtures, tip count, source volumes, dead volumes, and destination capacity.

1. Review the run preview and deck map with the operator.
2. Perform a slow dry run with nonhazardous liquid when geometry, custom

labware, partial tip pickup, or gripper moves are new.

1. Keep the emergency stop accessible and follow site-specific biosafety,

chemical-safety, and contamination-control procedures.

Simulation cannot verify physical calibration, liquid properties, meniscus behavior, labware manufacturing tolerances, cap or seal removal, tubing, or all possible collisions.

Choose the Right Interface

Use this skill for Python files imported into the Opentrons App and run through the Protocol API.

• Use Protocol Designer for supported no-code workflows.
• Use PyLabRobot for a hardware-agnostic workflow spanning vendors.
• Treat the robot's HTTP API as a separate integration surface. If direct HTTP

control is explicitly required, use the OpenAPI document served by the target robot and do not infer endpoints from Protocol API methods.

Required Intake

Do not write final protocol code until these facts are known:

• Robot: Flex or OT-2, plus installed robot software.
• Pipette model, volume range, channel count, and mount.
• Modules and generations; Flex Gripper or Stacker availability.
• Exact labware API load names and custom definition files, if any.
• Deck fixtures: Flex trash bin, waste chute, staging slots, or Stackers.
• Source volumes, destination volumes, dead volume, mixing needs, and liquid

characteristics.

• Tip policy: contamination boundaries, reuse policy, filters, partial pickup,

and total tips.

• Operator interventions, incubation timing, runtime parameters, and output

files.

• Acceptance criteria: tolerated volume error, required controls, and dry-run

plan.

If any physical configuration is uncertain, produce a parameterized draft and an explicit assumptions list rather than guessing.

Install and Simulate

Flex:

uv run --no-project --isolated --python 3.12 --with "opentrons==10.0.0" opentrons_simulate protocol.py

OT-2 API 2.28:

uv run --no-project --isolated --python 3.12 --with "opentrons==9.0.0" opentrons_simulate protocol.py

The 10.0.0 package rejects OT-2 protocols after the Flex/OT-2 release-line split. Always complete OT-2 analysis in the current OT-2 App.

For a dedicated Flex environment:

uv venv --python 3.12 .venv-opentrons
uv pip install --python .venv-opentrons/bin/python -r skills/opentrons-integration/requirements-flex.txt
.venv-opentrons/bin/opentrons_simulate protocol.py

Use requirements-ot2.txt instead for an OT-2 compatibility environment. On Windows, invoke the executable from .venv-opentrons\Scripts\opentrons_simulate.exe. Local simulation is for Python protocols; import Protocol Designer JSON files into the appropriate Opentrons App instead.

Protocol Skeletons

Flex, API 2.29

For Flex, requirements is mandatory. Put apiLevel only in requirements, not in both metadata and requirements.

from opentrons import protocol_api
metadata = {
    "protocolName": "Flex transfer",
    "author": "Your Name",
    "description": "Transfer buffer into a plate.",
}
requirements = {"robotType": "Flex", "apiLevel": "2.29"}
def run(protocol: protocol_api.ProtocolContext) -> None:
    tips = protocol.load_labware(
        "opentrons_flex_96_tiprack_200ul", "D1"
    )
    reservoir = protocol.load_labware("nest_12_reservoir_15ml", "D2")
    plate = protocol.load_labware("nest_96_wellplate_200ul_flat", "C2")
    protocol.load_trash_bin("A3")
    pipette = protocol.load_instrument(
        "flex_1channel_1000", "left", tip_racks=[tips]
    )
    pipette.transfer(
        100,
        reservoir["A1"],
        plate["A1"],
        new_tip="always",
    )

OT-2, API 2.28

For OT-2 API 2.15 and later, a requirements block is recommended. OT-2 has a fixed trash in slot 12; do not call load_trash_bin().

from opentrons import protocol_api
metadata = {
    "protocolName": "OT-2 transfer",
    "author": "Your Name",
}
requirements = {"robotType": "OT-2", "apiLevel": "2.28"}
def run(protocol: protocol_api.ProtocolContext) -> None:
    tips = protocol.load_labware("opentrons_96_tiprack_300ul", "1")
    reservoir = protocol.load_labware("nest_12_reservoir_15ml", "2")
    plate = protocol.load_labware("nest_96_wellplate_200ul_flat", "3")
    pipette = protocol.load_instrument(
        "p300_single_gen2", "left", tip_racks=[tips]
    )
    pipette.transfer(100, reservoir["A1"], plate["A1"])

Use the lowest API level that provides every required feature when a protocol must run across a mixed software fleet. Use the current maximum only when the workflow needs its behavior or capabilities.

Authoring Workflow

1. Select robot and API level

Check the maximum supported API in the App under the robot's advanced settings. Map every requested feature to its minimum API level using references/api_reference.md.

Important gates:

• 2.20: CSV runtime parameters, liquid presence detection, expanded partial

nozzle layouts.

• 2.21: Absorbance Plate Reader.
• 2.22: current labware-level liquid loading methods.
• 2.23: meniscus locations and labware lids.
• 2.24: liquid classes and liquid-class complex commands.
• 2.25: Flex Stacker and Flex 96-Channel 200 µL pipette.
• 2.27: dynamic pipetting and concurrent module actions.
• 2.28: 20 µL Flex tips, improved partial-tip return, and thermocycler ramp rate.
• 2.29: step grouping; Flex only at the verified baseline.
• 2.30: aspirating at meniscus(target="start") without an end_location.

2. Build the deck explicitly

• Use exact load names from the official Labware Library.
• Load Flex trash bins or the waste chute explicitly.
• Account for module footprints, staging slots, Stacker shuttles, gripper paths,

and tall-labware adjacency.

• Load labware on adapters or module contexts in the documented order.
• Never substitute a similarly named labware definition; geometry and offsets

are part of the protocol's safety model.

See references/modules_and_deck.md.

3. Select pipettes and tips

Current load names are:

• Flex: flex_1channel_50, flex_1channel_1000,

flex_8channel_50, flex_8channel_1000, flex_96channel_200, flex_96channel_1000.

• OT-2 GEN2: p20_single_gen2, p20_multi_gen2,

p300_single_gen2, p300_multi_gen2, p1000_single_gen2.

Check that every requested volume is within the configured pipette and tip range. For Flex 50 µL pipettes handling 1–4.9 µL, call configure_for_volume(volume) while empty before pickup; low-volume mode caps the pipette at 30 µL. A 100 nL operation is not an Opentrons pipetting task.

4. Choose a liquid-handling layer

• Use aspirate(), dispense(), mix(), air_gap(), blow_out(), and

touch_tip() for explicit control.

• Use transfer(), distribute(), and consolidate() for standard movements.
• On Flex, consider transfer_with_liquid_class(),

distribute_with_liquid_class(), or consolidate_with_liquid_class() for Opentrons-verified aqueous, volatile, or viscous behavior.

• Use dynamic start/end locations or dynamic_mix() only when API 2.27+ and the

geometry has been reviewed.

Model contamination boundaries before optimizing tips. For standard distribute() and consolidate(), new_tip="always" still uses one tip for the complex command; it does not provide a fresh tip for every destination or source. When independent samples require fresh tips, use suitable transfer() calls or explicit building blocks and inspect the expanded simulation log. Liquid-class commands have their own documented tip policies. See the complex-command parameter reference and references/liquid_handling.md.

5. Add setup information and runtime controls

Use define_liquid() and labware-level load_liquid() or load_liquid_by_well() to improve setup visualization. Do not use deprecated Well.load_liquid() in new API 2.22+ protocols.

Define operator-controlled values in add_parameters() and read them from protocol.params. Validate ranges and use defaults that produce a safe, meaningful simulation. CSV parameters have no default and only one CSV parameter can be selected per run.

6. Budget resources

Before simulation, calculate:

• Tips or tip sets required under every branch.
• Source volume = delivered volume + mixing loss + disposal volume + dead

volume + a justified reserve.

• Maximum destination volume after every addition and mix.
• Number of module, adapter, trash, and staging positions.
• Incubation and module timing, including concurrent tasks.

7. Validate in layers

1. Compile: python -m py_compile protocol.py.
2. Simulate with the pinned package.
3. Inspect the run log for command count, tip changes, pauses, and unexpected

locations.

1. Import into the appropriate App and require successful analysis.
2. Check protocol visualization, runtime parameter defaults, deck map, module

setup, and labware offsets.

1. Perform an operator-reviewed dry run before first use.

See references/validation_and_operations.md.

Common Failure Modes

• Using old names such as p300_single_flex; use current flex_* load names.
• Declaring apiLevel in both metadata and requirements.
• Using API 2.29 or later for OT-2.
• Treating a runtime parameter named dry_run as disabling liquid handling;

the bundled parameter only shortens a delay.

• Heating the PCR template before the operator confirms a compatible seal.
• Forgetting a Flex trash bin or waste chute.
• Loading a Magnetic Module on Flex; use supported Flex magnetic hardware.
• Calling read(wavelengths=...) on the plate reader; call initialize() first,

then read().

• Using deprecated Well.load_liquid() instead of labware-level methods.
• Assuming simulation verifies calibration, liquid height, or physical

clearances.

• Passing an unsafe well to a partial-nozzle pipette, which can place tips

outside labware and cause a crash.

• Using new_tip="once" across samples with incompatible contamination

requirements.

Bundled Templates