透過環境預熱,你可以在建立智慧體工作階段前,先建立由 OpenAI 代管的沙盒、安裝套件、載入檔案並執行設定指令。收到任務時,將準備好的環境附加到工作階段,即可啟動智慧體。
如果低延遲是核心需求,可以使用預熱功能。例如,報表應用程式可以在使用者選擇資料集時準備好所需的 Python 套件,程式開發工作流程也可以在使用者撰寫請求時先準備工作區。提早開始設定,可以縮短使用者的等待時間。
環境是智慧體執行工具的工作區。工作階段則保存智慧體的設定和對話。透過預熱,你可以先單獨準備工作區,等到需要工作階段時再附加環境。
整個流程分為三個步驟:
- 建立環境。 提供任務所需的套件、檔案和設定指令。
- 等待環境就緒。 重複查詢環境,直到狀態變為
ready,也可以使用 webhook 接收通知。
- 啟動工作階段。 建立工作階段時傳入環境 ID。
你也可以在設定仍在進行時附加環境。智慧體要等到設定完成後才能存取工作區。
預熱沙盒免費,附加前的容器用量也免費。預熱後尚未附加的沙盒會在 5 分鐘後到期。
將預熱的沙盒附加到工作階段後,即按標準容器費率計費。
這個範例會在啟動智慧體前安裝 pandas 並載入一個小型 CSV 檔案。智慧體接著會在準備好的工作區中計算總和。
本指南所需的最低 SDK 版本分別為 Python SDK 3.28.0、Node.js SDK 7.32.0、Java SDK 4.80.0 或 Ruby SDK 0.103.0。
將工作區設定傳送至 POST /v1/agents/environments:
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 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);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24from 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)
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 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);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24require "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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25curl 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,請將該 ID 存入 shell 變數:
ENVIRONMENT_ID="ccarenv_REPLACE_WITH_RETURNED_ID"
建立獨立環境時,請將 environment.type 設為 openai_hosted。
使用步驟 1 儲存的 ID 查詢環境:
const current = await client.beta.agents.environments.retrieve(environmentId);
console.log(current.status);
current = client.beta.agents.environments.retrieve(environment_id)
print(current.status)
current, err := client.Beta.Agents.Environments.Get(context.Background(), environmentID)
if err != nil {
panic(err)
}
fmt.Println(current.Status)
var current = client.beta().agents().environments().retrieve(environmentId);
System.out.println(current.status());
current = client.beta.agents.environments.retrieve(environment_id)
puts current.status
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 開啟事件串流。如需串流的詳細資訊,請參閱工作階段事件。
建立工作階段時,請提供先前儲存的環境 ID、智慧體及其第一筆輸入:
1
2
3
4
5
6
7
8
9
10
11
12
13
14const 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();
}
1
2
3
4
5
6
7
8
9stream = 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())
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15import 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);
}
1
2
3
4
5
6
7
8
9
10
11
12
13stream = 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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17curl --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。未使用的環境會在 5 分鐘後到期。使用已到期環境的 ID 重試也無法還原其工作區。 |
404:找不到環境。 |
確認環境 ID 是否正確,並使用與建立環境時相同的組織、專案和身分。如果環境已到期或已無法使用,請建立新環境。 |
409:共用環境已達工作階段數量上限。 |
一個共用環境最多可附加到 128 個工作階段。請重複使用現有的工作階段,或為額外的工作階段建立另一個環境。 |
如果多個任務需要相同的套件和設定,可以將環境設定儲存為範本,之後每次建立預熱環境時傳入範本 ID 即可:
1
2
3
4
5
6
7
8
9
10import 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);
1
2
3
4
5
6
7
8
9
10from 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)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import 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());
1
2
3
4
5
6
7
8
9
10require "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
1
2
3
4
5
6
7
8
9
10curl 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 設定:
1
2
3
4
5
6
7
8
9
10import 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);
1
2
3
4
5
6
7
8
9
10from openai import OpenAI
client = OpenAI()
environment = client.beta.agents.environments.create(
environment={
"type": "openai_hosted",
"desktop": {"enabled": True},
}
)
print(environment.id)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20import 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());
1
2
3
4
5
6
7
8
9
10require "openai"
client = OpenAI::Client.new
environment = client.beta.agents.environments.create(
environment: {
type: :openai_hosted,
desktop: { enabled: true }
}
)
puts environment.id
1
2
3
4
5
6
7
8
9
10
11
12curl 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 查詢以你的身分在目前組織和專案中建立且仍有效的環境:
1
2
3
4
5const environments = await client.beta.agents.environments.list({
limit: 20,
order: "desc",
});
console.log(environments.data);
1
2
3environments = client.beta.agents.environments.list(limit=20, order="desc")
for item in environments.data:
print(item.model_dump_json())
1
2
3
4
5
6
7
8
9
10
11
12
13import 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());
1
2
3
4
5environments = client.beta.agents.environments.list(
limit: 20,
order: :desc
)
(environments.data || []).each { |item| puts item.to_json }
1
2
3
4curl \
"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 為真,請將 after 設為上一個回應中的 last_id,以取得下一頁結果。limit 可設為 1 到 100,預設為 20。order 可設為 asc 或 desc。
- 多個工作階段可以共用同一個環境。 建立各個工作階段時,請傳入相同的
environment_id。這些工作階段會共用執行中的工作區,包括檔案、程序、已安裝的套件和環境設定。每個工作階段各自保留對話記錄。其他已附加的工作階段都能看到工作區的變更,因此如果任務需要各自獨立的工作區,請分別建立環境。一個共用環境最多可附加到 128 個工作階段。此行為適用於新建立的獨立環境,較早建立的環境則保留原有的生命週期。
- 未使用的環境會到期。 如果環境一直未附加到工作階段,就會在 5 分鐘後到期。請在接近任務預計開始的時間再預熱環境。
- 使用與建立環境時相同的身分。 查詢、列出或附加環境時,必須使用與建立環境時相同的組織、專案和已驗證身分。同一身分的不同 API 金鑰都能存取相同的環境,輪替金鑰後也一樣。
- 共用環境閒置後會停止運算。 首次將環境附加到工作階段時,系統會開始計算 20 分鐘的閒置期限。任何已附加工作階段中的活動,或透過環境檔案 API 進行的操作,都會延長期限。只要還有待處理的工作或仍在進行的回合,系統就不會因閒置而停止運算。因閒置而停止運算時,環境可能會進入
suspended 狀態,而非直接到期。此時系統會保留檢查點 7 天。暫停期間,運算會停止,但共用工作區仍會保留。刪除工作階段只會將該工作階段從環境中移除,共用工作區及其檢查點都會保留。API 未提供可單獨刪除環境的端點。
建立環境時,可以在請求中加入 Idempotency-Key 標頭。如果請求逾時或回應遺失,請使用相同的冪等鍵和相同的請求本文重試,以免多建立一個環境。
只要原本的環境仍可使用,重試請求完成時就會回傳該環境的 ID 和目前狀態。在冪等鍵保留期間,如果環境仍在建立中、建立結果尚不確定、環境已無法使用,或重試的參數與原請求不同,使用該鍵重試可能會收到 409。發生這些衝突時,系統不會建立替代環境。冪等鍵會保留 24 小時,超過這段時間後,使用相同的鍵可能會建立新環境。如果你的目的是建立新環境,請使用新的冪等鍵。