OpenAI 预热沙箱

预热环境允许在创建智能体会话前，先创建 OpenAI 托管沙箱、安装软件包、加载文件并运行初始化命令。任务到达后，将已准备环境附加到会话，再启动智能体。

延迟要求较高时适合预热：例如用户选择数据集时，报告应用就准备 Python 依赖；用户编写请求时，编码工作流先准备工作区。提前启动初始化，可减少用户实际等待时间。

工作方式

环境是运行工具的工作区，会话保存智能体配置与对话。预热将两者分开：

1. 创建环境：提供任务需要的软件包、文件及初始化命令。
2. 等待就绪：轮询环境直到 ready，或使用 webhook。
3. 启动会话：创建会话时传入环境 ID。

也可在初始化未结束时附加环境，但智能体要等初始化完成才能访问工作区。

价格

预热免费，包括附加会话前的容器用量。未附加的预热沙箱五分钟后过期。

附加到会话后，按标准容器价格计费。

准备报告工作区

本例先安装 pandas 并加载小型 CSV，之后让智能体使用工作区计算合计。

使用 Python SDK 3.28.0、Node.js SDK 7.32.0、Java SDK 4.80.0、Ruby SDK 0.103.0 或更高版本。

1. 创建环境

向 POST /v1/agents/environments 发送工作区配置：

来源示例 1（javascript）：

// [中文] 示例 1：1. 创建环境。
// [中文] 在会话外创建预热环境，保存环境 ID；等待 ready 后附加，或让会话等待初始化。
import OpenAI from "openai";

const client = new OpenAI();
const environment = await client.beta.agents.environments.create({
  environment: {
    type: "openai_hosted",
    packages: { python: ["pandas==2.2.3"] },
    files: [
      {
        type: "inline",
        path: "/workspace/amounts.csv",
        data: "YW1vdW50CjEwCjIwCjMwCg==",
      },
    ],
    setup_commands: [
      {
        command: 'python -c "import pandas; print(pandas.__version__)"',
        cwd: "/workspace",
      },
    ],
  },
});
const environmentId = environment.id;
console.log(environmentId);

来源示例 2（python）：

## [中文] 示例 2：1. 创建环境。
## [中文] 在会话外创建预热环境，保存环境 ID；等待 ready 后附加，或让会话等待初始化。
from openai import OpenAI

client = OpenAI()
environment = client.beta.agents.environments.create(
    environment={
        "type": "openai_hosted",
        "packages": {"python": ["pandas==2.2.3"]},
        "files": [
            {
                "type": "inline",
                "path": "/workspace/amounts.csv",
                "data": "YW1vdW50CjEwCjIwCjMwCg==",
            }
        ],
        "setup_commands": [
            {
                "command": 'python -c "import pandas; print(pandas.__version__)"',
                "cwd": "/workspace",
            }
        ],
    }
)
environment_id = environment.id
print(environment_id)

来源示例 3（java）：

// [中文] 示例 3：1. 创建环境。
// [中文] 在会话外创建预热环境，保存环境 ID；等待 ready 后附加，或让会话等待初始化。
import com.openai.client.okhttp.OpenAIOkHttpClient;

import com.openai.models.beta.agents.HostedEnvironmentFileParam;
import com.openai.models.beta.agents.SetupCommandParam;
import com.openai.models.beta.agents.environments.EnvironmentCreateParams;

var client = OpenAIOkHttpClient.fromEnv();
var environment =
    client
        .beta()
        .agents()
        .environments()
        .create(
            EnvironmentCreateParams.builder()
                .environment(
                    EnvironmentCreateParams.Environment.builder()
                        .packages(
                            EnvironmentCreateParams.Environment.Packages.builder()
                                .addPython("pandas==2.2.3")
                                .build())
                        .addFile(
                            HostedEnvironmentFileParam.Inline.builder()
                                .path("/workspace/amounts.csv")
                                .data("YW1vdW50CjEwCjIwCjMwCg==")
                                .build())
                        .addSetupCommand(
                            SetupCommandParam.builder()
                                .command(
                                    "python -c \"import pandas; print(pandas.__version__)\"")
                                .cwd("/workspace")
                                .build())
                        .build())
                .build());
String environmentId = environment.id();
System.out.println(environmentId);

来源示例 4（ruby）：

## [中文] 示例 4：1. 创建环境。
## [中文] 在会话外创建预热环境，保存环境 ID；等待 ready 后附加，或让会话等待初始化。
require "openai"

client = OpenAI::Client.new
environment = client.beta.agents.environments.create(
  environment: {
    type: :openai_hosted,
    packages: { python: ["pandas==2.2.3"] },
    files: [
      {
        type: :inline,
        path: "/workspace/amounts.csv",
        data: "YW1vdW50CjEwCjIwCjMwCg=="
      }
    ],
    setup_commands: [
      {
        command: 'python -c "import pandas; print(pandas.__version__)"',
        cwd: "/workspace"
      }
    ]
  }
)
environment_id = environment.id
puts environment_id

来源示例 5（bash）：

## [中文] 示例 5：1. 创建环境。
## [中文] 本段涉及的请求或服务地址：https://api.openai.com/v1/agents/environments；示例占位地址需替换为实际资源。
curl https://api.openai.com/v1/agents/environments \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": {
      "type": "openai_hosted",
      "packages": {
        "python": ["pandas==2.2.3"]
      },
      "files": [
        {
          "type": "inline",
          "path": "/workspace/amounts.csv",
          "data": "YW1vdW50CjEwCjIwCjMwCg=="
        }
      ],
      "setup_commands": [
        {
          "command": "python -c \"import pandas; print(pandas.__version__)\"",
          "cwd": "/workspace"
        }
      ]
    }
  }'

SDK 示例会保存返回的 id。cURL 用法将它保存到 shell 变量：

来源示例 6（bash）：

## [中文] 示例 6：1. 创建环境。
## [中文] 把创建环境返回的真实 ID 保存到 ENVIRONMENT_ID；此赋值本身不创建或连接环境。
ENVIRONMENT_ID="ccarenv_REPLACE_WITH_RETURNED_ID"

创建独立环境时，environment.type 使用 openai_hosted。

2. 检查就绪状态

使用第一步保存的 ID 读取环境：

来源示例 7（javascript）：

// [中文] 示例 7：2. 检查就绪状态。
// [中文] 读取预热环境当前状态；ready 表示初始化完成，不代表已有智能体连接。
const current = await client.beta.agents.environments.retrieve(environmentId);
console.log(current.status);

来源示例 8（python）：

## [中文] 示例 8：2. 检查就绪状态。
## [中文] 读取预热环境当前状态；ready 表示初始化完成，不代表已有智能体连接。
current = client.beta.agents.environments.retrieve(environment_id)
print(current.status)

来源示例 9（go）：

// [中文] 示例 9：2. 检查就绪状态。
// [中文] 读取指定环境的当前状态，等待 ready 后再附加；非就绪状态按本节排障。
current, err := client.Beta.Agents.Environments.Get(context.Background(), environmentID)
if err != nil {
    panic(err)
}
fmt.Println(current.Status)

来源示例 10（java）：

// [中文] 示例 10：2. 检查就绪状态。
// [中文] 读取预热环境当前状态；ready 表示初始化完成，不代表已有智能体连接。
var current = client.beta().agents().environments().retrieve(environmentId);
System.out.println(current.status());

来源示例 11（ruby）：

## [中文] 示例 11：2. 检查就绪状态。
## [中文] 读取预热环境当前状态；ready 表示初始化完成，不代表已有智能体连接。
current = client.beta.agents.environments.retrieve(environment_id)
puts current.status

来源示例 12（bash）：

## [中文] 示例 12：2. 检查就绪状态。
## [中文] 本段涉及的请求或服务地址：https://api.openai.com/v1/agents/environments/$ENVIRONMENT_ID；示例占位地址需替换为实际资源。
curl \
  "https://api.openai.com/v1/agents/environments/$ENVIRONMENT_ID" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

初始化期间状态为 pending，变成 ready 后，工作区准备完成，可以附加到会话。就绪不代表智能体已连接：没有会话时，环境也可能为 ready。

不想轮询，可让项目 webhook 订阅 agent.environment.ready 与 agent.environment.failed。

若在初始化完成前附加环境，使用会话的 agent.session.environment.ready 或 agent.session.environment.failed 跟踪初始化。可读取以 "stream": true 创建会话的响应流，或打开 GET /v1/agents/sessions/{session_id}/events，见会话事件。

3. 附加环境并运行任务

创建会话时提供已保存环境 ID、智能体及第一条输入：

来源示例 13（javascript）：

程序文字说明30：用pandas读取/workspace/amounts.csv，计算amount列总和并报告。

// [中文] 示例 13：3. 附加环境并运行任务。
// [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
const stream = await client.beta.agents.sessions.create({
  agent: { model: "gpt-6-astra" },
  environment: { type: "openai_hosted", environment_id: environmentId },
  input:
    "Use pandas to read /workspace/amounts.csv, calculate the sum of the amount column, and report the total.",
  stream: true,
});
try {
  for await (const event of stream) {
    console.log(event);
  }
} finally {
  stream.controller.abort();
}

来源示例 14（python）：

沿用程序文字说明30。

## [中文] 示例 14：3. 附加环境并运行任务。
## [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
stream = client.beta.agents.sessions.create(
    agent={"model": "gpt-6-astra"},
    environment={"type": "openai_hosted", "environment_id": environment_id},
    input="Use pandas to read /workspace/amounts.csv, calculate the sum of the amount column, and report the total.",
    stream=True,
)
with stream:
    for event in stream:
        print(event.model_dump_json())

来源示例 15（java）：

沿用程序文字说明30。

// [中文] 示例 15：3. 附加环境并运行任务。
// [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
import com.openai.models.beta.agents.EnvironmentParam;

import com.openai.models.beta.agents.sessions.SessionCreateParams;

var params =
    SessionCreateParams.builder()
        .agent(SessionCreateParams.Agent.builder().model("gpt-6-astra").build())
        .environment(
            EnvironmentParam.OpenAIHosted.builder().environmentId(environmentId).build())
        .input(
            "Use pandas to read /workspace/amounts.csv, calculate the sum of the amount column, and report the total.")
        .build();
try (var stream = client.beta().agents().sessions().createStreaming(params)) {
  stream.stream().forEach(System.out::println);
}

来源示例 16（ruby）：

沿用程序文字说明30。

## [中文] 示例 16：3. 附加环境并运行任务。
## [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
stream = client.beta.agents.sessions.create_streaming(
  agent: { model: "gpt-6-astra" },
  environment: {
    type: :openai_hosted,
    environment_id: environment_id
  },
  input: "Use pandas to read /workspace/amounts.csv, calculate the sum of the amount column, and report the total."
)
begin
  stream.each { |event| puts event.to_json }
ensure
  stream.close
end

来源示例 17（bash）：

沿用程序文字说明30。

## [中文] 示例 17：3. 附加环境并运行任务。
## [中文] 本段涉及的请求或服务地址：https://api.openai.com/v1/agents/sessions；示例占位地址需替换为实际资源。
curl --no-buffer https://api.openai.com/v1/agents/sessions \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
{
  "agent": {
    "model": "gpt-6-astra"
  },
  "environment": {
    "type": "openai_hosted",
    "environment_id": "$ENVIRONMENT_ID"
  },
  "input": "Use pandas to read /workspace/amounts.csv, calculate the sum of the amount column, and report the total.",
  "stream": true
}
EOF

常见错误

根据错误消息和当前环境状态选择恢复方式。新创建的共享环境最多附加128个会话，复用时会共享工作区；较早环境可能仍采用单会话生命周期。

使用已保存的环境模板

多个任务需要相同软件包和初始化时，可先保存环境模板，再在创建各预热环境时提供模板 ID：

来源示例 18（javascript）：

// [中文] 示例 18：使用已保存的环境模板。
// [中文] 在会话外创建预热环境，保存环境 ID；等待 ready 后附加，或让会话等待初始化。
import OpenAI from "openai";

const client = new OpenAI();
const environment = await client.beta.agents.environments.create({
  environment: {
    type: "openai_hosted",
    environment_template_id: "envtmpl_REPLACE_WITH_TEMPLATE_ID",
  },
});
console.log(environment.id);

来源示例 19（python）：

## [中文] 示例 19：使用已保存的环境模板。
## [中文] 在会话外创建预热环境，保存环境 ID；等待 ready 后附加，或让会话等待初始化。
from openai import OpenAI

client = OpenAI()
environment = client.beta.agents.environments.create(
    environment={
        "type": "openai_hosted",
        "environment_template_id": "envtmpl_REPLACE_WITH_TEMPLATE_ID",
    }
)
print(environment.id)

来源示例 20（java）：

// [中文] 示例 20：使用已保存的环境模板。
// [中文] 在会话外创建预热环境，保存环境 ID；等待 ready 后附加，或让会话等待初始化。
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.environments.EnvironmentCreateParams;

var client = OpenAIOkHttpClient.fromEnv();
var environment =
    client
        .beta()
        .agents()
        .environments()
        .create(
            EnvironmentCreateParams.builder()
                .environment(
                    EnvironmentCreateParams.Environment.builder()
                        .environmentTemplateId("envtmpl_REPLACE_WITH_TEMPLATE_ID")
                        .build())
                .build());
System.out.println(environment.id());

来源示例 21（ruby）：

## [中文] 示例 21：使用已保存的环境模板。
## [中文] 在会话外创建预热环境，保存环境 ID；等待 ready 后附加，或让会话等待初始化。
require "openai"

client = OpenAI::Client.new
environment = client.beta.agents.environments.create(
  environment: {
    type: :openai_hosted,
    environment_template_id: "envtmpl_REPLACE_WITH_TEMPLATE_ID"
  }
)
puts environment.id

来源示例 22（bash）：

## [中文] 示例 22：使用已保存的环境模板。
## [中文] 本段涉及的请求或服务地址：https://api.openai.com/v1/agents/environments；示例占位地址需替换为实际资源。
curl https://api.openai.com/v1/agents/environments \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "environment": {
    "type": "openai_hosted",
    "environment_template_id": "envtmpl_REPLACE_WITH_TEMPLATE_ID"
  }
}'

为计算机使用预热沙箱

浏览器任务可在会话开始前准备托管浏览器和虚拟显示器。创建环境时包含 desktop.enabled：

来源示例 23（javascript）：

// [中文] 示例 23：为计算机使用预热沙箱。
// [中文] 在会话外创建预热环境，保存环境 ID；等待 ready 后附加，或让会话等待初始化。
import OpenAI from "openai";

const client = new OpenAI();
const environment = await client.beta.agents.environments.create({
  environment: {
    type: "openai_hosted",
    desktop: { enabled: true },
  },
});
console.log(environment.id);

来源示例 24（python）：

## [中文] 示例 24：为计算机使用预热沙箱。
## [中文] 在会话外创建预热环境，保存环境 ID；等待 ready 后附加，或让会话等待初始化。
from openai import OpenAI

client = OpenAI()
environment = client.beta.agents.environments.create(
    environment={
        "type": "openai_hosted",
        "desktop": {"enabled": True},
    }
)
print(environment.id)

来源示例 25（java）：

// [中文] 示例 25：为计算机使用预热沙箱。
// [中文] 在会话外创建预热环境，保存环境 ID；等待 ready 后附加，或让会话等待初始化。
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.environments.EnvironmentCreateParams;

var client = OpenAIOkHttpClient.fromEnv();
var environment =
    client
        .beta()
        .agents()
        .environments()
        .create(
            EnvironmentCreateParams.builder()
                .environment(
                    EnvironmentCreateParams.Environment.builder()
                        .desktop(
                            EnvironmentCreateParams.Environment.Desktop.builder()
                                .enabled(true)
                                .build())
                        .build())
                .build());
System.out.println(environment.id());

来源示例 26（ruby）：

## [中文] 示例 26：为计算机使用预热沙箱。
## [中文] 在会话外创建预热环境，保存环境 ID；等待 ready 后附加，或让会话等待初始化。
require "openai"

client = OpenAI::Client.new
environment = client.beta.agents.environments.create(
  environment: {
    type: :openai_hosted,
    desktop: { enabled: true }
  }
)
puts environment.id

来源示例 27（bash）：

## [中文] 示例 27：为计算机使用预热沙箱。
## [中文] 本段涉及的请求或服务地址：https://api.openai.com/v1/agents/environments；示例占位地址需替换为实际资源。
curl https://api.openai.com/v1/agents/environments \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "environment": {
    "type": "openai_hosted",
    "desktop": {
      "enabled": true
    }
  }
}'

创建会话时附加该环境 ID，并为智能体提供 computer_use 工具。会话使用环境已保存的桌面配置。工具配置和浏览器源批准见计算机使用。

列出环境

GET /v1/agents/environments 返回当前组织、项目中，由当前身份创建的活动环境：

来源示例 28（javascript）：

// [中文] 示例 28：列出环境。
// [中文] 列出当前身份创建的活动环境，本段只显示返回的一页；更多结果需要分页。
const environments = await client.beta.agents.environments.list({
  limit: 20,
  order: "desc",
});
console.log(environments.data);

来源示例 29（python）：

## [中文] 示例 29：列出环境。
## [中文] 列出当前身份创建的活动环境，本段只显示返回的一页；更多结果需要分页。
environments = client.beta.agents.environments.list(limit=20, order="desc")
for item in environments.data:
    print(item.model_dump_json())

来源示例 30（java）：

// [中文] 示例 30：列出环境。
// [中文] 列出当前身份创建的活动环境，本段只显示返回的一页；更多结果需要分页。
import com.openai.models.beta.agents.environments.EnvironmentListParams;

var environments =
    client
        .beta()
        .agents()
        .environments()
        .list(
            EnvironmentListParams.builder()
                .limit(20L)
                .order(EnvironmentListParams.Order.DESC)
                .build());
System.out.println(environments.items());

来源示例 31（ruby）：

## [中文] 示例 31：列出环境。
## [中文] 列出当前身份创建的活动环境，本段只显示返回的一页；更多结果需要分页。
environments = client.beta.agents.environments.list(
  limit: 20,
  order: :desc
)
(environments.data || []).each { |item| puts item.to_json }

来源示例 32（bash）：

## [中文] 示例 32：列出环境。
## [中文] 本段涉及的请求或服务地址：https://api.openai.com/v1/agents/environments?limit=20&order=desc；示例占位地址需替换为实际资源。
curl \
  "https://api.openai.com/v1/agents/environments?limit=20&order=desc" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

列表包含附加会话前后的环境，状态可能为 pending、ready、connected、disconnected 或 suspended；不含失败、过期、删除和终止的环境。列表中的环境可能已附加一个或多个会话。

默认按最新优先排列。has_more 为真时，将上一响应 last_id 作为 after 取下一页。limit 为1—100，默认20；order 为 asc 或 desc。

生命周期与复用

• 多会话共享一个环境：创建各会话时提供相同 environment_id，即可共享文件、进程、已安装包和环境配置，各会话仍有独立对话历史。工作区变更对其他已附加会话可见；需隔离任务时使用不同环境。每环境最多128个会话，此行为适用于新创建独立环境，旧环境保留原生命周期。
• 未用环境会过期：始终未附加的环境五分钟后过期，因此应接近预计任务开始时间再预热。
• 保持创建身份一致：读取、列出和附加操作要求相同组织、项目及认证身份。同一身份的不同密钥，包括轮换后的密钥，可访问同一环境。
• 共享环境在不活动后过期：第一次附加启动20分钟空闲期限，任一已附加会话或环境文件 API 的活动会延长期限，待处理工作和活动轮次会阻止空闲过期。删除会话只移除该会话，不删除共享工作区；最后一个会话删除后，仍可在空闲截止前重新附加。API 没有独立环境删除端点。

安全重试创建请求

创建环境时可发送 Idempotency-Key 请求头。请求超时或响应丢失，用相同键、相同请求体重试，避免重复创建环境。

原环境仍可用时，已完成的重试返回其 ID 和当前状态。创建仍在进行、结果不确定、环境已不可用或参数不一致时，已保留键可能返回 409，不会创建替代环境。键保留24小时，之后复用同一键可能创建新环境；有意创建另一个环境时使用新键。