adaptyv

Adaptyv Bio Foundry API

Adaptyv Bio 是一家云实验室，可将蛋白质序列转化为实验数据。用户通过 API 或 UI 提交氨基酸序列；Adaptyv 的自动化实验室会运行检测（结合、热稳定性、表达、荧光），并在约 21 天内交付结果。

官方文档： docs.adaptyvbio.com/api-reference · llms.txt 索引 · OpenAPI 规范

快速入门

基础 URL： https://foundry-api-public.adaptyvbio.com/api/v1

身份验证： 在 Authorization 标头中使用 Bearer 令牌。令牌可从 foundry.adaptyvbio.com 侧边栏获取。

编写代码时，始终从环境变量 ADAPTYV_API_KEY 或 .env 文件读取 API 密钥，绝不要将令牌硬编码。首先检查项目根目录中是否有 .env 文件；如果有，请使用 python-dotenv 等库加载。

官方 API 文档 在 curl 示例中使用 FOUNDRY_API_TOKEN；它与 Bearer 令牌相同。为与 SDK 保持一致，在 Python 和新编写的 shell 脚本中优先使用 ADAPTYV_API_KEY。

export ADAPTYV_API_KEY="abs0_..."
curl https://foundry-api-public.adaptyvbio.com/api/v1/targets?limit=3 \
  -H "Authorization: Bearer $ADAPTYV_API_KEY"

除 GET /openapi.json 外，每个请求都需要身份验证。请将令牌存储在环境变量或 .env 文件中，绝不要将其提交到源代码管理系统。

Python SDK

版本说明： adaptyv-sdk 0.1.0（Beta）尚未发布到 PyPI，请从 GitHub 安装：

uv pip install "git+https://github.com/adaptyvbio/adaptyv-sdk.git"

在包含 pyproject.toml 的项目中：

uv add "adaptyv-sdk @ git+https://github.com/adaptyvbio/adaptyv-sdk.git"

环境变量（在 shell 或 .env 文件中设置）：

ADAPTYV_API_KEY=your_api_key
ADAPTYV_API_URL=https://foundry-api-public.adaptyvbio.com/api/v1
ADAPTYV_ORGANIZATION_ID=your_org_id  # optional

如果未显式传入，@lab.experiment 装饰器和 FoundryClient 都会从环境中读取 ADAPTYV_API_KEY 和 ADAPTYV_API_URL。

装饰器模式

from adaptyv import lab

@lab.experiment(target="PD-L1", experiment_type="screening", method="bli")
def design_binders():
    return {"design_a": "MVKVGVNG...", "design_b": "MKVLVAG..."}

result = design_binders()
print(f"Experiment: {result.experiment_url}")

客户端模式

import os
from adaptyv import FoundryClient

client = FoundryClient(
    api_key=os.environ["ADAPTYV_API_KEY"],
    base_url=os.environ.get(
        "ADAPTYV_API_URL",
        "https://foundry-api-public.adaptyvbio.com/api/v1",
    ),
)

# Browse targets
targets = client.targets.list(search="EGFR", selfservice_only=True)

# Estimate cost
estimate = client.experiments.cost_estimate({
    "experiment_spec": {
        "experiment_type": "screening",
        "method": "bli",
        "target_id": "target-uuid",
        "sequences": {"seq1": "EVQLVESGGGLVQ..."},
        "n_replicates": 3
    }
})

# Create and submit
exp = client.experiments.create({...})
client.experiments.submit(exp.experiment_id)

# Later: retrieve results
results = client.experiments.get_results(exp.experiment_id)

实验类型

类型	方法	测量内容	是否需要靶标
affinity	bli 或 spr	KD、kon、koff 动力学	是
screening	bli 或 spr	是否结合	是
thermostability	—	熔解温度（Tm）	否
expression	—	表达产量	否
fluorescence	—	荧光强度	否

实验生命周期

Draft → WaitingForConfirmation → QuoteSent → WaitingForMaterials → InQueue → InProduction → DataAnalysis → InReview → Done

状态	执行方	说明
Draft	你	可编辑，不产生费用承诺
WaitingForConfirmation	Adaptyv	审核中，正在准备报价
QuoteSent	你	审核并确认报价
WaitingForMaterials	Adaptyv	已订购基因片段和靶标
InQueue	Adaptyv	材料已到，等待进入实验室
InProduction	Adaptyv	检测正在运行
DataAnalysis	Adaptyv	正在处理原始数据并进行质控
InReview	Adaptyv	最终验证中
Done	你	结果已就绪
Canceled	任一方	实验已取消

实验的 results_status 字段用于跟踪结果状态：none、partial 或 all。

常见工作流

1. 提交结合筛选（分步操作）

# 1. Find a target
targets = client.targets.list(search="EGFR", selfservice_only=True)
target_id = targets.items[0].id

# 2. Preview cost
estimate = client.experiments.cost_estimate({
    "experiment_spec": {
        "experiment_type": "screening",
        "method": "bli",
        "target_id": target_id,
        "sequences": {"seq1": "EVQLVESGGGLVQ...", "seq2": "MKVLVAG..."},
        "n_replicates": 3
    }
})

# 3. Create experiment (starts as Draft)
exp = client.experiments.create({
    "name": "EGFR binder screen batch 1",
    "experiment_spec": {
        "experiment_type": "screening",
        "method": "bli",
        "target_id": target_id,
        "sequences": {"seq1": "EVQLVESGGGLVQ...", "seq2": "MKVLVAG..."},
        "n_replicates": 3
    }
})

# 4. Submit for review
client.experiments.submit(exp.experiment_id)

# 5. Poll or use webhooks until Done
# 6. Retrieve results
results = client.experiments.get_results(exp.experiment_id)

2. 自动化流程（跳过草稿并自动接受报价）

exp = client.experiments.create({
    "name": "Auto pipeline run",
    "experiment_spec": {...},
    "skip_draft": True,
    "auto_accept_quote": True,
    "webhook_url": "https://my-server.com/webhook"
})
# Webhook fires on each status transition; poll or wait for Done

3. 使用 Webhook

创建实验时传入 webhook_url。每次状态转换时，Adaptyv 都会向该 URL 发送 POST 请求，包含实验 ID、先前状态和新状态。

序列

• 简单格式：{"seq1": "EVQLVESGGGLVQPGGSLRLSCAAS"}
• 丰富格式：{"seq1": {"aa_string": "EVQLVESGGGLVQ...", "control": false, "metadata": {"type": "scfv"}}}
• 多链：使用冒号分隔符 — "MVLS:EVQL"
• 有效氨基酸：A、C、D、E、F、G、H、I、K、L、M、N、P、Q、R、S、T、V、W、Y（不区分大小写，存储时统一为大写）
• 只能向状态为 Draft 的实验添加序列

过滤、排序和分页

所有列表端点都支持分页（limit 为 1-100，默认值为 50；offset）、搜索（对名称字段进行自由文本搜索）和排序。

过滤通过 filter 查询参数使用 s 表达式语法：

• 比较：eq(field,value)、neq、gt、gte、lt、lte、contains(field,substring)
• 范围/集合：between(field,lo,hi)、in(field,v1,v2,...)
• 逻辑：and(expr1,expr2,...)、or(...)、not(expr)
• 空值：is_null(field)、is_not_null(field)
• JSONB：at(field,key)——例如，eq(at(metadata,score),42)
• 类型转换：float()、int()、text()、timestamp()、date()

排序使用 asc(field) 或 desc(field)，多个字段以逗号分隔（最多 8 个）：

sort=desc(created_at),asc(name)

示例： filter=and(gte(created_at,2026-01-01),eq(status,done))

错误处理

所有错误均返回：

{
  "error": "Human-readable description",
  "request_id": "req_019462a4-b1c2-7def-8901-23456789abcd"
}

request_id 也会出现在 x-request-id 响应标头中——联系支持人员时请提供该值。

令牌管理

令牌使用基于 Biscuit 的密码学衰减机制。你可以通过 POST /tokens/attenuate 创建受限令牌，并将其范围限定到组织、资源类型、操作（读取/创建/更新）和过期时间。撤销令牌（POST /tokens/revoke）会同时撤销该令牌及其所有派生令牌。

详细 API 参考

如需查看全部 32 个端点的请求/响应架构，请阅读 references/api-endpoints.md。

Agent 操作流程

1. 检查环境。 确认工具包版本和输入格式（SMILES、SDF、PDB、CIF），并在计算前对分子进行清理。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。对于任何会影响结果的值，应先询问，不要猜测。
3. 先运行小规模版本。 先处理少量分子或一个目标，并检查输出。
4. 按照上述说明和参考资料执行完整任务。
5. 验证结果。 检查无效结构、单位一致性，以及预测模型的适用域。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及还有哪些不确定之处。

如果出现这种情况	请这样处理
分子解析或清理失败	说明原因并跳过这些分子；绝不能悄悄丢弃或修改结构。
这些说明中提到的函数、标志或端点在已安装版本中不存在	查阅已安装版本自己的文档（help()、--help、官方文档），调整做法并告知用户。绝不能凭空编造 API。
必需的输入、标识符或参数存在歧义	询问用户，或在运行前明确说明所采用的假设。

诚信准则

• 绝不能捏造结果、参数、标识符、引文或统计数据。若无法运行或验证某项内容，应如实说明。
• 计算预测属于假设，并非实验结果；应明确标注。
• 此处与版本相关的细节可能已过时：请对照已安装版本的官方文档进行确认。
• 对于需要付费、会占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，务必先征求同意。

相关技能

• tamarind：通过 REST API 或 MCP 服务，在 Tamarind Bio 平台上访问一系列开源分子设计和结构生物学工具……
• ginkgo-cloud-lab：在 Ginkgo Bioworks Cloud Lab（cloud.ginkgo.bio）上提交和管理方案；这是一个用于在 Reconfig… 上自主执行实验的 Web 界面。
• esm：介绍 EvolutionaryScale/Biohub 的 esm Python SDK：ESM3 生成式蛋白质设计（序列、结构和功能轨道、链式思维……