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。
請將此金鑰保留在沙盒外。請使用包含 Beta 版 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。 |