适合想让云端 Agent 运行代码、处理文件，又需要明确执行边界的开发者。本文成果是：将虚构 10,20,30 CSV 送入 OpenAI-hosted Sandbox，Agent 在断网工作区内求和，写入 /workspace/outputs/summary.json，再读回验证。准备 OpenAI Platform 项目、具有 Agents API 公测权限的应用 Key 和预算；模型与托管容器分别计费。约需 30—60 分钟。官方资料核验于 2026-10-01；本站制作时只做了离线语法/策略测试，未用真实 Key 运行 API，流事件和产物需在读者账号验收。
一、区分 Agents API 和 Sandbox
Agents API 托管 Codex Harness、Session、编排及上下文管理；environment.type="openai_hosted" 让 OpenAI 为 Session 创建 Linux 工作区。它可运行代码、处理文件并生成 artifact。Agents SDK Sandbox 与 Responses API hosted shell 属不同接入路径，不能把示例参数随意混用。已有站内第一个云端 Agent 入门讲基础 Session；本文重点是网络、数据、密钥及验收边界。
OpenAI-hosted Sandbox 默认网络是 **enabled**，因此本例显式设为 network.access="disabled"。应用 Key 留在调用应用，不能放进 Sandbox 的 env 或输入文件。每个 Session 有独立工作区；/workspace/outputs 下文件在回合完成后发布为不可变 artifact。环境创建响应不等于准备完成，必要时查看环境状态直到 connected。托管 Sandbox 与模型分别计费，长期闲置与重试也应纳入预算。
二、跑通最小案例
第 1 步：准备权限
在 OpenAI Platform 创建应用 API Key，给 Session 操作 api.agents.read、api.agents.write，给推理 api.responses.write。在应用终端设置 OPENAI_API_KEY，不要写进仓库、日志或 Sandbox。安装当前官方 Python SDK：python -m pip install --upgrade openai。选择账号可用模型并核对价格；示例默认 gpt-6-astra，可通过应用环境变量 AGENT_MODEL 调整。
第 2 步：运行免费示例
下载本文Sandbox 示例代码，解压后运行 python sandbox_demo.py。代码创建 openai_hosted Session、small 容器、禁用出站网络，并以内联 base64 方式传入虚构 CSV。任务要求 Agent 用 Python 求和，将 JSON 写到 /workspace/outputs/summary.json，读回并报告实际值。预期 total=60；包内 JSON 是目标结构示意，**不是实际 API 返回**。
第 3 步：核验事件和文件
从流事件确认 Sandbox 已连接、命令真实执行、JSON 被读回；按官方 Files and artifacts 文档下载最终产物，核对 total 与源 CSV 的三行相符。若状态仍为 provisioning，通过 GET /v1/agents/environments/{environment_id} 查状态；failed 查对应事件错误。若使用 cURL，请带 OpenAI-Beta: agents=v1；官方 SDK 会自动加入。保存需要的产物后清理 Session，关闭事件流并不等于取消任务。
三、商业场景的安全边界
| 控制点 | 本例配置 | 发布前核验 |
|---|---|---|
| 输入 | 只用合成 CSV、64 KiB 上限 | 拒绝密钥、个人与客户资料 |
| 网络 | 显式 disabled | 不让 Agent 出站访问未知域名 |
| 密钥 | 应用层持有 | 不注入沙箱或生成代码 |
| 文件 | 限定 /workspace/input.csv 与 outputs | 产物读回、下载、清理 |
| 权限 | 专用项目和最小 API 权限 | 预算、日志与 Session 生命周期 |
| 外部动作 | 无 MCP、无业务系统写入 | 新增动作前单独审批 |
网络断开不能单独构成完整安全保证。Agent 生成的代码能访问其环境内的文件和变量；需要第三方凭据时，按官方 Vault/代理机制设计，不直接把真实密钥作为普通环境变量暴露给 Agent。不同客户或敏感工作负载分环境。Agents API 当前仅支持美国数据驻留，不支持 ZDR；改用自托管执行环境也不改变 API 这一边界。此案例只适合虚构或获准进入该服务的数据。
四、常见失败与回滚
| 现象 | 定位 | 处理 |
|---|---|---|
| 401/403 | Key 权限或项目限制 | 核对三项 scope 和模型权限，勿贴出 Key |
beta.agents 不存在 | SDK 过旧 | 更新官方 SDK 并对照公测文档 |
| 环境一直 provisioning | setup 或连接未完成 | 查询环境状态与 failed 事件，限制重试次数 |
| 求和错误 | 读取/执行不符 | 对照 CSV、实际命令和产物，拒绝发布错误结果 |
| 找不到文件 | 路径或回合状态 | 确认写在 outputs 且回合结束 |
| 费用异常 | 模型、容器、重试 | 停止新任务、清理 Session、检查用量 |
回滚时停止新 Session、保留审计记录，撤下错误 artifact 的公开链接，恢复到合成输入和显式断网配置；若怀疑泄密立即撤销或轮换相关 Key。
五、免费与付费资料
免费下载 Sandbox 示例代码能独立完成一次虚构 CSV 求和练习，含操作说明和目标输出示例。
查看 ¥29.90 安全 Agent 执行环境完整项目提供应用侧输入校验、默认断网的请求构造、dry-run、七项离线测试、部署验收、权限、排错回滚与更新记录。交付范围是受限 CSV 演示项目，不是任意命令的企业生产控制平面；真实 API、artifact 下载及生产安全审计需在购买者环境验收。
FAQ
Hosted Sandbox 默认断网吗？
不是。官方文档的 network.access 默认 enabled，本例明确配置 disabled。
能把 OPENAI_API_KEY 放入 Sandbox env 吗？
不应这样做。应用 Key 留在应用侧，且该名称是沙箱保留变量；Agent 生成代码能读取环境变量。
创建 Session 成功就表示代码已经跑完吗？
不是。环境准备、流事件、结果读回与 artifact 下载都需要单独核验。
自托管 Sandbox 能获得 ZDR 吗？
不能凭执行环境切换推断。官方目前说明 Agents API 不支持 ZDR，自托管也不改变这一点。
官方来源与核验
核验日期 2026-10-01：Agents API Quickstart、OpenAI-hosted sandboxes、Sandbox security、Agents API overview。表中的安全配置为本站示例方案，未宣称真实运行或生产认证。
工具选型与提示词资料
适合阅读工具评测、工具推荐、对比测评类文章后继续转化。
