如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

预热沙盒

在启动智能体会话前准备好工作空间。

通过环境预热,您可以在创建智能体会话前创建由 OpenAI 托管的沙盒,安装软件包、加载文件并运行初始化指令。收到任务后,将准备好的环境附加到会话并启动智能体。

如果低延迟是核心要求,可以使用预热。例如,报表应用可以在用户选择数据集时准备所需的 Python 依赖项,编码工作流也可以在用户编写请求时准备工作空间。提前开始初始化可以缩短用户等待的时间。

工作原理

环境是智能体运行工具的工作空间。会话保存智能体配置和对话。通过预热,您可以单独准备工作空间,等到需要会话时再将环境附加到会话。

整个流程分为三步:

  1. 创建环境。 提供任务所需的软件包、文件和初始化指令。
  2. 等待环境就绪。 反复查询环境,直到其状态变为 ready,也可以通过 webhook 接收通知。
  3. 启动会话。 创建会话时传入环境 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。

1. 创建环境

将工作空间配置发送到 POST /v1/agents/environments:

from 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)

SDK 示例会保存返回的 id,供后续步骤使用。如果您使用 cURL,请将其保存到 shell 变量中:

ENVIRONMENT_ID="ccarenv_REPLACE_WITH_RETURNED_ID"

创建独立环境时,将 environment.type 设为 openai_hosted。

2. 检查环境是否就绪

使用第 1 步中保存的 ID 查询环境:

current = client.beta.agents.environments.retrieve(environment_id)
print(current.status)

初始化期间,环境状态为 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 打开事件流。有关流式传输的详细信息,请参阅会话事件。

3. 附加环境并运行任务

创建会话时,传入已保存的环境 ID、智能体及其第一条输入:

stream = 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())

常见错误

根据错误消息和环境的当前状态选择处理方式。

新创建的共享环境最多可附加到 128 个会话。多个会话可以复用同一环境,共享其中的工作空间。较早创建的环境可能仍采用单会话生命周期。

错误或现象 处理方式
尝试附加已过期的环境。 创建新环境并使用新的 ID。未使用的环境会在 5 分钟后过期。使用已过期的 ID 重试无法恢复其工作空间。
404:找不到环境。 检查环境 ID,并确保使用的组织、项目和身份与创建环境时一致。如果环境已过期或不再可用,请创建新环境。
409:共享环境已达到会话数上限。 一个共享环境最多可附加到 128 个会话。请复用现有会话,或为更多会话创建另一个环境。

使用已保存的环境模板

如果多个任务需要相同的软件包和初始化步骤,请将环境配置保存为模板,然后在每次创建预热环境时传入模板 ID:

from 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)

为计算机使用预热沙盒

对于浏览器任务,请在会话开始前准备好托管浏览器和虚拟显示器。创建环境时,请在配置中包含 desktop.enabled:

from openai import OpenAI

client = OpenAI()
environment = client.beta.agents.environments.create(
    environment={
        "type": "openai_hosted",
        "desktop": {"enabled": True},
    }
)
print(environment.id)

创建会话时,使用已保存的环境 ID 附加环境,并为智能体提供 computer_use 工具。会话会使用环境中保存的桌面配置。有关工具配置和浏览器源审批的详细信息,请参阅计算机使用。

列出您的环境

使用 GET /v1/agents/environments 查找您以当前身份在当前组织和项目中创建的活跃环境:

environments = client.beta.agents.environments.list(limit=20, order="desc")
for item in environments.data:
    print(item.model_dump_json())

无论环境是否已附加到会话,只要其状态为 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 小时,之后使用相同的幂等键可能会创建新环境。如果您确实要创建新环境,请使用新的幂等键。