benchling-integration

Benchling インテグレーション

概要

Benchling は、ライフサイエンスの研究開発向けクラウドプラットフォームです。Python SDK と REST API を使って、レジストリエンティティ（DNA、RNA、タンパク質）、インベントリ、電子実験ノート、ワークフローにプログラムからアクセスできます。

バージョンに関する注意: 例は benchling-sdk 1.25.0（PyPI の最新安定版）を対象としています。ドキュメント：benchling.com/sdk-docs。プラットフォームガイド：docs.benchling.com。

このスキルを使用する場面

次のような場合に、このスキルを使用してください。

• Benchling の Python SDK または REST API を使用する
• 生物学的配列（DNA、RNA、タンパク質）とレジストリエンティティを管理する
• インベントリ操作（サンプル、コンテナ、場所、移送）を自動化する
• 電子実験ノートのエントリーを作成または検索する
• ワークフローの自動化や Benchling Apps を構築する
• Benchling と外部システムの間でデータを同期する
• 分析のために Benchling Data Warehouse にクエリを実行する
• AWS EventBridge を使ったイベント駆動型インテグレーションを設定する

主な機能

コード例を含む 7 つの機能分野については、 references/core_capabilities.md を参照してください。

1. 認証とセットアップ — API キーと OAuth アプリによる認証。references/authentication.md を参照してください。
2. レジストリとエンティティの管理 — DNA および AA 配列、カスタムエンティティ、スキーマ、登録。
3. インベントリ管理 — コンテナ、ボックス、プレート、場所、移送。
4. ノートブックとドキュメント — エントリー、日々のメモ、構造化テーブル。
5. ワークフローと自動化 — タスク、フローチャート、アッセイの実行。
6. イベントとインテグレーション — EventBridge サブスクリプション。references/eventbridge.md を参照してください。
7. データウェアハウスと分析 — ウェアハウスへの SQL アクセス。

エンドポイントと SDK の詳細については、 references/api_endpoints.md と references/sdk_reference.md を参照してください。

ベストプラクティス

エラー処理

SDK は失敗したリクエストを自動的に再試行します。

# Automatic retry for 429, 502, 503, 504 status codes
# Up to 5 retries with exponential backoff
# Customize retry behavior if needed
from benchling_sdk.retry import RetryStrategy

benchling = Benchling(
    url=tenant_url,
    auth_method=ApiKeyAuth(api_key),
    retry_strategy=RetryStrategy(max_retries=3),
)

効率的なページネーション

メモリ効率のよいページネーションにはジェネレーターを使用してください。

# Generator-based iteration
for page in benchling.dna_sequences.list():
    for sequence in page:
        process(sequence)

# Check estimated count without loading all pages
total = benchling.dna_sequences.list().estimated_count()

スキーマフィールドヘルパー

カスタムスキーマフィールドには fields() ヘルパーを使用してください。

# Convert dict to Fields object
custom_fields = benchling.models.fields({
    "concentration": "100 ng/μL",
    "date_prepared": "2025-10-20",
    "notes": "High quality prep"
})

前方互換性

SDK は未知の列挙値や型を適切に処理します。

• 未知の列挙値は保持されます
• 認識されないポリモーフィック型は UnknownType を返します
• 新しい API バージョンでも作業できます

セキュリティ上の考慮事項

• API キーや OAuth シークレットをバージョン管理にコミットしないでください
• 名前付きの環境変数（BENCHLING_TENANT_URL、BENCHLING_API_KEY など）のみを読み取ってください
• ネットワーク呼び出しはテナント URL のみにルーティングしてください
• キーが侵害された場合はローテーションしてください。複数ユーザー向けの本番アプリでは OAuth を使用してください
• Developer Console でアプリに必要最小限の権限を付与してください

リソース

references/

詳細な情報を確認するためのリファレンスドキュメントです。

• authentication.md - OIDC、セキュリティのベストプラクティス、認証情報の管理を含む包括的な認証ガイド
• sdk_reference.md - 高度なパターン、例、すべてのエンティティ型を含む Python SDK の詳細リファレンス
• api_endpoints.md - SDK を使わずに直接 HTTP 呼び出しを行うための REST API エンドポイントリファレンス
• eventbridge.md - EventBridge のセットアップ、イベントペイロードスキーマ、ルールの例、Lambda ハンドラー、検証、復旧

必要に応じて、具体的なインテグレーション要件に合わせてこれらのリファレンスを読み込んでください。

よくあるユースケース

1. エンティティの一括インポート:

# Import multiple sequences from FASTA file
from Bio import SeqIO

for record in SeqIO.parse("sequences.fasta", "fasta"):
    benchling.dna_sequences.create(
        DnaSequenceCreate(
            name=record.id,
            bases=str(record.seq),
            is_circular=False,
            folder_id="fld_abc123"
        )
    )

2. インベントリ監査:

# List all containers in a specific location
containers = benchling.containers.list(
    parent_storage_id="box_abc123"
)

for page in containers:
    for container in page:
        print(f"{container.name}: {container.barcode}")

3. ワークフローの自動化:

# Update all pending tasks for a workflow
tasks = benchling.workflow_tasks.list(
    workflow_id="wf_abc123",
    status="pending"
)

for page in tasks:
    for task in page:
        # Perform automated checks
        if auto_validate(task):
            benchling.workflow_tasks.update(
                task_id=task.id,
                workflow_task=WorkflowTaskUpdate(
                    status_id="status_complete"
                )
            )

4. データのエクスポート:

# Export all sequences with specific properties
sequences = benchling.dna_sequences.list()
export_data = []

for page in sequences:
    for seq in page:
        if seq.schema_id == "target_schema_id":
            export_data.append({
                "id": seq.id,
                "name": seq.name,
                "bases": seq.bases,
                "length": len(seq.bases)
            })

# Save to CSV or database
import csv
with open("sequences.csv", "w") as f:
    writer = csv.DictWriter(f, fieldnames=export_data[0].keys())
    writer.writeheader()
    writer.writerows(export_data)

追加リソース

• 公式ドキュメント: https://docs.benchling.com
• Python SDK リファレンス: https://benchling.com/sdk-docs/
• API リファレンス: https://benchling.com/api/reference
• サポート: [email protected]

エージェントの操作手順

1. 環境を確認します。 機器またはプラットフォームのモデル、API バージョン、認証情報、シミュレーターが利用可能かどうかを確認します。
2. 入力内容を明確にします。 データまたはユーザーから、形式、識別子、パラメーターを確認します。結果を左右する値は推測せず、質問してください。
3. まず小規模なバージョンを実行します。 実際のサンプルを使う前に、プロトコルをシミュレーションするか、水またはダミーのラボウェアを使って実行します。
4. 上記の手順と参考資料を使って、タスク全体を実行します。
5. 結果を検証します。 容量、デッキレイアウト、ラボウェアの定義を確認し、実行前に人間の承認を得てください。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未解決の点を明記します。

発生した場合	対応
プロトコルがシミュレーションで失敗する	シミュレーション上で修正してください。検証されていないプロトコルをハードウェアで実行してはいけません。
これらの手順に記載されている関数、フラグ、エンドポイントがインストール済みのバージョンに存在しない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認し、調整してユーザーに伝えてください。API をでっち上げてはいけません。
必須の入力、識別子、パラメーターが曖昧である	ユーザーに質問するか、実行前に仮定を明示してください。

誠実性に関する規則

• 結果、パラメーター、識別子、引用、統計を捏造してはいけません。実行または検証できないことは、明確に伝えてください。
• ユーザーから明示的な確認を得ずに、物理的な操作、注文、請求を実行してはいけません。
• ここに記載されているバージョン固有の詳細は古くなっている可能性があります。インストール済みバージョンの公式ドキュメントで確認してください。
• 費用がかかる操作、共有 GPU やクラウドのクォータを消費する操作、個人データや患者データを扱う操作、または取り消せない操作を行う前に、ユーザーに確認してください。

関連スキル

• labarchive-integration：公式の LabArchives ELN REST-like API および Inventory API v1 と安全に連携します。
• latchbio-integration：Python SDK、CLI、Latch Data and Registry、Nextflow、Snakema…を使って、Latch 上でバイオインフォマティクスのワークフローを構築、登録、デバッグ、運用します。