如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

OpenAI 托管沙盒

运行代码并创建可下载的文件,无需管理计算资源。

OpenAI 托管沙盒为您的智能体提供一个配备 Python、Node.js 和命令行工具的 Linux 工作空间。OpenAI 负责配置并连接沙盒,您的应用负责提交任务并获取结果。如果需要使用自己的镜像、计算资源或专用网络,请选择自托管沙盒。

如果任务需要通过浏览器与网站交互,请参阅计算机使用。

如需在创建会话之前准备好工作空间,请参阅预热沙盒。

配置沙盒

在创建会话的请求中,将 environment.type 设为 openai_hosted。只添加工作负载所需的设置。沙盒的工作目录为 /workspace。

使用 container_size 和 network 选择任务所需的资源和网络访问权限。如果您使用环境模板,未指定的设置将继承模板中的值。

准备软件包和文件

使用以下设置为沙盒提供依赖项和输入文件:

  • packages:要安装 Python 包、系统软件包或全局 npm 包,请分别在 python、system 或 npm 列表中列出相应的包。需要固定版本时,请指定确切的版本号,例如 pandas==2.2.3。
  • files:通过 Files API 的文件 ID 或内联的 base64 编码内容提供输入文件。

运行初始化命令

使用 setup_commands 在智能体启动前按顺序运行 shell 命令。例如,[{ "command": "mkdir -p reports" }] 会创建一个目录。每条命令都可以单独设置 cwd,默认为 /workspace。

初始化命令运行前,软件包和输入文件均已准备就绪。您可以用初始化命令检查所需的依赖项或文件。如果初始化命令返回非零退出状态,智能体将无法启动。

设置环境变量

使用 env 设置值为字符串的环境变量。智能体生成的代码可以读取这些值。

对于密钥等敏感信息,请使用凭据库中的凭据,将真实值保存在沙盒之外。系统会拒绝使用运行时保留的变量名,包括 PATH、CODEX_* 和 OPENAI_API_KEY。

选择容器规格

创建会话时,设置 environment.container_size 即可选择沙盒可用的 CPU 和内存资源。默认值为 medium。

规格 vCPU 内存
small 1 1 GB
medium 2 4 GB
large 4 16 GB

例如,在 POST /v1/agents/sessions 请求中加入以下环境配置,即可选择 small:

{
  "environment": {
    "type": "openai_hosted",
    "container_size": "small"
  }
}

返回的会话对象会在 environment.container_size 中显示所选规格。此设置仅适用于 OpenAI 托管沙盒。

控制网络访问

network.access 行为
enabled 允许出站访问。如果未继承模板的网络策略,这是默认行为。
disabled 阻止出站访问。
restricted 仅允许访问 allowed_domains 中列出的主机。

受限模式下,请列出 1 至 100 个完整的主机名,例如 api.example.com。请勿包含通配符、协议、路径或端口。子域名和重定向目标都需要单独列出。托管的 stdio MCP 服务器目前要求将网络访问设为 enabled,请参阅 stdio MCP 要求。

添加技能和插件

使用 skills、plugins 和 capability_directories 添加技能和插件。

跨会话复用配置

设置 environment_template_id 即可复用已保存的配置。未指定的设置将继承模板中的值。覆盖网络设置时,不能扩大模板策略允许的访问范围。模板仅保存配置,不保存正在运行的工作空间。

确认初始化成功

收到创建会话的响应表示初始化已开始。要检查状态,请调用 GET /v1/agents/environments/{environment_id},其中环境 ID 取自会话的 environment.id。

状态 后续操作
provisioning 等待初始化完成。
connected 初始化成功。您可以添加或列出当前沙盒中的文件。
failed 查看 environment.error 字段。该字段位于 agent.session.environment.failed 事件中。

请等到状态变为 connected 后,再添加或列出当前沙盒中的文件。

文件与生命周期

每个会话都有独立的工作空间。只要沙盒仍然存在,文件就会在各轮交互之间保留。每轮交互完成时,/workspace/outputs 下的文件会发布为不可变的产物。沙盒过期后,您仍可下载这些副本。

有关文件上传、路径规则、沙盒内的文件操作、下载和限制,请参阅文件与产物。请在删除会话前保存所需的输出文件。

沙盒过期

已连接的沙盒会收到保活信号,两轮交互之间也会收到。如果连续一小时没有活动,也没有收到保活信号,沙盒可能会被删除。此超时时长无法配置。

使用完毕后,删除会话以请求清理沙盒。如果初始化或任务执行尚未结束,删除请求返回 409,请稍后重试,并限制重试次数。关闭事件流不会取消任务。

定价

OpenAI 托管沙盒按标准容器费率计费。模型用量按所选模型的 API 费率单独计费。

示例:创建报告

向智能体提供一个包含 10、20 和 30 的 CSV 文件。智能体会运行 Python 计算总和,并将结果写入 /workspace/outputs/summary.json。

请在运行应用的终端中设置 OPENAI_API_KEY,具体步骤见快速入门的前提条件。请将此密钥保存在沙盒之外。您使用的 OpenAI SDK 版本必须包含测试版 Agents API。

创建 summary.json
from openai import OpenAI

client = OpenAI()
stream = client.beta.agents.sessions.create(
    agent={"model": "gpt-6-astra"},
    environment={
        "type": "openai_hosted",
        "network": {"access": "disabled"},
        "files": [
            {
                "type": "inline",
                "path": "/workspace/amounts.csv",
                "data": "YW1vdW50CjEwCjIwCjMwCg==",
            }
        ],
    },
    input="Use Python to sum the amount column in /workspace/amounts.csv. Write a JSON object with the total to /workspace/outputs/summary.json, then read it back to verify it.",
    stream=True,
)

with stream.with_result_collection():
    for event in stream:
        print(event.model_dump_json())
    result = stream.get_final_result()

client.beta.agents.sessions.artifacts.for_result(result).download(
    "/workspace/outputs/summary.json", to="summary.json"
)

files 中的 base64 编码值包含 CSV 输入数据。代码会打印会话事件。请保存 session.id,其值来自 agent.session.created 事件。收到 agent.session.turn.completed 事件后,列出产物,找到 summary.json 并下载该文件。文件内容应如下所示:

{ "total": 60 }

一轮交互完成并不保证每次工具调用都成功。如果任务失败,或事件流在本轮交互完成前结束,请检查已保存的会话条目。使用完毕后,请删除会话。

故障排查

问题 排查方法
初始化失败 查看环境初始化失败事件,修复软件包、输入文件或初始化命令中的错误,再创建新会话。
沙盒发出的请求被阻止 检查 network 设置,以及请求经重定向后访问的所有主机。
沙盒内的文件操作失败 确认沙盒状态为 connected。如果沙盒已过期,请创建新会话并重新提供输入文件。
查询状态或列出文件的请求返回 5xx 逐步延长重试间隔,并设置重试截止时间。如果错误持续出现,请保留请求 ID。