openai-agents-python 沙箱客户端选型与实践指南从本地到托管环境的完整迁移路径【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python本指南基于 docs/zh/sandbox/clients.md 展开系统讲解 openai-agents-python 沙箱Sandbox功能中在哪里运行沙箱工作这一核心决策从零安装的UnixLocalSandboxClient、容器隔离的DockerSandboxClient到七种托管沙箱客户端以及贯穿始终的挂载Mount与远程存储、凭据确认安全模型。读完本文你将能够在不改动SandboxAgent定义的前提下仅通过调整SandboxRunConfig中的客户端与客户端专属选项完成本地开发、容器隔离、托管生产环境的平滑切换并安全地接入 S3、GCS、R2、Azure Blob、Box 等远程存储。Beta 功能提示沙箱智能体目前处于 Beta 阶段。在正式发布之前API 细节、默认值和支持的功能可能会发生变化后续将逐步提供更高级的功能。核心设计智能体不变只换运行配置沙箱功能在架构上刻意将智能体定义与沙箱运行时解耦。SandboxAgent只负责描述模型、指令与能力capabilities而沙箱工作具体运行在哪一种环境中完全由RunConfig中的沙箱配置决定。从源码看SandboxRunConfig是一个聚合配置的数据类其关键字段包括字段作用client用于创建或恢复沙箱会话的客户端类型为BaseSandboxClient[Any]是本文选型的主角options创建新会话时使用的客户端专属选项如 Docker 镜像、Modal 资源规格session当前进程复用的活沙箱会话覆盖如 docker_runner.py 中手动create()后传入session_state在未使用RunState负载时显式指定要恢复的SandboxSessionStatemanifest创建新会话时的沙箱清单manifest覆盖snapshot创建新会话时使用的快照规格concurrency_limits/archive_limits沙箱物化与归档解压的资源限制cwd模型面对的工作目录相对沙箱工作区根目录这种定义与运行时分离的设计意味着从 Unix 本地切换到 Docker再到任何托管平台SandboxAgent的定义始终保持不变你只需要替换SandboxRunConfig中的client与options。决策指南先想清楚目标环境官方文档给出了一张面向目标的选型决策表是理解全部沙箱客户端的起点目标首选方案原因在 macOS 或 Linux 上实现最快的本地迭代UnixLocalSandboxClient无需额外安装便于使用本地文件系统进行开发基本的容器隔离DockerSandboxClient使用特定镜像在 Docker 内运行工作托管执行或生产级隔离托管沙箱客户端将工作区边界移至由提供商管理的环境从源码结构看这条决策路径与实现分层一一对应src/agents/sandbox/sandboxes/下只有两个内置本地实现unix_local.py与docker.py而托管客户端全部作为扩展extensions提供sandboxes/__init__.py中还体现了平台适配逻辑——UnixLocalSandboxClient仅在非 Windows 平台sys.platform ! win32导入而 Docker 作为可选 extra 依赖在未安装时会被优雅降级而不破坏基础导入。本地客户端UnixLocal 与 Docker对于大多数用户官方建议从以下两个沙箱客户端之一开始客户端安装适用场景示例UnixLocalSandboxClient无在 macOS 或 Linux 上实现最快的本地迭代适合作为本地开发的默认选择unix_local_runner.pyDockerSandboxClientopenai-agents[docker]需要容器隔离或需要使用特定镜像在本地复现目标环境docker_runner.pyUnix 本地客户端是基于本地文件系统开始开发的最简便方式。当你需要更强的环境隔离或与生产环境保持一致时可迁移到 Docker 或托管提供商。路径授权的差异SandboxPathGrant.host_path一个容易被忽略但很关键的差异是路径授权语义SandboxPathGrant.host_path仅适用于 Docker它可以将主机路径映射到容器内不同的 POSIX 路径而 Unix 本地客户端只支持相同路径的授权same-path grants。完整的行为约束参见 docs/sandbox/guide.md 中的清单路径授权章节。UnixLocalSandboxClient还提供了环境继承控制构造参数inherit_host_environment默认True决定是否继承宿主机环境变量host_environment_allowlist则用于在关闭继承时按名称白名单放行指定变量——两者同时使用时会在构造阶段直接抛出ValueError这是 unix_local.py 中明确实现的防御性校验。从 Unix 本地切换到 Docker只改运行配置官方文档给出了标准切换模式——保持智能体定义不变仅更改运行配置from docker import from_env as docker_from_env from agents.run import RunConfig from agents.sandbox import SandboxRunConfig from agents.sandbox.sandboxes.docker import DockerSandboxClient, DockerSandboxClientOptions run_config RunConfig( sandboxSandboxRunConfig( clientDockerSandboxClient(docker_from_env()), optionsDockerSandboxClientOptions(imagepython:3.14-slim), ), )当你需要容器隔离或希望沙箱镜像与其他环境中使用的镜像保持一致时请使用此方式。其中docker_from_env()来自 docker SDK从宿主机 Docker 环境socket、环境变量等构造客户端代码仓库内置的默认 Python 沙箱镜像常量DEFAULT_PYTHON_SANDBOX_IMAGE python:3.14-slim定义在 config.py上面的示例即与该默认值保持一致从源码看DockerSandboxClientOptions是 pydantic 模型字段包括image必填、exposed_ports默认空元组、network_mode仅允许none或None以及labels。完整的可运行示例请参考 examples/sandbox/docker/docker_runner.py它展示了完整生命周期构造 manifest → 创建SandboxAgent含default_manifest、capabilities[WorkspaceShellCapability()]→docker_client.create()分配会话 →Runner.run_streamed()流式驱动 →finally中docker_client.delete()释放容器。禁用 Docker 网络network_modenone当 Docker 沙箱不得访问网络时设置network_modenoneoptions DockerSandboxClientOptions( imagepython:3.14-slim, network_modenone, )需要注意以下语义均有源码佐证唯一受支持的显式网络模式是none省略network_mode保持None则保留 Docker 的默认行为禁用网络的沙箱无法暴露端口将network_modenone与非空的exposed_ports元组组合使用会在选项验证期间失败。这一校验实现在_validate_docker_network_configurationdocker.py其逻辑为if network_mode none and exposed_ports: raise ValueError(exposed_ports cannot be used when network_modenone)该设置会存储在沙箱会话状态中DockerSandboxSessionState.network_mode如果 SDK 在恢复会话状态时必须创建替代容器此设置也会被重新应用——即网络策略随状态持久化替代容器不会意外获得网络。挂载与远程存储条目 策略两层模型挂载体系是沙箱接入外部存储的核心机制它由两层概念组成挂载条目Mount entries描述要公开哪些存储如某个 S3 bucket挂载策略Mount strategies描述沙箱后端如何附加这些存储如用rclone还是 Docker volume。内置挂载条目和通用策略从agents.sandbox.entries导入托管提供商的策略则从agents.extensions.sandbox或提供商专属扩展包获取。源码中agents.sandbox.entries的导出列表entries/init.py确认了这些符号的可用性。常用挂载选项选项说明mount_path存储在沙箱中的显示位置。相对路径基于清单根目录manifest root解析绝对路径按原样使用read_only默认为True。仅当沙箱应将更改写回已挂载存储时才设置为Falsemount_strategy必需。请使用同时匹配挂载条目和沙箱后端的策略挂载会被视为临时工作区条目快照和持久化流程会分离或跳过已挂载路径而不会将挂载的远程存储复制到保存的工作区中。这意味着挂载的内容是活的外部存储引用而非工作区快照的一部分。通用本地/容器策略策略或模式适用场景说明InContainerMountStrategy(patternRcloneMountPattern(...))沙箱镜像可以运行rclone支持 S3、GCS、R2、Azure Blob 和 Box。RcloneMountPattern可以在fuse模式或nfs模式下运行InContainerMountStrategy(patternMountpointMountPattern(...))镜像包含mount-s3并且你希望以 Mountpoint 方式访问 S3 或 S3 兼容存储支持S3Mount和GCSMountInContainerMountStrategy(patternFuseMountPattern(...))镜像包含blobfuse2并支持 FUSE支持AzureBlobMountInContainerMountStrategy(patternS3FilesMountPattern(...))镜像包含mount.s3files并且能够访问现有的 S3 Files 挂载目标支持S3FilesMountDockerVolumeMountStrategy(driver...)Docker 应在容器启动前附加由卷驱动程序支持的挂载仅适用于 Docker。S3、GCS、R2、Azure Blob 和 Box 可通过rclone挂载S3 和 GCS 也可通过mountpoint挂载从源码可以进一步了解各模式的行为细节entries/mounts/patterns.pyRcloneMountPatternL686 起默认modefuse可选nfsremote_name未指定时会基于remote_kind与会话 ID 推导出确定性的每会话 remote 名sandbox_{remote_kind}_{session_id}使多个挂载可以共存而不共享可变的 rclone 配置段MountpointMountPatternL438 起的MountpointOptions支持prefix、region、endpoint_url等参数FuseMountPatternL173 起为blobfuse2提供了丰富的缓存调优字段包括cache_typeblock_cache/file_cache、cache_size_mb、block_cache_block_size_mb、各类缓存超时attr_cache_timeout_sec、entry_cache_timeout_sec等S3FilesMountPatternL578 起的S3FilesOptions支持mount_target_ip、access_point、region与extra_options并在apply时首先通过command -v mount.s3files校验镜像内工具是否存在。以S3Mount为例providers/s3.py一个挂载条目包含bucket必填、可选的access_key_id/secret_access_key/session_token内联凭据、prefix、region、endpoint_url以及s3_provider默认AWS可用于 S3 兼容存储。支持的托管平台当你需要托管环境时通常可以继续使用相同的SandboxAgent定义仅需更改SandboxRunConfig中的沙箱客户端。如果你使用的是已发布的 SDK而非此代码仓库的检出版本请通过匹配的软件包 extra 安装沙箱客户端依赖项。有关代码仓库中扩展代码示例的提供商专属设置说明和链接请参阅 examples/sandbox/extensions/README.md。客户端安装示例BlaxelSandboxClientopenai-agents[blaxel]blaxel_runner.pyCloudflareSandboxClientopenai-agents[cloudflare]cloudflare_runner.pyDaytonaSandboxClientopenai-agents[daytona]daytona_runner.pyE2BSandboxClientopenai-agents[e2b]e2b_runner.pyModalSandboxClientopenai-agents[modal]modal_runner.pyRunloopSandboxClientopenai-agents[runloop]runner.pyVercelSandboxClientopenai-agents[vercel]vercel_runner.pyModal 沙箱规格使用ModalSandboxClientOptions.cpu和ModalSandboxClientOptions.memory为新的 Modal 沙箱请求资源单个值表示请求该数量的资源包含两个元素的(request, limit)元组将第一个元素用作请求值第二个元素用作限制值内存值的单位为 MiB。from agents.extensions.sandbox import ModalSandboxClientOptions options ModalSandboxClientOptions( app_nameagents-sandbox, cpu(1.0, 4.0), memory(2048, 8192), )将cpu、memory或两者保留为None即可对每项省略的资源使用 Modal 的默认值。选定的值会保留在沙箱会话状态中以便替代沙箱replacement sandbox使用相同的资源配置——这一点与 Docker 的network_mode持久化语义一致客户端选项中的关键配置随会话状态存续。各托管后端的挂载能力托管沙箱客户端会提供提供商专属的挂载策略。请选择最适合你的存储提供商的后端和挂载策略后端挂载说明Docker支持将S3Mount、GCSMount、R2Mount、AzureBlobMount、BoxMount和S3FilesMount与InContainerMountStrategy、DockerVolumeMountStrategy等本地策略配合使用ModalSandboxClient支持使用ModalCloudBucketMountStrategy搭配S3Mount、R2Mount和通过 HMAC 认证的GCSMount来挂载云存储桶。你可以使用内联凭据或命名的 Modal SecretCloudflareSandboxClient支持使用CloudflareBucketMountStrategy搭配S3Mount、R2Mount和通过 HMAC 认证的GCSMount来挂载存储桶BlaxelSandboxClient支持将BlaxelCloudBucketMountStrategy与S3Mount、R2Mount或GCSMount条目配对以挂载云存储桶。还支持通过BlaxelDriveMount和BlaxelDriveMountStrategy使用持久化 Blaxel Drives两者均可从agents.extensions.sandbox.blaxel获取DaytonaSandboxClient支持使用DaytonaCloudBucketMountStrategy通过rclone挂载云存储可将其与S3Mount、GCSMount、R2Mount、AzureBlobMount和BoxMount配合使用E2BSandboxClient支持使用E2BCloudBucketMountStrategy通过rclone挂载云存储可将其与S3Mount、GCSMount、R2Mount、AzureBlobMount和BoxMount配合使用RunloopSandboxClient支持使用RunloopCloudBucketMountStrategy通过rclone挂载云存储可将其与S3Mount、GCSMount、R2Mount、AzureBlobMount和BoxMount配合使用VercelSandboxClient支持将VercelCloudBucketMountStrategy与S3Mount条目配对以挂载仅能在创建时配置的 S3 和 S3 兼容存储桶已挂载的会话无法恢复并且内联凭据需要allow_s3_credential_exposureTrue凭据边界与挂载确认机制挂载表说明了每个后端可以处理哪些存储类型但勾选标记并不会绕过运行在模型控制沙箱内的挂载辅助程序的凭据边界也不表示每种策略都能在没有凭据的情况下运行。这是沙箱安全模型中最重要的部分Agents SDK仅在所选辅助程序无需受保护权限即可运行时才接受未附带确认acknowledgement的容器内挂载如果挂载需要受保护的权限而受信任的应用程序代码未明确确认为该确切挂载路径暴露此权限Agents SDK 会在启动沙箱或挂载辅助程序之前拒绝该挂载。无凭据挂载与广泛确认场景无凭据的rclone挂载仅限于 S3、GCS、R2 和 Azure Blob容器内的Box 挂载需要非交互式身份验证来源以及与该来源匹配的确认FuseMountPattern需要广泛权限确认因为blobfuse2会发现环境中已有的 Azure 权限即使未配置内联凭据也是如此S3FilesMountPattern同样需要广泛权限确认因为mount.s3files会使用环境中已有的 IAM 权限当 Docker 作为后端时这些要求同样适用。两类确认 API 与 Manifest 的运行时策略对于名为data的挂载条目请保留由与所配置权限匹配的确认所返回并复制的Manifest# Mount-scoped values such as inline access keys. manifest manifest.with_in_container_mount_credential_exposure_acknowledged(data) # Broader authority such as managed or workload identity and external credential files. manifest manifest.with_in_container_mount_broad_credential_exposure_acknowledged(data)源码确认了这两类确认的语义manifest.py它们是受信任的应用侧策略仅在运行时有效不会被序列化docstring 明确标注 runtime-only and is not serialized实现上通过_with_mount_credential_exposure_acknowledged(authority, mount_paths)将确认路径分别记录到mount_scoped与broad两个策略集合中并返回一个深拷贝的受信 Manifest必须传入所有需要确认的确切挂载路径使用两类权限的挂载需要两项确认确认允许辅助程序接收凭据但不会将凭据的使用限制在挂载路径内——因此它本质上是对辅助程序可能以更高权限访问凭据的知情同意底层校验_manifest_has_configured_mount_authority_mount_security.py会递归遍历 manifest 条目识别配置或可能隐藏凭据权限的挂载未确认即拒绝启动。最佳实践如果可用请优先选择外部策略或提供商原生策略否则请使用限定在沙箱范围内、短期有效且遵循最小权限原则的凭据。VercelSandboxClientOptions(allow_s3_credential_exposureTrue)仍然是一个兼容性选项仅适用于在创建 Vercel S3 挂载时使用内联且限定于挂载范围的凭据它不授予广泛的凭据权限。后端 × 存储类型能力矩阵下表汇总了每个后端可以直接挂载哪些远程存储条目后端AWS S3Cloudflare R2GCSAzure Blob StorageBoxS3 FilesDocker✓✓✓✓✓✓ModalSandboxClient✓✓✓---CloudflareSandboxClient✓✓✓---BlaxelSandboxClient✓✓✓---DaytonaSandboxClient✓✓✓✓✓-E2BSandboxClient✓✓✓✓✓-RunloopSandboxClient✓✓✓✓✓-VercelSandboxClient✓-----从矩阵可以提炼出清晰的选型规律Docker 是唯一全类型覆盖的后端Modal、Cloudflare、Blaxel 聚焦 S3/R2/GCS 三类对象存储Daytona、E2B、Runloop 通过rclone覆盖到 Azure Blob 与 BoxVercel 仅支持 S3 且受创建时配置、不可恢复会话等限制约束。更多可运行的示例如需更多可运行的代码示例请浏览 examples/sandbox/ 目录其中包含本地unix_local_runner.py、Dockerdocker_runner.py、编码任务docs/coding_task.py、内存memory.py、memory_s3.py、任务转移handoffs.py和智能体组合sandbox_agents_as_tools.py等模式另请浏览 examples/sandbox/extensions/其中包含托管沙箱客户端的扩展示例Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop、Vercel 等。此外examples/sandbox/docker/mounts/ 下还提供了s3_mount_read_write.py、gcs_mount_read_write.py、azure_mount_read_write.py等针对具体存储的读写挂载示例可作为挂载实践的直接参考。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考