Scientific Agent Skills 之 Adaptyv 技能：用 Foundry API 打通蛋白实验从序列提交到数据回传的全链路

Scientific Agent Skills 之 Adaptyv 技能用 Foundry API 打通蛋白实验从序列提交到数据回传的全链路【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills本篇基于 Scientific Agent Skills 仓库中的skills/adaptyv技能完整讲解 Adaptyv Bio 云实验室FoundryAPI 的接入方式如何完成认证与 SDK 安装如何用装饰器或FoundryClient提交蛋白结合/热稳定性/表达/荧光实验如何跟踪九段式实验生命周期并拉回动力学与 Tm 数据。读完后你可以让 AI Agent 直接编写可运行的 Foundry 集成代码把提交氨基酸序列 → 自动实验室检测 → 结构化结果回传的约 21 天实验闭环变成几行 Python。技能定位它教 Agent 做什么Adaptyv Bio 是一个云实验室用户通过 API 或 Web 界面提交氨基酸序列其自动化实验室执行结合BLI/SPR、热稳定性、表达与荧光等检测并在约 21 天内回传实验数据原文表述见 skills/adaptyv/SKILL.md 第 13 行。在仓库的 README 中它被归入Protein Engineering Design类别定位为Cloud laboratory platform: Adaptyv (automated protein testing and validation)。该技能的触发条件写在 frontmatter 的description中当用户提到 Adaptyv、Foundry API、蛋白结合实验、蛋白筛选、BLI/SPR 检测、热稳定性检测或代码中 import 了adaptyv、adaptyv_sdk、FoundryClient或引用了foundry-api-public.adaptyvbio.com时Agent 应启用本技能。适用前提来自 frontmattercompatibility字段Python 3.10拥有一个 Adaptyv Foundry 账号以及从 Foundry 门户侧边栏获取的 API key通过uv从 GitHub 安装adaptyv-sdk0.1.0 beta尚未发布到 PyPI。需要说明的是从目录结构看skills/adaptyv/不包含scripts/目录是一个纯文档型参考技能仓库安全扫描报告 docs/security-report.md 也将其标注为documentation-only reference for the Adaptyv Bio Foundry API。它的全部价值在于把 Foundry API 的认证约定、实验生命周期和 32 个端点的请求/响应契约固化成 Agent 可执行的集成知识。认证与 API 基础约定Base URLhttps://foundry-api-public.adaptyvbio.com/api/v1认证方式Authorization请求头携带 Bearer tokentoken 从 Foundry 门户foundry.adaptyvbio.com侧边栏获取。密钥来源写代码时一律从环境变量ADAPTYV_API_KEY或项目根目录的.env文件读取密钥——绝不硬编码 token。技能给出的实操建议是先检查项目根目录是否存在.env文件若存在则用python-dotenv之类的库加载它。变量名约定官方文档的 curl 示例使用FOUNDRY_API_TOKEN它与本技能推荐的ADAPTYV_API_KEY是同一个 Bearer token为了与 SDK 保持一致Python 代码和新写的 shell 脚本应统一采用ADAPTYV_API_KEY。最小可用验证请求除GET /openapi.json外其余所有请求都需要认证export ADAPTYV_API_KEYabs0_... curl https://foundry-api-public.adaptyvbio.com/api/v1/targets?limit3 \ -H Authorization: Bearer $ADAPTYV_API_KEY技能同时强调token 只能存放在环境变量或.env文件中绝不能提交到版本控制系统。GET /openapi.json端点无需认证可用于机器读取完整的 OpenAPI 规范。安装 Python SDK 与环境变量adaptyv-sdk目前是0.1.0 beta未上 PyPI需要从 GitHub 安装uv pip install githttps://github.com/adaptyvbio/adaptyv-sdk.git在带pyproject.toml的项目里则用uv add adaptyv-sdk githttps://github.com/adaptyvbio/adaptyv-sdk.gitSDK 相关环境变量设在 shell 或.env文件中变量必填说明ADAPTYV_API_KEY是Foundry Bearer tokenADAPTYV_API_URL否默认https://foundry-api-public.adaptyvbio.com/api/v1ADAPTYV_ORGANIZATION_ID否组织 IDlab.experiment装饰器与FoundryClient在显式传参之外都会自动从环境中读取ADAPTYV_API_KEY和ADAPTYV_API_URL因此多数场景下显式传参可以省略。供应链与安全提示仓库的安全扫描docs/security-report.md 中 adaptyv 条目评级 MEDIUM指出上述安装命令直接拉取 SDK 仓库 HEAD 的代码未固定 commit、tag 或版本且 0.1.0 未发布到 PyPI缺少注册表级别的原生完整性校验。报告的整改建议是把安装固定到具体 tag 或 commit SHA如githttps://github.com/adaptyvbio/adaptyv-sdk.gitcommit-sha并在从源码仓库安装包前征得用户确认。此外扫描报告还提示下文自动化流水线工作流中的skip_draftauto_accept_quote组合会在无人工审核的情况下直接创建真实发票生产环境使用需格外谨慎。两种编程模式装饰器模式最少的样板代码装饰器负责实验提交返回对象带experiment_url可直接跳转到 Foundry 门户代码见 skills/adaptyv/SKILL.md#L61-L70from adaptyv import lab lab.experiment(targetPD-L1, experiment_typescreening, methodbli) def design_binders(): return {design_a: MVKVGVNG..., design_b: MKVLVAG...} result design_binders() print(fExperiment: {result.experiment_url})适合定义一批序列 → 一次性提交的脚本化场景target、实验类型、方法都收敛在装饰器参数里。客户端模式完整的生命周期控制需要浏览目录、估价、创建、提交、回取结果时使用FoundryClient代码见 skills/adaptyv/SKILL.md#L74-L106import os from adaptyv import FoundryClient client FoundryClient( api_keyos.environ[ADAPTYV_API_KEY], base_urlos.environ.get( ADAPTYV_API_URL, https://foundry-api-public.adaptyvbio.com/api/v1, ), ) # Browse targets targets client.targets.list(searchEGFR, selfservice_onlyTrue) # 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)客户端命名空间与端点分组一一对应client.targets、client.experiments底层映射到参考文档中的 Experiments / Targets 等端点族。实验类型与字段要求五种实验类型及其检测方法继承自 skills/adaptyv/SKILL.md#L110-L116类型方法测量内容需要 Targetaffinitybli或sprKD、kon、koff 动力学是screeningbli或spr结合与否是/否是thermostability—熔解温度Tm否expression—表达量否fluorescence—荧光强度否创建实验的POST /experiments接受name、experiment_spec、skip_draft默认 false、auto_accept_quote默认 false、webhook_url五个字段见 references/api-endpoints.md#L21-L67。experiment_spec内各字段在不同实验类型下的要求如下字段AffinityScreeningThermostabilityFluorescenceExpressionexperiment_type必填必填必填必填必填method必填必填———target_id必填必填———sequences必填必填必填必填必填n_replicates建议默认 3建议默认 3可选可选可选antigen_concentrations可选————值得注意的默认值antigen_concentrations仅用于 affinity 实验缺省为[1000.0, 316.2, 100.0, 31.6, 0.0]nM即约每 3.16 倍10^0.5递减的五浓度梯度加零浓度对照n_replicates为技术重复数最小值 1。实验生命周期九段状态机实验从Draft起步最终到达DoneDraft → WaitingForConfirmation → QuoteSent → WaitingForMaterials → InQueue → InProduction → DataAnalysis → InReview → Done各状态由谁驱动、含义如何继承自 skills/adaptyv/SKILL.md#L124-L137状态行动方说明Draft你可编辑无费用承诺WaitingForConfirmationAdaptyv审核中报价正在生成QuoteSent你审阅并确认报价WaitingForMaterialsAdaptyv基因片段与靶点材料已订购InQueueAdaptyv材料到位进入实验室队列InProductionAdaptyv检测正在运行DataAnalysisAdaptyv原始数据处理与 QCInReviewAdaptyv最终校验Done你结果可用Canceled任一方实验已取消实验中还有一个results_status字段跟踪数据回传进度none、partial或all。当它进入partial/all时GET /results列表里才会出现对应的分析结果。编辑规则与状态强相关Draft实验可以完整编辑PATCH /experiments/{id}报价生成之后只有name、description和webhook_url仍可修改序列也只能追加到Draft状态的实验否则POST /sequences返回 409。三大典型工作流工作流 1提交一个结合筛选分步版这是技能给出的标准路径找靶点 → 预览费用 → 创建 Draft → 提交审核 → 轮询/webhook → 取结果完整代码见 skills/adaptyv/SKILL.md#L141-L177# 1. Find a target targets client.targets.list(searchEGFR, selfservice_onlyTrue) 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自动化流水线跳过 Draft 自动接受报价在创建时传入skip_draft: True直接越过 Draft 进入WaitingForConfirmationauto_accept_quote: True自动接受报价并创建发票再挂webhook_url接收每次状态迁移的 POST 通知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再结合POST /experiments的响应字段看这条链路的含义auto_accept_quote触发发票时会返回stripe_hosted_invoice_url与stripe_invoice_id——也就是说该模式会真实产生 Stripe 发票。对应仓库安全报告的提示建议只在预算与审批机制完备的自动化环境里启用这两个开关。工作流 3Webhook 通知创建实验时传入webhook_urlAdaptyv 会在每一次状态迁移时向该 URL 发 POST载荷包含实验 ID、前一状态与新的状态。配合GET /updates更新流见下文即可实现不依赖轮询的事件驱动集成。报价、发票与费用估算费用相关端点是先估价、再确认、后开票的结构详见 references/api-endpoints.mdPOST /experiments/cost-estimate不创建实验即算价。返回pricing_version如v1_2026-01-20说明价格按版本管理、assay按类型的 base 重复数计价、materials结合实验的靶点材料成本、total_cents美元美分。所有价格不含 VAT税费在开票时计算没有自助定价的靶点会返回不完整的估算。GET /experiments/{id}/quote报价元数据含amount_total/amount_subtotal最小货币单位、currencyISO 代码如usd、status、expires_at另有/quote/pdf返回application/pdf报价单。POST /experiments/{id}/quote/confirm或POST /quotes/{quote_id}/confirm接受报价、创建草稿发票实验推进到WaitingForMaterials请求体可带purchase_order_number响应含hosted_invoice_url与invoice_id。POST /quotes/{quote_id}/reject取消报价关联实验回退到Draft请求体必填reason可附feedback。GET /experiments/{id}/invoice与GET /quotes/GET /quotes/{quote_id}发票元数据含托管支付 URL与组织级报价列表/明细含line_items逐项价格、subtotal_cents、tax_cents、total_cents。这套设计对应生命周期表里QuoteSent由你行动的语义报价确认是一个显式的人工决策点除非你显式开启auto_accept_quote。序列格式规则与批量追加sequences字段支持两种写法继承自 skills/adaptyv/SKILL.md#L196-L202简单格式{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状态的实验创建后批量追加走POST /sequencesreferences/api-endpoints.md#L327-L356请求体为experiment_code人类可读实验码如PROJ-001注意这里用 code 而非 UUID加sequences数组每条含aa_string必填、name、control、metadata201 响应返回added_count、experiment_id、experiment_code、sequence_ids实验不在 Draft 时返回 409。查询侧GET /sequences返回全实验序列按创建倒序列表项只含前 50 字符的aa_preview与lengthGET /sequences/{id}才返回完整aa_string、is_control与metadata。靶点目录从目录选靶到自定义靶点GET /targets列出可用于实验的已验证抗原查询参数比通用分页参数多出三个领域参数见 references/api-endpoints.md#L401-L429参数类型说明limitint最大条数1–100默认 50offsetint跳过条数searchstring产品名自由文本搜索sortstring排序表达式selfservice_onlyboolean仅返回有自助定价的靶点估价前提show_conjugatedboolean是否包含缀合靶点默认仅未缀合detailedboolean在details块中填充富化数据基因名、结构、序列、生物活性列表项关键字段idUUID直接用作experiment_spec.target_id、name、vendor_name、catalog_number供应商目录号、url、pricingnull 表示需要定制报价、details。GET /targets/{target_id}返回单个靶点目录记录。目录里没有想要的靶点时走POST /targets/request-custom提交自定义靶点供人工审核必填name与组织内唯一的product_idsequence与pdb_id至少提供其一可选pdb_file、molecular_weightkDa、note随后用GET /targets/request-custom列表可filtereq(status,pending_review)和GET /targets/request-custom/{request_id}跟踪状态批准后会关联出material_id。结果回传结果端点与字段结构GET /results列出已完成的分析结果按新到旧排序GET /experiments/{id}/results取单个实验的结果两者都支持limit、offset、filter、sort结果端点或search序列端点。结果列表项字段字段类型说明iduuid结果标识titlestring人类可读标题experiment_iduuid关联实验result_typestring如affinity、thermostabilitysummaryarray关键结果按类型不同见下metadataobject扩展元数据如仪器信息data_package_urlstring/null原始数据包下载 URLcreated_atdatetime结果生成时间summary的类型相关结构是解读数据的关键AffinityResult含kd_mean、kd_std、kon_mean、kon_log_std、koff_mean、koff_std、replicates数组每个重复带kd、kon、koff、binding_strength、kon_method、koff_method、replicate索引、sequence、target_idThermostabilityResult含 Tm 值与熔解曲线。GET /results/{result_id}返回包含完整summary数组的详情。过滤、排序与分页s-expression 查询语法所有列表端点统一支持分页limit1–100默认 50offset、对 name 字段的自由文本search以及sort排序。过滤通过filter查询参数使用 s-expression 语法完整清单继承自 skills/adaptyv/SKILL.md#L204-L221比较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)JSONBat(field,key)例如eq(at(metadata,score),42)类型转换float()、int()、text()、timestamp()、date()排序用asc(field)或desc(field)逗号分隔最多 8 个键sortdesc(created_at),asc(name)组合示例——筛选 2026 年以来完成且状态为 done 的实验filterand(gte(created_at,2026-01-01),eq(status,done))这套语法在 updates 流上同样有用例如filtereq(type,status_change)、filterin(experiment_id,uuid1,uuid2)。更新流Updates轮询之外的第二通道GET /updates返回实验更新流最新在前每条含id、experiment_id、experiment_code、name更新描述、timestampGET /experiments/{id}/updates返回单实验的更新最旧在前。更新类型有三种status_change、progress、error。webhook 负责实时推送updates 流则提供可过滤、可分页的历史审计轨迹二者是互补的关系。错误处理与反馈回路所有错误响应统一为两字段结构{ error: Human-readable description, request_id: req_019462a4-b1c2-7def-8901-23456789abcd }request_id同时出现在x-request-id响应头中联系支持时应附上它。这个 ID 还有第二个用途POST /feedback/submit端点接收 bug 报告/功能请求/一般反馈请求体必填request_uuid即出问题那次的请求 UUID与feedback_typefeature_request、feedback或bug_reportjson_body结构化错误细节与human_note自由描述至少提供其一201 响应返回reference与message。这意味着错误上下文可以程序化地回流给供应商而不是只停留在日志里。令牌管理基于 Biscuit 的密码学衰减Foundry 的 token 采用 Biscuit 密码学衰减机制支持为不同执行主体发放权限收窄的子 token端点见 references/api-endpoints.md#L586-L643GET /tokens列出调用者拥有的全部 tokenroot 与 attenuated字段含kindroot/attenuated、expires_atnull 表示永不过期、revoked_at、parent_token_id、root_token_id、attenuation_spec。POST /tokens/attenuate为现有 token 创建受限版本。请求体含token格式为abs0_{slug}{biscuit_base64}、attenuation限制规格、name可选attenuated_parent_token_id支持链式衰减限制类型覆盖组织、资源experiments/results、动作read/create/update、过期时间。201 响应返回新数据库 ID 与新的衰减 token 字符串。POST /tokens/revoke撤销调用 token 的 root 及其全部衰减后代幂等响应含token_id、revoked_at、children_revoked。对 Agent 集成的实际意义可以按任务粒度发放只读 仅 experiments 资源 72 小时过期的 token让自动化流水线持有的凭证泄露面最小化而不是全程使用 root token。端点总览与延伸阅读按资源分组的 32 个端点可归纳为八族完整请求/响应字段表见 skills/adaptyv/references/api-endpoints.md资源族主要端点ExperimentsPOST /experiments、GET /experiments、GET/PATCH /experiments/{id}、POST .../submit、POST /experiments/cost-estimate、GET .../quote、GET .../quote/pdf、POST .../quote/confirm、GET .../invoice、GET .../results、GET .../sequences、GET .../updatesSequencesGET /sequences、GET /sequences/{id}、POST /sequencesResultsGET /results、GET /results/{id}TargetsGET /targets、GET /targets/{id}、POST /targets/request-custom、GET /targets/request-custom、GET /targets/request-custom/{id}QuotesGET /quotes、GET /quotes/{id}、POST /quotes/{id}/confirm、POST /quotes/{id}/rejectTokensGET /tokens、POST /tokens/attenuate、POST /tokens/revokeUpdatesGET /updatesFeedbackPOST /feedback/submit技能主文档与端点参考的相对位置关系入口是 skills/adaptyv/SKILL.mdfrontmatterversion: 1.2作者 K-Dense Inc.端点全集在 skills/adaptyv/references/api-endpoints.md该技能在仓库技能目录中的条目见 docs/skills.md。在 Agent 侧只需让宿主Cursor、Claude Code、Codex 等 Agent Skills 标准宿主按 README 的Getting Started安装本技能集合当提示词涉及 Adaptyv 或代码出现FoundryClient时上述认证约定、生命周期状态机与端点契约即会被自动带入上下文直接产出可运行的集成代码。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考