通过环境预热,您可以在创建智能体会话前创建由 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
14ctx := context.Background()
client := openai.NewClient()
environment, err := client.Beta.Agents.Environments.New(ctx, openai.BetaAgentEnvironmentNewParams{
Environment: openai.BetaAgentEnvironmentNewParamsEnvironment{
Packages: openai.BetaAgentEnvironmentNewParamsEnvironmentPackages{Python: []string{"pandas==2.2.3"}},
Files: []openai.HostedEnvironmentFileParamUnion{{OfParamInline: &openai.HostedEnvironmentFileParamInline{Path: "/workspace/amounts.csv", Data: "YW1vdW50CjEwCjIwCjMwCg=="}}},
SetupCommands: []openai.SetupCommandParam{{Command: `python -c "import pandas; print(pandas.__version__)"`, Cwd: openai.String("/workspace")}},
},
})
if err != nil {
panic(err)
}
environmentID := environment.ID
fmt.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
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,请将其保存到 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(ctx, 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
15
16
17
18
19
20
21
22
23stream := client.Beta.Agents.Sessions.NewStreaming(ctx, openai.BetaAgentSessionNewParams{
Agent: openai.BetaAgentSessionNewParamsAgent{Model: openai.String("gpt-6-astra")},
Environment: openai.EnvironmentParamUnion{OfParamOpenAIHosted: &openai.EnvironmentParamOpenAIHosted{EnvironmentID: openai.String(environmentID)}},
Input: openai.BetaAgentSessionNewParamsInputUnion{OfString: openai.String("Use pandas to read /workspace/amounts.csv, calculate the sum of the amount column, and report the total.")},
})
defer stream.Close()
completed := false
for stream.Next() {
event := stream.Current()
fmt.Println(event.RawJSON())
switch event.Type {
case "agent.session.turn.failed", "error":
panic("Agent turn failed")
case "agent.session.turn.completed":
completed = true
}
}
if err := stream.Err(); err != nil {
panic(err)
}
if !completed {
panic("Stream ended before the turn completed")
}
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
9environment, err := client.Beta.Agents.Environments.New(context.Background(), openai.BetaAgentEnvironmentNewParams{
Environment: openai.BetaAgentEnvironmentNewParamsEnvironment{
EnvironmentTemplateID: openai.String("envtmpl_REPLACE_WITH_TEMPLATE_ID"),
},
})
if err != nil {
panic(err)
}
fmt.Println(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
9environment, err := client.Beta.Agents.Environments.New(context.Background(), openai.BetaAgentEnvironmentNewParams{
Environment: openai.BetaAgentEnvironmentNewParamsEnvironment{
Desktop: openai.BetaAgentEnvironmentNewParamsEnvironmentDesktop{Enabled: openai.Bool(true)},
},
})
if err != nil {
panic(err)
}
fmt.Println(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
7environments, err := client.Beta.Agents.Environments.List(ctx, openai.BetaAgentEnvironmentListParams{Limit: openai.Int(20), Order: "desc"})
if err != nil {
panic(err)
}
for _, item := range environments.Data {
fmt.Println(item.ID)
}
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 小时,之后使用相同的幂等键可能会创建新环境。如果您确实要创建新环境,请使用新的幂等键。