langchain-runloop 集成指南Deep Agents 的 Runloop 云沙箱生命周期管理与 Blueprint 引导机制【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents导读本文围绕langchain-runloop这一 Deep Agents 官方合作伙伴集成包展开讲解其版本演进脉络、Runloop 云端 Devbox 沙箱的创建/挂载/销毁全生命周期 API以及 0.0.6 版本引入的 Blueprint 引导bootstrapping机制——一种按名取用、缺失即建的预构建镜像复用方案。读完本文你将掌握如何用三行代码把 Runloop 云沙箱接入 Deep Agents 工作流理解RUNLOOP_SANDBOX_BLUEPRINT_ID与RUNLOOP_SANDBOX_BLUEPRINT_NAME的优先级语义并能复现仓库中的单元测试与集成测试来验证行为。一、版本演进从 CHANGELOG 看功能脉络langchain-runloop的变更历史记录在 libs/partners/runloop/CHANGELOG.md三个已记录版本勾勒出清晰的演进路径版本日期类型关键变更0.0.72026-07-29Bug Fix将依赖收紧为deepagents 0.7.xPR #51490.0.62026-06-03Feature新增 Runloop 沙箱的 Blueprint 引导Blueprint bootstrappingPR #35560.0.52026-05-12Feature对齐 deepagents v0.6 接口值得说明的是0.0.5 之前的版本是在 release-please 自动化发布机制启用前发布的因此没有生成对应的 Changelog 条目CHANGELOG 中明确注明此点。也就是说Blueprint 引导是 0.0.6 之后才可用的能力如果你在使用旧版本请先升级。版本约束在 pyproject.toml 中同样可见——0.0.7 将依赖锁定为deepagents0.7.0,0.8.0配合runloop-api-client保证集成包与核心 SDK 的接口契约一致。包本身支持 Python 3.113.14遵循 MIT 协议。二、快速上手安装与最小可运行示例2.1 安装使用uv一行安装项目本身也通过 uv.lock 管理依赖uv add langchain-runloop2.2 最小调用来自 README 的最小示例展示了完整的创建—执行—清理闭环import os from langchain_runloop import RunloopProvider api_key os.environ[RUNLOOP_API_KEY] provider RunloopProvider(api_keyapi_key) sandbox provider.get_or_create() try: result sandbox.execute(echo hello) print(result.output) finally: provider.delete(sandbox_idsandbox.id)这段代码对应三个核心 API分别对应源码中 provider 与 sandbox 两个模块的职责划分RunloopProvider.get_or_create()创建或挂载一个 Devboxprovider.py 第 143 行起RunloopSandbox.execute()在 Devbox 内执行 shell 命令sandbox.py 第 36 行起RunloopProvider.delete()按 ID 关闭 Devboxprovider.py 第 239 行起。包的公开导出面只有RunloopProvider与RunloopSandbox两个类这一稳定契约由 test_import.py 用__all__断言锁定下游导入不会因内部重构而破坏。三、核心特性Blueprint 引导机制0.0.6Blueprint 是 Runloop 平台上的预构建镜像可以类比 LangSmith 的 snapshot 快照。0.0.6 的核心价值在于让沙箱从预置好依赖环境的 Blueprint 启动而不是每次从空白 Devbox 冷启动从而大幅缩短 Agent 进入工作状态的等待时间。3.1 三种指定方式与优先级从get_or_create()的源码provider.py 第 143-222 行可以梳理出 Blueprint 的完整解析顺序优先级从高到低为环境变量RUNLOOP_SANDBOX_BLUEPRINT_ID直接按 ID 引导create_from_blueprint_id跳过列出/构建流程——因为 ID 是确定性标识无需探测是否存在snapshot关键字参数如snapshotmy-blueprint按名称引导缺失即自动构建create-if-missing环境变量RUNLOOP_SANDBOX_BLUEPRINT_NAME按名称引导同样缺失即建都不存在时退化为创建空白 Devbox保持 0.0.6 之前的旧行为。README 中的两种典型写法# 方式一按名称引导缺失时自动构建 sandbox provider.get_or_create(snapshotmy-blueprint)# 方式二通过环境变量固定引导目标 export RUNLOOP_SANDBOX_BLUEPRINT_NAMEmy-blueprint export RUNLOOP_SANDBOX_BLUEPRINT_IDbp-xxxx # ID 存在时优先且跳过自动构建3.2 create-if-missing 的底层实现缺失即建并非简单调用一个创建接口而是由_ensure_blueprint()provider.py 第 69-120 行实现的三步保障分页探测以name为过滤条件、每页 100 条调用client.blueprints.list()若首页未命中且has_more为真则用starting_afterpage.blueprints[-1].id游标翻页对应测试test_ensure_blueprint_paginates_to_find_ready_match状态判定命中同名 Blueprint 时只有build_complete状态才直接复用状态为queued、provisioning、building时抛错提示仍在构建中请等待或删除重建状态为failed时给出终态错误上次构建失败删除重试或修复 Dockerfile_not_ready_messageprovider.py 第 52-66 行缺失构建确认不存在后调用create_and_await_build_complete(name..., dockerfile...)同步等待构建完成。其中 Dockerfile 默认值为FROM python:3\nprovider.py 第 28 行可通过get_or_create(blueprint_dockerfile...)参数覆盖例如FROM ubuntu:24.04\n。这一默认值行为由test_blueprint_dockerfile_defaults_when_omitted与test_blueprint_dockerfile_forwarded_to_ensure两个测试锁定。3.3 关键设计决策避免重复构建源码中有两处刻意为之的不重复设计值得开发者借鉴同名的非就绪 Blueprint 一律抛错而非二次构建测试test_ensure_blueprint_raises_when_in_flight/test_ensure_blueprint_failed_status_advises_delete防止并发场景下对同一名称发起重复构建造成资源浪费按 ID 引导跳过整个探测流程把确定性标识与按名引导区分对待。四、沙箱后端RunloopSandbox 的协议实现RunloopSandbox继承自 Deep Agents 核心的BaseSandboxdeepagents/backends/sandbox.py只实现两个抽象方法其余文件操作ls、glob、grep、read、write、edit均由基类基于execute()与upload_files()派生execute(command, timeout)调用devbox.cmd.exec()默认超时 30 分钟_default_timeout 30 * 60sandbox.py 第 29 行stdout 与 stderr 合并后封装为ExecuteResponse(output, exit_code, truncatedFalse)download_files(paths)逐个调用devbox.file.download()返回FileDownloadResponse列表upload_files(files)接收(path, bytes)元组列表逐个上传并返回FileUploadResponse列表。这种最小实现 基类派生的架构意味着任何第三方沙箱供应商只需实现这三个语义就能获得 Deep Agents 全套文件操作能力这也是 libs/partners 下各合作伙伴包daytona、modal、vercel 等保持同一模式的原因。五、与 deepagents-code 的集成方式langchain-runloop除了可被独立调用还被 Deep Agents 的 CLIdeepagents-code注册为内置沙箱供应商。在 sandbox_registry.py 第 64-70 行可以看到其元数据runloop: SandboxProviderMetadata( namerunloop, working_dir/home/user, installSandboxInstallHint(kindextra, namerunloop), supports_snapshot_nameTrue, backend_modulelangchain_runloop, ),三点值得注意supports_snapshot_nameTrue表示该供应商原生支持按名快照引导与本文第三节的snapshot参数能力对应working_dir/home/userAgent 在沙箱内的默认工作目录安装提示通过deepagents-code的runloopextra 安装也可由 CLI 自动提示补装。CLI 侧的用户配置文件~/.deepagents/config.toml的[sandboxes.providers]可通过package、working_dir、class_path等键对内置供应商做覆盖注册表采用配置 入口点 内置的优先级合并策略。六、错误处理与可观测性从单元测试tests/unit_tests/test_provider.py可以确认以下错误语义便于在集成时做精确的异常分支处理场景异常测试验证传入不支持的 kwargsTypeError(Received unsupported arguments: ...)test_get_or_create_rejects_unknown_kwargs挂载不存在的 Devbox IDKeyError(sandbox_id)将 SDK 的NotFoundError翻译为稳定的KeyError调用方无需导入 SDK 即可判断test_attach_to_missing_devbox_translates_not_found_to_keyerrorAPI Key 认证失败/权限不足RuntimeError提示检查RUNLOOP_API_KEY或带DEEPAGENTS_CODE_前缀的覆盖变量test_auth_failure_wraps_with_credential_hintAPI 连接/超时RuntimeError消息标注transient — safe to retry瞬态可重试test_connection_failure_wraps_as_retryableBlueprint 列取失败RuntimeError(Failed to list blueprints: ...)test_ensure_blueprint_list_failure_raises_runtime_errorBlueprint 构建失败RuntimeError(Failed to build blueprint name ...)test_ensure_blueprint_create_failure_raises_runtime_error环境变量解析的细节provider 的resolve_env_var参数支持注入自定义解析器默认实现_default_resolve_envprovider.py 第 32-49 行与 CLI 的DEEPAGENTS_CODE_前缀语义保持一致读取RUNLOOP_API_KEY时若存在DEEPAGENTS_CODE_RUNLOOP_API_KEY则优先采用存在但为空的变量视为未设置返回None避免空字符串被误当成有效配置。这一行为由test_default_resolve_env_*系列测试覆盖对同时使用 CLI 与独立 SDK 的场景尤其重要。七、测试矩阵如何验证集成正确性仓库在 tests 下划分了两层测试单元测试unit_tests/test_provider.py共 15 个用例全程 mockRunloopSDK覆盖 Blueprint 解析优先级ID 优先于 kwarg、kwarg 优先于 NAME 环境变量、分页探测、状态判定、错误翻译等所有纯逻辑分支无需真实 Runloop 账号即可运行集成测试integration_tests/test_integration.py继承langchain_tests的SandboxIntegrationTests标准套件通过RUNLOOP_API_KEY环境变量获取凭据真实创建 Devbox、以RunloopSandbox作为后端跑全套沙箱协议测试最后在 fixture 的finally中删除 Devbox——这与第二小节示例的创建—执行—清理闭环一致导入契约测试test_import.py断言__all__ {RunloopProvider, RunloopSandbox}防止公开 API 意外漂移。本地运行方式# 单元测试无需凭据 uv run pytest libs/partners/runloop/tests/unit_tests # 集成测试需先 export RUNLOOP_API_KEY... uv run pytest libs/partners/runloop/tests/integration_tests八、选型与使用建议综合以上源码与文档证据给出几条实践建议优先使用 Blueprint 按名引导为项目预建一个装好依赖、跑过uv sync或pip install -e .的 BlueprintDockerfile 可精确到基础镜像与依赖层之后所有沙箱从同一环境快速派生避免每次冷启动安装依赖生产环境用 ID 固定环境当某个 Blueprint 经过验证后用RUNLOOP_SANDBOX_BLUEPRINT_ID锁定既跳过探测流程、又防止同名重建造成环境漂移显式清理沙箱像 README 示例那样用try/finally包裹执行逻辑防止 Devbox 泄漏产生持续计费留意版本契约集成包与 deepagents 的版本存在强耦合0.0.7 ↔ deepagents 0.7.x升级核心 SDK 时请同步升级langchain-runloop否则可能触发 API 不兼容。小结langchain-runloop以约两百行的核心实现provider.py sandbox.py为 Deep Agents 提供了完整的 Runloop 云端沙箱能力从 CHANGELOG 可见的 Blueprint 引导0.0.6、依赖对齐0.0.7到按优先级解析的环境变量语义、create-if-missing 的防重复构建逻辑以及稳定的公开导出面。无论是独立调用还是作为deepagents-code的内置供应商使用其行为都有对应的单元测试与集成测试可查证是一份便于二次开发与故障排查的电池齐备集成示例。【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考