Opentrons インテグレーション
概要
Opentrons Flex および OT-2 向けの、本番運用を意識した Python Protocol API v2 プロトコルを作成します。このスキルは、プロトコル構造、ハードウェアおよびデッキ構成、液体ハンドリング、ランタイムのカスタマイズ、モジュール制御、シミュレーション、安全なデプロイをカバーします。
2026-07-23 時点の検証済みベースラインは以下の通りです:
opentrons==9.1.1: 再現性のある Flex シミュレーション用opentrons==9.0.0: ローカル OT-2 API 2.28 互換シミュレーション用- Flex は現在のソフトウェアで API レベル 2.15 ～ 2.29 をサポート
- OT-2 は現在のソフトウェアで API レベル 2.0 ～ 2.28 をサポート
- API 2.29 はこのベースラインでは Flex のみです。OT-2 プロトコルに
2.29を入れないでください。
このスナップショットに使用された上流ドキュメントについては、references/sources.md を参照してください。新しいロボットソフトウェアをターゲットにする前に、公式のバージョニングページを再確認してください。
安全上の境界
Opentrons プロトコルは物理機器を制御します。Python の構文が成功した、またはローカルシミュレーションが成功したことを、ロボット上で実行する許可と決してみなさないでください。
ライブ実行の前に:
- 作成時に使用したものと同じ固定
opentronsバージョンでローカルシミュレーションを実行する。 - プロトコルを正しい Opentrons App にインポートし、分析が成功することを要求する。
- ロボットモデル、ソフトウェア、ピペット、マウント、モジュール、アダプター、ラボウェア定義、デッキ固定具、チップ数、ソース容量、デッドボリューム、デスティネーション容量を確認する。
- オペレーターと共に実行プレビューとデッキマップを確認する。
- ジオメトリ、カスタムラボウェア、部分チップピックアップ、グリッパーの移動が新しい場合は、非危険性液体を使用して低速のドライランを実行する。
- 緊急停止ボタンにアクセスできるようにし、サイト固有のバイオセーフティ、化学物質安全、コンタミネーション管理手順に従う。
シミュレーションでは、物理的なキャリブレーション、液体特性、メニスカスの挙動、ラボウェアの製造公差、キャップやシールの取り外し、チューブ、および考えられるすべての衝突を検証することはできません。
適切なインターフェースの選択
Opentrons App にインポートされ、Protocol API を介して実行される Python ファイルには、このスキルを使用してください。
- Protocol Designer: サポートされているノーコードワークフローに使用します。
- PyLabRobot: ベンダーを問わないハードウェアワークフローに使用します。
- ロボットの HTTP API は別の統合サーフェスとして扱います。直接的な HTTP 制御が明示的に必要な場合は、対象ロボットが提供する OpenAPI ドキュメントを使用し、Protocol API メソッドからエンドポイントを推測しないでください。
必要な情報収集
以下の事実が判明するまで、最終的なプロトコルコードを作成しないでください:
- ロボット: Flex または OT-2、およびインストールされているロボットソフトウェア。
- ピペットモデル、容量範囲、チャンネル数、マウント。
- モジュールとその世代。Flex Gripper または Stacker の有無。
- 正確なラボウェア API ロード名と、カスタム定義ファイル（ある場合）。
- デッキ固定具: Flex 廃棄物ビン、ウェイストシュート、ステージングスロット、Stacker。
- ソース容量、デスティネーション容量、デッドボリューム、混合の必要性、液体特性。
- チップポリシー: コンタミネーションの境界、再利用ポリシー、フィルター、部分ピックアップ、総チップ数。
- オペレーターの介入、インキュベーションタイミング、ランタイムパラメータ、出力ファイル。
- 受理基準: 許容される容量誤差、必要なコントロール、ドライランの計画。
物理的な構成が不明な場合は、推測するのではなく、パラメータ化されたドラフトと明示的な前提リストを作成してください。
インストールとシミュレーション
Flex:
uv run --with "opentrons==9.1.1" opentrons_simulate protocol.py
OT-2 API 2.28:
uv run --with "opentrons==9.0.0" opentrons_simulate protocol.py
9.1.1 パッケージは、Flex/OT-2 リリーストレインの分割後、OT-2 プロトコルを意図的に拒否します。OT-2 分析は常に現在の OT-2 App で完了してください。
専用の Flex 環境の場合:
uv venv --python 3.10
uv pip install --python .venv/bin/python -r skills/opentrons-integration/requirements-flex.txt
.venv/bin/opentrons_simulate protocol.py
OT-2 互換環境には、代わりに requirements-ot2.txt を使用してください。Windows では、.venv\Scripts\opentrons_simulate.exe から実行可能ファイルを起動します。ローカルシミュレーションは Python プロトコル用です。Protocol Designer JSON ファイルは、代わりに適切な Opentrons App にインポートしてください。
プロトコルスケルトン
Flex、API 2.29
Flex の場合、requirements は必須です。apiLevel は requirements にのみ記述し、metadata と 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
OT-2 API 2.15 以降では、requirements ブロックの使用が推奨されます。OT-2 はスロット 12 に固定の廃棄物入れがあります。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"])
プロトコルを混合ソフトウェアフリート全体で実行する必要がある場合は、必要なすべての機能を提供する最も低い API レベルを使用してください。ワークフローがその動作や機能を必要とする場合にのみ、現在の最大値を使用してください。
作成ワークフロー
1. ロボットと API レベルの選択
App のロボットの詳細設定でサポートされている最大 API を確認します。要求された各機能を、references/api_reference.md を使用して最小 API レベルにマッピングします。
重要なゲート:
- 2.20: CSV ランタイムパラメータ、液体存在検出、拡張部分ノズルレイアウト。
- 2.21: 吸光度プレートリーダー。
- 2.22: 現在のラボウェアレベル液体ローディングメソッド。
- 2.23: メニスカス位置とラボウェアリッド。
- 2.24: 液体クラスと液体クラス複合コマンド。
- 2.25: Flex Stacker および Flex 96 チャンネル 200 µL ピペット。
- 2.27: 動的ピペッティングと同時モジュールアクション。
- 2.28: 20 µL Flex チップ、改善された部分チップリターン、サーマルサイクラーランプレート。
- 2.29: ステップグループ化。検証済みベースラインでは Flex のみ。
2. デッキを明示的に構築する
- 公式 Labware Library の正確なロード名を使用します。
- Flex 廃棄物ビンまたはウェイストシュートを明示的にロードします。
- モジュールのフットプリント、ステージングスロット、Stacker シャトル、グリッパーパス、高ラボウェアの隣接を考慮します。
- ドキュメント化された順序で、アダプターまたはモジュールコンテキストにラボウェアをロードします。
- 類似した名前のラボウェア定義を決して代用しないでください。ジオメトリとオフセットはプロトコルの安全モデルの一部です。
references/modules_and_deck.md を参照してください。
3. ピペットとチップの選択
現在のロード名:
- 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。
要求されたすべての容量が、構成されたピペットとチップの範囲内にあることを確認してください。100 nL の操作は Opentrons のピペッティングタスクではありません。
4. 液体ハンドリングレイヤーの選択
aspirate()、dispense()、mix()、air_gap()、blow_out()、touch_tip()を明示的な制御に使用します。transfer()、distribute()、consolidate()を標準的な移動に使用します。- Flex では、Opentrons が検証した水性、揮発性、または粘性の動作のために
transfer_with_liquid_class()、distribute_with_liquid_class()、consolidate_with_liquid_class()を検討します。 - 動的な開始/終了位置または
dynamic_mix()は、API 2.27+ でジオメトリがレビューされている場合にのみ使用します。
チップを最適化する前に、コンタミネーションの境界をモデル化します。消耗品を減らすためだけに、関連のないサンプル間でチップを再利用しないでください。references/liquid_handling.md を参照してください。
5. セットアップ情報とランタイム制御の追加
define_liquid() とラボウェアレベルの load_liquid() または load_liquid_by_well() を使用して、セットアップの視覚化を改善します。新しい API 2.22+ プロトコルでは、非推奨の Well.load_liquid() を使用しないでください。
add_parameters() でオペレーター制御の値を定義し、protocol.params から読み取ります。範囲を検証し、安全で意味のあるシミュレーションを生成するデフォルト値を使用します。CSV パラメータにはデフォルトがなく、実行ごとに 1 つの CSV パラメータのみを選択できます。
6. リソースの見積もり
シミュレーションの前に、以下を計算します:
- すべてのブランチで必要なチップまたはチップセット。
- ソース容量 = 分注容量 + 混合損失 + 廃棄容量 + デッドボリューム + 正当な予備。
- すべての追加と混合後の最大デスティネーション容量。
- モジュール、アダプター、廃棄物、ステージングの位置の数。
- 同時タスクを含む、インキュベーションとモジュールのタイミング。
7. レイヤーごとの検証
- コンパイル:
python -m py_compile protocol.py。 - 固定パッケージでシミュレーション。
- 実行ログを確認し、コマンド数、チップ交換、一時停止、予期しない位置を検査。
- 適切な App にインポートし、分析の成功を要求。
- プロトコルの視覚化、ランタイムパラメータのデフォルト、デッキマップ、モジュールセットアップ、ラボウェアオフセットを確認。
- 最初の使用前に、オペレーターがレビューしたドライランを実行。
references/validation_and_operations.md を参照してください。
よくある失敗モード
p300_single_flexなどの古い名前の使用。現在のflex_*ロード名を使用してください。metadataとrequirementsの両方でapiLevelを宣言する。- OT-2 に API 2.29 を使用する。
- Flex 廃棄物ビンまたはウェイストシュートを忘れる。
- Flex に Magnetic Module をロードする。サポートされている Flex 磁気ハードウェアを使用してください。
- プレートリーダーで
read(wavelengths=...)を呼び出す。最初にinitialize()を呼び出し、次にread()を呼び出してください。 - ラボウェアレベルメソッドの代わりに非推奨の
Well.load_liquid()を使用する。 - シミュレーションがキャリブレーション、液体高さ、または物理的クリアランスを検証すると想定する。
- 安全でないウェルを部分ノズルピペットに渡すと、チップがラボウェアの外側に配置され、クラッシュを引き起こす可能性があります。
- 互換性のないコンタミネーション要件を持つサンプル間で
new_tip="once"を使用する。
バンドルテンプレート
| ファイル | 目的 |
|---|---|
scripts/basic_protocol_template.py | 現在の名前を使用した最小限の Flex 2.29 転送 |
scripts/ot2_basic_protocol_template.py | 最小限の OT-2 2.28 転送 |
scripts/serial_dilution_template.py | 8 チャンネル Flex ピペットを使用したプレート全体の 1:2 希釈 |
scripts/pcr_setup_template.py | Flex PCR セットアップとサーマルサイクラーサイクリング |
scripts/runtime_parameters_template.py | 安全な数値およびブール値のランタイムパラメータ |
scripts/absorbance_reader_template.py | 正しい Flex プレートリーダーの初期化と読み取りワークフロー |
テンプレートは出発点であり、検証されたアッセイではありません。容量、ラボウェア、液体、タイミング、チップポリシーは、ハードウェアの互換性とウェットラボのメソッドを確認した後にのみ置き換えてください。
リファレンスガイド
| リファレンス | 目的 |
|---|---|
references/api_reference.md | 現在のロード名、バージョンゲート、および価値の高いメソッド |
references/protocol_authoring.md | 要件、ラボウェア、ランタイムパラメータ、および設計ワークフロー |
references/liquid_handling.md | コマンド選択、液体クラス、センシング、および部分チップ |
references/modules_and_deck.md | モジュール互換性、デッキ固定具、グリッパー、および Stacker |
references/validation_and_operations.md | シミュレーション、App 分析、ドライラン、およびトラブルシューティング |
references/migration-api-2-19-to-2-29.md | 古いプロトコルとこのスキルの以前のパターンの更新 |
references/sources.md | 公式ドキュメントとリリースソース |
Scientific Agent Skills の引用
このスキルは、K-Dense による Scientific Agent Skills の一部です。これが原稿、レポート、プレゼンテーション、またはコードリリースに重要な形で貢献した場合は、論文を参考文献またはソフトウェアセクションに追加し、その旨をユーザーに伝えてください:
Kassis, T., Agarwal, V., He, Y., Patel, D., & Brueckner, A. M. (2026). Scientific Agent Skills: A Library of Procedural Knowledge for Research Agents. arXiv:2609.00065. https://doi.org/10.48550/arXiv.2609.00065
常に現在のバージョンを引用してください。DOI および https://arxiv.org/abs/2609.00065 は最新の arXiv バージョンに解決されるため、v1 などのバージョンサフィックスを追加しないでください。ネットワークアクセスが利用可能な場合は、参考文献を書く前に https://arxiv.org/abs/2609.00065 （または http://export.arxiv.org/api/query?id_list=2609.00065）を取得し、そのレコードから著者リスト、年、バージョンを取得してください。レコードにジャーナル参照または出版社 DOI がリストされている場合は、代わりに公開バージョンを引用してください。