Deep Agents 中的 Runloop 沙箱集成从零启动 Devbox 到 Blueprint 预置环境实战【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents导读本文围绕 langchain-runloop 这一 Deep Agents 官方合作伙伴集成包展开它让 Agent 可以借助 Runloop 云端 devbox 作为隔离的执行沙箱完成命令执行、文件上传/下载等安全操作。读完本文你将掌握RunloopProvider的完整生命周期用法创建、挂载、删除理解snapshot参数与RUNLOOP_SANDBOX_BLUEPRINT_ID/RUNLOOP_SANDBOX_BLUEPRINT_NAME两个环境变量的优先级规则并能通过自定义 Dockerfile 预置带依赖的运行环境把这套能力接入你自己的 Deep Agents 后端。这个包解决什么问题langchain-runloop是 Deep Agents 的 Runloop 沙箱集成层本质是一个遵循SandboxBackendProtocol标准的后端适配器。它把 Runloop 的 devbox云端隔离的开发沙箱封装成 Deep Agents 可以直接调用的执行环境让 Agent 在完全隔离的云容器里运行任意 shell 命令而不会污染本地文件系统。从仓库结构看这个包的核心代码非常精简只有三个模块provider.py —— 负责 devbox 生命周期管理创建、挂载、删除以及 Blueprint 启动逻辑sandbox.py —— 实现BaseSandbox协议提供execute、upload_files、download_files等沙箱操作init.py —— 对外暴露RunloopProvider与RunloopSandbox两个公开 API。快速安装推荐使用uv作为包管理器仓库本身也通过 uv.lock 锁定依赖版本uv add langchain-runloop在 pyproject.toml 中可以确认它的运行时依赖为deepagents0.7.0,0.8.0和runloop-api-client并要求 Python 版本在 3.11 到 3.14 之间requires-python 3.11,4.0。也就是说这个包必须配合 Deep Agents 0.7.x 版本使用安装前请先核对你的 Deep Agents 版本。第一个示例创建、执行、删除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)对照 provider.py 的源码这三步的底层行为如下get_or_create()在没有任何 Blueprint 相关参数时直接调用self._sdk.devbox.create()创建一个全新的空 devbox对应源码 provider.pysandbox.execute(echo hello)由 sandbox.py 实现它调用 devbox 的cmd.exec执行命令默认超时时间为 30 分钟self._default_timeout 30 * 60并把 stdout 与 stderr 合并进ExecuteResponse.output同时返回exit_code与truncated标志provider.delete(sandbox_idsandbox.id)通过底层 client 的devboxes.shutdown(idsandbox_id)关闭 devbox见 provider.py。注意RunloopSandbox继承自 Deep Agents 的BaseSandbox见 sandbox.py后者位于 libs/deepagents/deepagents/backends/sandbox.py 中。BaseSandbox基于execute()提供了文件列表、grep、glob、读写等默认实现因此这个后端不仅能跑命令还能支撑 Agent 的完整文件系统操作。从命名 Blueprint 启动预置环境的关键每次创建全新 devbox 意味着环境里什么都没有。Runloop 的 Blueprint蓝图概念允许你预构建一个带固定依赖和镜像的模板之后每次从该模板快速拉起 devbox。langchain-runloop将这一能力通过snapshot参数暴露出来sandbox provider.get_or_create(snapshotmy-blueprint)这个参数语义上与 LangSmith snapshots 类似即create-if-missing如果名为my-blueprint的 Blueprint 不存在则自动创建并等待构建完成如果已存在且构建成功则直接复用。Blueprint 的解析优先级当 Blueprint 相关信息同时来自多个来源时源码明确规定了以下优先级见 provider.pyRUNLOOP_SANDBOX_BLUEPRINT_ID环境变量按 ID 启动跳过所有列表查询和构建流程直接调用create_from_blueprint_idsnapshot参数即 Blueprint 名称按名称启动create-if-missingRUNLOOP_SANDBOX_BLUEPRINT_NAME环境变量与snapshot相同也按名称启动create-if-missing以上都不设置时回退到创建空 devbox与旧版本行为完全一致。README 中那句ID wins; skips auto-build正是第 1 条优先级的直白描述。这套优先级在单元测试 test_provider.py 中有非常完整的覆盖test_blueprint_id_env_wins_over_kwarg验证了RUNLOOP_SANDBOX_BLUEPRINT_ID优先于显式传入的snapshot参数test_kwarg_wins_over_blueprint_name_env验证了snapshot参数优先于RUNLOOP_SANDBOX_BLUEPRINT_NAME环境变量test_blueprint_name_env_used_when_no_kwarg验证了无参数时环境变量生效test_sandbox_id_skips_blueprint_logic验证了显式指定sandbox_id挂载已有 devbox 时完全绕过 Blueprint 解析逻辑。用环境变量固定 Blueprint如果你不想在代码里写死 Blueprint 名称可以通过环境变量注入export RUNLOOP_SANDBOX_BLUEPRINT_NAMEmy-blueprint # 或者使用 Blueprint ID优先级更高跳过自动构建 export RUNLOOP_SANDBOX_BLUEPRINT_IDbp-xxxxxxxx从源码看这两个环境变量只在get_or_create调用时读取且读取逻辑支持DEEPAGENTS_CODE_前缀覆盖provider.py中的_default_resolve_env会先检查DEEPAGENTS_CODE_RUNLOOP_SANDBOX_BLUEPRINT_ID是否存在存在且非空则优先使用否则回退到无前缀变量见 provider.py。这与 deepagents-code CLI 的行为保持一致方便你在被 CLI 包裹的场景下统一注入配置。对应的单元测试test_default_resolve_env_prefix_wins验证了前缀变量覆盖普通变量的行为。自定义 Blueprint 的 Dockerfile按名称启动且 Blueprint 不存在时包会用一段默认 Dockerfile 自动构建FROM python:3这段默认值定义在源码常量_DEFAULT_BLUEPRINT_DOCKERFILE中见 provider.py。如果你需要预装 Python 包、系统依赖或特定工具链可以通过blueprint_dockerfile参数传入自定义 Dockerfilesandbox provider.get_or_create( snapshotdata-science-env, blueprint_dockerfile\ FROM python:3.12 RUN pip install pandas numpy scikit-learn RUN apt-get update apt-get install -y --no-install-recommends git curl , )测试test_blueprint_dockerfile_forwarded_to_ensure和test_blueprint_dockerfile_defaults_when_omitted分别验证了自定义 Dockerfile 会被透传给构建流程、省略时使用默认FROM python:3。Blueprint 构建的状态机_ensure_blueprint函数见 provider.py实现了确保 Blueprint 可用的完整逻辑分页列出所有 Blueprint每页 100 个通过starting_after游标翻页找到同名 Blueprint 时检查其状态build_complete直接复用不重复构建failed抛出RuntimeError提示删除它重试或修复 Dockerfilequeued/provisioning/building抛出RuntimeError提示等待完成或删除后重建完全找不到同名 Blueprint 时调用create_and_await_build_complete同步创建并等待构建完成。对应测试覆盖了这些分支test_ensure_blueprint_reuses_build_complete复用已构建、test_ensure_blueprint_builds_when_missing缺失时构建、test_ensure_blueprint_raises_when_in_flight构建中报错、test_ensure_blueprint_failed_status_advises_delete失败状态提示删除、test_ensure_blueprint_paginates_to_find_ready_match分页找到可用 Blueprint。挂载已有 devbox断点续跑get_or_create同样支持通过sandbox_id挂载一个已经存在的 devbox适合 Agent 断点续跑或共享工作现场的场景sandbox provider.get_or_create(sandbox_iddevbox-id)此时包会调用self._sdk.devbox.from_id(sandbox_id)进行挂载完全跳过 Blueprint 解析测试test_sandbox_id_skips_blueprint_logic验证了这一行为。一个值得注意的实现细节是如果该 ID 不存在SDK 抛出的NotFoundError会被转译成标准的KeyError(sandbox_id)见 provider.py这样调用方例如 deepagents-code 的沙箱工厂无需导入 runloop SDK 就能捕获沙箱不存在的异常。测试test_attach_to_missing_devbox_translates_not_found_to_keyerror专门覆盖了这个异常转换行为。沙箱操作能力一览RunloopSandbox目前实现的协议方法如下全部在 sandbox.py 中方法作用底层调用execute(command, timeoutNone)在 devbox 内执行 shell 命令devbox.cmd.exec默认超时 30 分钟合并 stdout/stderrdownload_files(paths)批量下载 devbox 中的文件devbox.file.download返回FileDownloadResponse列表upload_files(files)批量上传文件到 devboxdevbox.file.upload返回FileUploadResponse列表id属性返回 devbox ID构造时缓存这些响应类型ExecuteResponse、FileDownloadResponse、FileUploadResponse均定义在 Deep Agents 的 backends/protocol.py 中其中文件操作响应被设计为支持批量部分失败每个条目独立携带error字段便于 LLM 在批量文件操作时定位失败项。另外sandbox.py 的execute支持传入timeout参数覆盖默认的 30 分钟超时如果传None则使用后端默认值。错误处理约定RunloopProvider对底层 SDK 异常做了系统性的归一化见 provider.py这对 Agent 场景尤其重要——错误信息必须能被模型理解并采取行动底层异常转换结果提示信息AuthenticationError/PermissionDeniedErrorRuntimeError检查RUNLOOP_API_KEY或DEEPAGENTS_CODE_RUNLOOP_API_KEYAPIConnectionError/APITimeoutErrorRuntimeError标记为瞬态错误transient安全重试其他创建异常RuntimeError包含目标 Blueprint 名称或 ID 的上下文信息NotFoundError挂载时KeyError(sandbox_id)供调用方识别沙箱缺失对应的异常转换测试test_auth_failure_wraps_with_credential_hint、test_connection_failure_wraps_as_retryable、test_blueprint_failure_wraps_in_runtime_error在 test_provider.py 中均有覆盖。另外get_or_create只接受白名单参数任何未支持的额外 kwargs 会直接抛出TypeError测试test_get_or_create_rejects_unknown_kwargs验证与 LangSmith provider 的行为保持一致。测试与集成验证单元测试仓库在 tests/unit_tests/ 下提供了两组单元测试test_provider.py 覆盖 Blueprint 解析优先级、异常转换、默认 Dockerfile、delete关闭 devbox、_ensure_blueprint全部分支复用/构建/进行中/失败/分页以及_default_resolve_env的前缀覆盖逻辑test_import.py 锁定公开 API 面确保langchain_runloop.__all__恰好是{RunloopProvider, RunloopSandbox}。在libs/partners/runloop目录下执行单元测试make test等价于uv run --group test pytest -vvv --disable-socket --allow-unix-socket tests/unit_tests/默认禁用网络访问仅用 mock 验证逻辑。集成测试tests/integration_tests/test_integration.py 通过SandboxIntegrationTests标准测试套件验证真实环境下的行为需要真实 API KeyRUNLOOP_API_KEYyour-key make integration_test集成测试的 fixture 会读取RUNLOOP_API_KEY环境变量缺失时直接报错提示真实创建一个 devbox 并包装成RunloopSandbox测试结束后调用client.devboxes.delete清理资源。与 Deep Agents 主框架的衔接在 Deep Agents 的整体架构中runloop 属于沙箱合作伙伴集成之一。RunloopSandbox实现BaseSandbox协议backends/sandbox.pyRunloopProvider的get_or_create与其它 provider 保持相同的签名约定sandbox_id、timeout、snapshot、**kwargs其中timeout参数在源码中被显式标注为为与其他 provider 保持 API 一致而保留见 provider.pysnapshot的语义则与 LangSmith 快照对齐——这保证了 Deep Agents 上层代码可以用统一的方式调度不同云沙箱提供商。版本与兼容性根据 CHANGELOG.md 与 pyproject.toml当前版本为 0.0.7要求deepagents0.7.0,0.8.00.0.6 版本引入了 Blueprint 启动能力即snapshot参数与相关环境变量0.0.5 及更早版本适配的是 Deep Agents 0.6 及以前的协议。如果升级 Deep Agents 主框架请同步升级langchain-runloop避免协议不匹配导致沙箱方法签名失效。常见问题与排查建议Q1RuntimeError: Runloop rejected the credentials说明 API Key 无效或权限不足。检查RUNLOOP_API_KEY或被 CLI 包裹时的DEEPAGENTS_CODE_RUNLOOP_API_KEY是否设置正确。Q2RuntimeError: ... (transient — safe to retry)属于网络瞬态错误稍后重试即可。Q3RuntimeError: Blueprint xxx exists but its last build failed同名 Blueprint 上次构建失败。删除该 Blueprint 或修复自定义 Dockerfile 后重试只有failed状态是终态queued、provisioning、building均表示仍在进行中等待构建完成即可。Q4挂载不存在的 devbox 时报KeyError这是设计行为NotFoundError被转译为KeyError(sandbox_id)请确认 devbox ID 正确或改为不传sandbox_id重新创建。Q5如何判断一条命令执行失败execute返回的ExecuteResponse携带exit_code字段非零即表示命令失败output中同时包含 stdout 与 stderr若 stderr 非空会追加到 output 末尾便于 Agent 分析失败原因。小结langchain-runloop用极小的代码面为 Deep Agents 提供了完整的 Runloop 云端沙箱能力get_or_create一个方法统一了创建空 devbox、挂载已有 devbox、从命名 Blueprint 启动三种模式snapshot参数与RUNLOOP_SANDBOX_BLUEPRINT_ID/RUNLOOP_SANDBOX_BLUEPRINT_NAME环境变量构成了清晰、可测试的优先级体系自定义 Dockerfile 让预置环境变得可复制、可版本化。如果你正在为 Deep Agents 寻找开箱即用的隔离执行环境这套集成是值得直接落地的选择。【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考