OpenAI 托管的沙盒为您的智能体提供一个配备 Python、Node.js
和命令行工具的 Linux 工作空间。OpenAI 负责配置并连接沙盒;您的应用负责提供任务
并获取结果。如果您需要使用自己的镜像、计算资源或专用网络,
请选择自托管沙盒。
将 environment.type 设为 openai_hosted,并且仅添加工作负载
所需的设置。工作目录为 /workspace。
packages:通过 python、system 或 npm 列表安装 Python 包、系统包或全局 npm 包。根据需要固定版本,例如 pandas==2.2.3。
setup_commands:在智能体启动前按顺序运行 Shell 命令,例如 [{ "command": "mkdir -p reports" }]。每条命令都可以单独设置可选的 cwd,默认值为 /workspace。
files:通过 Files API ID 或内联 base64 内容提供输入文件。
env:设置值为字符串的环境变量。运行时保留的名称不予接受,包括 PATH、CODEX_* 和 OPENAI_API_KEY。
skills、plugins、capability_directories:添加技能和插件。
environment_template_id:在不同会话之间复用已保存的配置。省略的设置会继承模板中的值;覆盖网络设置时不能放宽模板的策略。
系统会在运行设置命令前准备好软件包和输入文件。如果设置命令的退出状态非零,智能体将无法启动。使用设置命令检查所需的依赖项或文件。模板保存的是配置,而非正在运行的工作空间。
network.access | 行为 |
|---|
enabled | 允许出站访问。除非继承了模板策略,否则这是默认行为。 |
disabled | 阻止出站访问。 |
restricted | 仅允许访问 allowed_domains 中列出的主机。 |
受限模式接受 1–100 个精确主机名,例如 api.example.com。
不要包含通配符、协议、路径或端口。子域名和重定向
目标需要各自单独的条目。托管的 stdio MCP 服务器目前要求
将访问权限设为 enabled;请参阅 stdio MCP 要求。
创建会话的响应表示设置已开始。使用会话的 environment.id
调用 GET /v1/agents/environments/{environment_id} 获取状态:
provisioning 表示设置正在进行;connected 表示设置成功。
如果状态为 failed,请读取 agent.session.environment.failed 事件中的 environment.error。
请等到状态变为 connected 后再添加或列出实时文件。
每个会话都有独立的工作空间。只要沙盒仍然存在,
文件就会跨轮次保留。每轮完成时,/workspace/outputs 下的文件会
作为不可变产物发布;即使沙盒
过期,这些副本仍可下载。
有关上传、
路径规则、实时文件操作、下载和限制,请参阅文件和产物。
删除会话前,请保存您需要的输出。
已连接的沙盒会收到保活信号,在轮次之间也不例外。如果活动和保活信号均停止一小时,沙盒可能会被删除。此超时时间无法配置。
使用完毕后,删除会话以请求清理沙盒。如果设置或执行尚在结束过程中,
删除操作返回 409,请等待后重试,并限制
重试次数。关闭事件流不会取消任务。
OpenAI 托管的沙盒按标准容器费率计费。
模型用量按所选模型的 API 费率单独计费。
向智能体提供一个包含 10、20 和 30 的 CSV 文件。智能体会运行 Python 计算
总和,并写入 /workspace/outputs/summary.json。
按照
快速入门的前提条件,在应用终端中设置 OPENAI_API_KEY。
请将此密钥保留在沙盒之外。使用包含测试版 Agents API 的
OpenAI SDK 版本。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24import OpenAI from "openai";
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,
});
for await (const event of stream) {
console.log(event);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23from 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:
for event in stream:
print(event.model_dump_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
32package main
import (
"context"
"fmt"
"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()
for stream.Next() {
fmt.Println(stream.Current().RawJSON())
}
if err := stream.Err(); 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
34import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.EnvironmentParam;
import com.openai.models.beta.agents.HostedEnvironmentFileParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;
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)) {
stream.stream().forEach(System.out::println);
}
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25require "openai"
require "json"
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.each { |event| puts event.to_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 输入。代码会打印会话事件。
保存 agent.session.created 中的 session.id。在 agent.session.turn.completed 事件发生后,
列出产物,找到 summary.json,
并下载该文件。其内容应为:
{ "total": 60 }
一轮执行完成并不保证每个工具都执行成功。如果任务失败,或
事件流在完成前结束,请检查已保存的会话条目。
使用完毕后,请删除会话。
| 问题 | 检查事项 |
|---|
| 设置失败 | 检查环境失败事件,修复软件包、输入文件或设置命令中的错误,然后再创建新会话。 |
| 沙盒请求被阻止 | 检查 network 以及通过重定向访问的所有主机。 |
| 实时文件操作失败 | 确认沙盒状态为 connected。如果沙盒已过期,请创建新会话并重新提供输入。 |
状态或文件列表请求返回 5xx | 逐步延长重试间隔,并设置重试截止时间。如果错误持续出现,请保留请求 ID。 |