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 版本包含 Beta 版 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。 |