OpenAI Agents SDK 沙箱如何挂载 S3 等远程存储【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python如果你的 Sandbox Agent 需要读写存放在 S3、GCS、R2 等对象存储里的数据而不是每次都在本地临时文件里折腾OpenAI Agents SDK 的沙箱支持把这些远程存储挂载到沙箱工作区内Agent 用普通的文件工具和 shell 命令访问挂载目录数据实际留在远程桶里。本文以 Docker 沙箱后端挂载 S3 桶为主线给出仓库中现成的可运行示例、验证方式以及 S3 承载跨沙箱记忆的可选玩法。沙箱Sandbox agents目前是 beta 功能API、默认值和支持能力在 GA 前可能变化。先理解两个概念Mount 条目与挂载策略SDK 把挂载拆成两层见 docs/sandbox/clients.md 的 Mounts and remote storage 一节Mount 条目如S3Mount、GCSMount、R2Mount、AzureBlobMount、BoxMount、S3FilesMount描述暴露什么存储作为Manifest的 entries 写入挂载策略如DockerVolumeMountStrategy、InContainerMountStrategy描述沙箱后端如何把存储挂上必须同时匹配条目类型和沙箱后端。写在条目上的通用选项mount_path存储出现在沙箱里的位置。Manifest 条目路径是 workspace 相对路径时在 manifest root 下解析绝对路径原样使用。read_only默认True。只有当沙箱需要把写回落到远程存储时才设False。mount_strategy必填选一个与条目和后端都匹配的策略。一个重要的行为边界挂载被视为 ephemeral workspace 条目。快照snapshot和persist_workspace()流程会跳过或断开挂载路径而不是把远程存储复制进保存的工作区——也就是说数据本来就留在 S3 里这正是挂载的意义。准备条件按 docs/sandbox_agents.md 的快速开始部分pip install openai-agents[docker]前置条件Python 3.10 或更高宿主机运行 Docker示例用docker.from_env()连接 Docker daemon一个可运行的模型。示例默认模型为gpt-5.6-sol可通过环境变量OPENAI_MODEL覆盖。S3 侧需要的环境变量取自 examples/sandbox/memory_s3.py 与 examples/sandbox/docker/mounts/s3_mount_read_write.py。下面示例值均为占位请替换为你自己的桶名与凭据export S3_MOUNT_BUCKETmy-bucket # 桶名必填memory_s3.py 也认 S3_BUCKET export AWS_ACCESS_KEY_ID... # 你的 S3 Access Key export AWS_SECRET_ACCESS_KEY... # 你的 S3 Secret Key # 可选 export AWS_SESSION_TOKEN... # 临时凭据时的会话 token export AWS_REGIONus-east-1 # 或 AWS_DEFAULT_REGION export S3_ENDPOINT_URL... # 仅 S3 兼容端点非 AWS 官方 S3时需要 export S3_MOUNT_PREFIXsome/prefix/ # 仅挂载桶内某个前缀时需要两个运行前提需要注意镜像示例脚本ensure_mount_image()会检查本地是否存在agents-sandbox-docker-mount-example:latest缺失时基于 examples/sandbox/docker/Dockerfile.mount 构建。该镜像在 ubuntu:22.04 上安装 fuse3、固定版本 rclone1.74.4、mount-s3、blobfuse2 和 mount.s3files覆盖容器内各挂载工具的路径。rclone 卷驱动走DockerVolumeMountStrategy(driverrclone)时Docker 在容器启动前通过名为rclone的卷插件挂卷因此宿主机必须已安装 rclone Docker 卷插件。缺失时创建会话会抛出plugin rclone not found冒烟示例会直接退出并提示 rclone Docker volume plugin not found。主路径在 Docker 沙箱里挂载 S3 桶核心代码就三件事用S3Mount声明挂载、给DockerSandboxClient指定镜像、用Runner跑起来。S3Mount的字段见 src/agents/sandbox/entries/mounts/providers/s3.py字段说明bucket必填桶名prefix只挂载桶内某个前缀region区域access_key_id/secret_access_key/session_token为内联凭据endpoint_urlS3 兼容服务的端点地址s3_provider默认AWS最小可用写法与仓库示例同构from agents import Runner from agents.run import RunConfig from agents.sandbox import Manifest, SandboxRunConfig from agents.sandbox.capabilities import Filesystem, Shell from agents.sandbox.entries import DockerVolumeMountStrategy, S3Mount from agents.sandbox.sandboxes.docker import ( DockerSandboxClient, DockerSandboxClientOptions, ) manifest Manifest( entries{ # 条目键即挂载路径workspace 相对 data: S3Mount( bucketmy-bucket, # 读者自己的桶名 access_key_id..., secret_access_key..., regionus-east-1, prefixsome/prefix/, mount_strategyDockerVolumeMountStrategy(driverrclone), read_onlyFalse, # 需要 Agent 写回远程桶时设为 False ), } ) client DockerSandboxClient(docker_from_env()) # docker 库的 from_env() sandbox await client.create( manifestmanifest, optionsDockerSandboxClientOptions(imageagents-sandbox-docker-mount-example:latest), ) async with sandbox: result await Runner.run( agent, # 你的 SandboxAgent 检查 data/ 目录并列出内容。, run_configRunConfig(sandboxSandboxRunConfig(sessionsandbox)), ) print(result.final_output) await client.delete(sandbox)仓库里有一个完整可跑的示例 examples/sandbox/docker/mounts/s3_mount_read_write.py它使用上面同样的S3MountDockerVolumeMountStrategy(driverrclone)read_onlyFalse组合挂载目录为s3-docker-volume-rclone。设置好环境变量后直接运行python examples/sandbox/docker/mounts/s3_mount_read_write.py验证挂载是否真的可用验证逻辑在公共支撑模块 examples/sandbox/docker/mounts/mount_smoke.py 中流程是构建一个 shell-only 的SandboxAgent要求它把一段指定内容用printf %s写到挂载目录下的文件里再用cat读回宿主机侧通过sandbox.read(path)直接读该文件断言读回内容与写入内容完全一致全部通过则打印验证结果。运行成功时终端输出由代码逻辑决定done docker_volume/rclone: ok其中done是 Agent 按指令回复的内容docker_volume/rclone: ok表示Agent 写入 → 宿主机读回 → 内容一致这一读写闭环校验通过。失败时的两个明确信号创建会话阶段报plugin rclone not found宿主机缺 rclone Docker 卷插件见准备条件容器内挂载路径在sandbox.start()阶段抛MountCommandError示例会把exc.context里的command与stderr打印出来方便定位容器内挂载命令的失败原因。可选分支用 S3 承载跨沙箱的记忆如果你的目标是多个全新沙箱之间共享 Agent 记忆仓库提供了 examples/sandbox/memory_s3.py把Memorycapability 的 layout 指到 S3 挂载目录里让记忆产物直接落在远程存储。它的做法默认挂载目录为persistentMemory( layoutMemoryLayoutConfig( memories_dirpersistent/memories, sessions_dirpersistent/sessions, ), generateMemoryGenerateConfig(extra_promptMEMORY_EXTRA_PROMPT), )示例流程是跑两个全新的 Docker 沙箱第一个沙箱修一个 bug会话关闭时记忆生成把memory_summary.md等产物写进 S3 挂载目录第二个沙箱挂载同一个桶前缀后先断言persistent/memories/memory_summary.md非空证明 S3 里的记忆真的被新沙箱读到了再基于记忆执行后续任务。最后脚本打印 S3 里各记忆产物persistent/sessions、MEMORY.md、memory_summary.md、raw_memories、rollout_summaries的树状清单并输出S3 prefix: {prefix}。运行方式S3_BUCKET与 S3 凭据环境变量同上python examples/sandbox/memory_s3.py --model gpt-5.6-sol --prefix my-persistent-prefix--prefix不传时默认生成sandbox-memory-example/uuid形式的唯一前缀。关于 Memory 机制本身读/生成的默认行为、layout 隔离等见 docs/sandbox/memory.md。注意按该文档说明全新空沙箱的记忆是空的——跨沙箱复用记忆的前提正是把memories/目录放在可持久化的地方这里是 S3 挂载。其他远程存储与后端支持等远程存储的支持矩阵以 docs/sandbox/clients.md 的表格为准。各后端可直接挂载的远程存储类型后端AWS S3Cloudflare R2GCSAzure Blob StorageBoxS3 FilesDocker✓✓✓✓✓✓ModalSandboxClient✓✓✓---CloudflareSandboxClient✓✓✓---BlaxelSandboxClient✓✓✓---DaytonaSandboxClient✓✓✓✓✓-E2BSandboxClient✓✓✓✓✓-RunloopSandboxClient✓✓✓✓✓-VercelSandboxClient✓仅创建时挂载-----Docker 后端的四类策略通用与具体桶类型配合使用InContainerMountStrategy(patternRcloneMountPattern(...))镜像内能跑rclone时使用支持 S3、GCS、R2、Azure Blob、Box可走fuse或nfs模式InContainerMountStrategy(patternMountpointMountPattern(...))镜像内有mount-s3Mountpoint 风格的 S3 / S3 兼容访问支持S3Mount和GCSMountInContainerMountStrategy(patternFuseMountPattern(...))镜像内有blobfuse2和 FUSE 支持支持AzureBlobMountInContainerMountStrategy(patternS3FilesMountPattern(...))镜像内有mount.s3files且能访问现有 S3 Files 挂载目标DockerVolumeMountStrategy(driver...)Docker 专用容器启动前挂卷驱动S3、GCS、R2、Azure Blob、Box 可经rclone驱动挂载S3 和 GCS 还可经mountpoint驱动。容器内策略要求镜像自带对应 CLI——Dockerfile.mount里安装的 rclone、mount-s3、blobfuse2、mount.s3files 正是为此准备的agents-sandbox-docker-mount-example:latest这个示例镜像覆盖了上述全部容器内路径。换用 hosted 后端时SandboxAgent定义基本不变只改SandboxRunConfig里的 client 和对应的 provider 挂载策略各 provider 的安装 extras 与示例入口见 examples/sandbox/extensions/。凭据边界与限制这部分来自 clients.md 的说明直接关系到你能不能把内联凭据塞进挂载条目SDK 对需要受保护权限的容器内挂载采取拒绝式边界除非受信应用代码显式确认暴露范围否则在启动沙箱或挂载助手之前就会拒绝该挂载。确认方式是对 manifest 调用以挂载条目名为参数manifest.with_in_container_mount_credential_exposure_acknowledged(data)——挂载级凭据如内联 access keymanifest.with_in_container_mount_broad_credential_exposure_acknowledged(data)——更宽的权限来源托管/工作负载身份、外部凭据文件等。 两者同时需要时都要调用确认是运行期语义、不会被序列化。文档建议优先外部/provider 原生策略否则使用沙箱级、短生命周期、最小权限的凭据。无凭据的rclone挂载仅支持 S3、GCS、R2、Azure BlobFuseMountPatternblobfuse2 会发现环境中的 Azure 凭据与S3FilesMountPattern使用环境 IAM 权限需要宽范围确认。VercelSandboxClient的 S3 挂载只能在创建时配置挂载中的会话不能 resume内联凭据需allow_s3_credential_exposureTrue。会话状态序列化会移除云挂载凭据和确认标记。对支持恢复挂载会话的后端恢复时要通过SandboxRunConfig.manifest或agent.default_manifest提供当前受信的 manifest且挂载拓扑必须与持久化状态一致否则恢复在沙箱启动前失败。挂载是 ephemeral 条目快照、persist_workspace()都不会把挂载的远程存储复制进工作区注入的 live 会话也不能通过 manifest 覆盖新增或修改挂载条目。继续深入客户端选型与挂载策略全表docs/sandbox/clients.mdManifest、capability 与生命周期概念docs/sandbox/guide.md更多可运行示例examples/sandbox/含unix_local_runner.py、docker/docker_runner.py等入口【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
