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 设置事件驱动型集成

核心功能

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 - REST API 端点参考，适用于不使用 SDK 的直接 HTTP 调用
• 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]

Agent 操作规程

1. 检查环境。 确认仪器或平台型号、API 版本、凭据，以及是否有可用的模拟器。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。任何会改变结果的值都应询问，不要猜测。
3. 先运行小规模版本。 在使用真实样本前，先模拟协议，或使用水或模拟实验室器具运行。
4. 根据上述说明和参考资料执行完整任务。
5. 验证结果。 核实体积、平台布局和实验室器具定义；执行前由人工批准协议。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及哪些内容仍不确定。

如果发生这种情况	请这样做
协议在模拟中失败	在模拟中修复；切勿在未验证协议的情况下在硬件上运行。
这些说明中的函数、标志或端点在已安装版本中不存在	查阅已安装版本自身的文档（help()、--help、官方文档），调整做法并告知用户。切勿编造 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明假设。

诚信规则

• 切勿捏造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请直截了当地说明。
• 未经用户明确确认，切勿触发实体操作、下单或收费。
• 请将此处与版本相关的细节视为可能已过时：根据已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，请先询问。

相关技能

• labarchive-integration：通过官方的 LabArchives 类 REST API 和 Inventory API v1 安全集成。
• latchbio-integration：使用 Python SDK、CLI、Latch Data 和 Registry、Nextflow、Snakema… 在 Latch 上构建、注册、调试和运行生物信息学工作流