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:
123456{
"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。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35import OpenAI from "openai";
import { agentFileDestination } from "openai/helpers/beta/agents/filesystem";
const client = new OpenAI();
const stream = await 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,
});
stream.withResultCollection();
try {
for await (const event of stream) {
console.log(event);
}
const result = await stream.finalResult();
await client.beta.agents.sessions.artifacts.forResult(result).download({
path: "/workspace/outputs/summary.json",
to: agentFileDestination("summary.json"),
});
} finally {
stream.controller.abort();
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28from 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"
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47package main
import (
"context"
"fmt"
"os"
"github.com/openai/openai-go/v3"
)
func main() {
ctx := context.Background()
client := openai.NewClient()
stream := client.Beta.Agents.Sessions.NewStreaming(ctx, openai.BetaAgentSessionNewParams{
Agent: openai.BetaAgentSessionNewParamsAgent{Model: openai.String("gpt-6-astra")},
Environment: openai.EnvironmentParamUnion{OfParamOpenAIHosted: &openai.EnvironmentParamOpenAIHosted{
Network: openai.EnvironmentParamOpenAIHostedNetwork{Access: "disabled"},
Files: []openai.HostedEnvironmentFileParamUnion{{OfParamInline: &openai.HostedEnvironmentFileParamInline{
Path: "/workspace/amounts.csv",
Data: "YW1vdW50CjEwCjIwCjMwCg==",
}}},
}},
Input: openai.BetaAgentSessionNewParamsInputUnion{OfString: openai.String("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.")},
})
defer stream.Close()
openai.BetaAgentSessionWithResultCollection(stream)
for stream.Next() {
fmt.Println(stream.Current().RawJSON())
}
result, err := openai.BetaAgentSessionFinalResult(stream)
if err != nil {
panic(err)
}
destination, err := os.Create("summary.json")
if err != nil {
panic(err)
}
defer destination.Close()
_, err = client.Beta.Agents.Sessions.Artifacts.ForResult(result).Download(ctx, "/workspace/outputs/summary.json", destination)
if err != nil {
panic(err)
}
if err := destination.Close(); err != nil {
panic(err)
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.helpers.beta.agents.AgentArtifactDownloads;
import com.openai.models.beta.agents.EnvironmentParam;
import com.openai.models.beta.agents.HostedEnvironmentFileParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;
import com.openai.services.beta.agents.AgentTurnResults;
import java.nio.file.Path;
public class HostedReport {
public static void main(String[] args) throws Exception {
var client = OpenAIOkHttpClient.fromEnv();
var params =
SessionCreateParams.builder()
.agent(SessionCreateParams.Agent.builder().model("gpt-6-astra").build())
.environment(
EnvironmentParam.OpenAIHosted.builder()
.network(
EnvironmentParam.OpenAIHosted.Network.builder()
.access(EnvironmentParam.OpenAIHosted.Network.Access.DISABLED)
.build())
.addFile(
HostedEnvironmentFileParam.Inline.builder()
.path("/workspace/amounts.csv")
.data("YW1vdW50CjEwCjIwCjMwCg==")
.build())
.build())
.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.")
.build();
try (var stream = client.beta().agents().sessions().createStreaming(params)) {
AgentTurnResults.withResultCollection(stream);
stream.stream().forEach(System.out::println);
var result = AgentTurnResults.getFinalResult(stream);
AgentArtifactDownloads.forResult(client.beta().agents().sessions().artifacts(), result)
.download("/workspace/outputs/summary.json", Path.of("summary.json"));
}
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33require "openai"
require "json"
require "pathname"
client = OpenAI::Client.new
stream = client.beta.agents.sessions.create_streaming(
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."
)
begin
stream.with_result_collection
stream.each { |event| puts event.to_json }
result = stream.get_final_result
puts result.output_text
client.beta.agents.sessions.artifacts.for_result(result).download(
path: "/workspace/outputs/summary.json",
to: Pathname("summary.json")
)
ensure
stream.close
end
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24curl --no-buffer --fail-with-body https://api.openai.com/v1/agents/sessions \
-H "OpenAI-Beta: agents=v1" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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
}'
files 中的 base64 编码值包含 CSV 输入数据。代码会打印会话事件。请保存 session.id,其值来自 agent.session.created 事件。收到 agent.session.turn.completed 事件后,列出产物,找到 summary.json 并下载该文件。文件内容应如下所示:
{ "total": 60 }
一轮交互完成并不保证每次工具调用都成功。如果任务失败,或事件流在本轮交互完成前结束,请检查已保存的会话条目。使用完毕后,请删除会话。
| 问题 |
排查方法 |
| 初始化失败 |
查看环境初始化失败事件,修复软件包、输入文件或初始化命令中的错误,再创建新会话。 |
| 沙盒发出的请求被阻止 |
检查 network 设置,以及请求经重定向后访问的所有主机。 |
| 沙盒内的文件操作失败 |
确认沙盒状态为 connected。如果沙盒已过期,请创建新会话并重新提供输入文件。 |
查询状态或列出文件的请求返回 5xx |
逐步延长重试间隔,并设置重试截止时间。如果错误持续出现,请保留请求 ID。 |