benchling-integration

用途

Benchling Integration 用于通过编程方式访问 Benchling 云平台。Benchling 是生命科学研发云平台，本技能帮助开发者使用 Benchling Python SDK 和 REST API 访问注册表实体（DNA、RNA、蛋白质）、库存、电子实验记录本（ELN）条目、工作流、Benchling Apps 以及数据仓库查询。

版本说明：示例基于 benchling-sdk 1.25.0（PyPI 最新稳定版）。文档：benchling.com/sdk-docs。平台指南：docs.benchling.com。

适用场景

使用 Benchling Python SDK 或 REST API
管理生物序列（DNA、RNA、蛋白质）与注册表实体
自动化库存操作（样本、容器、位置、转移）
创建或查询电子实验记录本条目
构建工作流自动化或 Benchling Apps
在 Benchling 与外部系统间同步数据
查询 Benchling 数据仓库进行分析
通过 AWS EventBridge 设置事件驱动集成

主要能力

技能包含七个能力领域，每个领域均附代码，位于 references/core_capabilities.md：

认证与设置——API 密钥与 OAuth 应用认证；参见 references/authentication.md。
注册表与实体管理——DNA 与氨基酸序列、自定义实体、schema 与注册。
库存管理——容器、盒子、板、位置与转移。
笔记本与文档——条目、日常笔记与结构化表格。
工作流与自动化——任务、流程图与检测运行。
事件与集成——EventBridge 订阅；参见 references/eventbridge.md。
数据仓库与分析——通过 SQL 访问数据仓库。

端点与 SDK 细节见 references/api_endpoints.md 和 references/sdk_reference.md。

使用方式与最佳实践

错误处理：SDK 会自动重试失败请求，针对 429、502、503、504 状态码最多重试 5 次并采用指数退避，可自定义重试行为：

from benchling_sdk.retry import RetryStrategy

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

分页效率：使用生成器实现内存高效的分页：

for page in benchling.dna_sequences.list():
    for sequence in page:
        process(sequence)

total = benchling.dna_sequences.list().estimated_count()

Schema 字段辅助：使用 fields() 辅助函数处理自定义 schema 字段：

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
在开发者控制台中为应用授予最小必要权限

常见用例

批量实体导入：从 FASTA 文件导入多个序列：

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"
        )
    )

库存审计：列出特定位置的所有容器：

containers = benchling.containers.list(
    parent_storage_id="box_abc123"
)

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

工作流自动化：更新工作流中所有待处理任务：

tasks = benchling.workflow_tasks.list(
    workflow_id="wf_abc123",
    status="pending"
)

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

数据导出：导出具有特定属性的所有序列：

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)
            })

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

资源

references/ 目录包含详细参考文档：

authentication.md——全面认证指南，包括 OIDC、安全最佳实践与凭据管理
sdk_reference.md——详细 Python SDK 参考，含高级模式、示例与所有实体类型
api_endpoints.md——REST API 端点参考，用于不使用 SDK 的直接 HTTP 调用
eventbridge.md——EventBridge 设置、事件负载 schema、规则示例、Lambda 处理器、验证与恢复

官方文档：https://docs.benchling.com Python SDK 参考：https://benchling.com/sdk-docs/ API 参考：https://benchling.com/api/reference

智能体操作流程

检查环境：确认仪器或平台型号、API 版本、凭据以及是否有模拟器可用。
确定输入：从数据或用户处确认格式、标识符与参数。对任何会改变结果的取值应询问而非猜测。
先运行小版本：在使用真实样本前，先模拟协议或用清水/虚拟实验器皿运行。
使用上述说明与参考执行完整任务。
验证结果：核对体积、台面布局与实验器皿定义；协议执行前须经人工批准。
报告：说明运行了什么（版本、命令、参数）、检查了什么、还有哪些不确定。

异常处理：

协议在模拟中失败：在模拟中修复；切勿在硬件上运行未经验证的协议。
说明中的函数、标志或端点在已安装版本中缺失：查阅已安装版本自身的文档（help()、--help、官方文档），调整后告知用户。切勿臆造 API。
必需输入、标识符或参数不明确：询问用户，或在运行前明确说明假设。

完整性规则

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

技能介绍

用途