OpenAI SDK 出现托管 Agent 环境资源：prewarmed 预热创建、闲置挂起与过期事件

OpenAI 的两个官方 SDK 在三天里连发了四个版本,而它们讲的是同一个故事:一个可创建、可闲置挂起、可过期的托管 agent 环境资源,正在浮出水面。本文逐字引用 2026-10-12 当日抓取的 GitHub release notes 与 SDK tag 源码,类型层之外不断言。

1. 时间线:三天四个版本

版本号与时间来自 GitHub Releases API 当日抓取。上一篇文章《GPT-6 家族扩容:gpt-6-sol、gpt-6-luna、gpt-6.1-sol 进驻官方 SDK,dots 与 Intelligent UI 同窗亮相》核对时,python 最新版还是 v3.26.1、node 是 v7.31.0——这条环境 API 线是那之后三天内新增的。

2. 预热创建:environments.create

新资源挂在 client.beta.agents.environments 下。create 方法的文档原文:

Creates an OpenAI-hosted environment before creating a session. Requires access to the prewarming beta.

两个信息:其一,环境是先于会话创建的("before creating a session");其二,它走 prewarming beta 门控。vault_ids 参数的文档是 "The IDs of up to 10 vaults made available to an OpenAI-hosted environment"——至多 10 个 vault 可挂给环境。资源下另有 files 与 templates 两个子资源。

按 v3.29.0 tag 的 environment_create_params.py,environment 参数的形状是:

environment = {
    "type": "openai_hosted",           # 必填,当前唯一字面量
    "desktop": {"enabled": True},       # 可选
    "packages": {
        "npm": ["typescript@5"],
        "python": ["httpx"],
        "system": [],                   # 三组各自可选
    },
    "network": {
        "access": "restricted",         # enabled / disabled / restricted
        "allowed_domains": ["api.example.com"],
        "blocked_domains": [],
    },
    "env": {"FOO": "bar"},
    "setup_commands": [],               # SetupCommandParam 列表
    "files": [],                        # HostedEnvironmentFileParam 列表
    "skills": [],                       # HostedSkillParam 列表
    "plugins": [],                      # HostedPluginParam 列表
    "capability_directories": [],
    "environment_template_id": "tmpl_...",
}

env = client.beta.agents.environments.create(
    environment=environment,
    vault_ids=["vault_..."],            # 至多 10 个
)

这是类型层最小示例:各字段的类型与枚举逐字来自 environment_create_params.py,但本文未真机调用(beta 门控,以你的 API 响应为准)。网络配置有一条类型层注释值得照录:非空的 allowed_domains 列表要求 access: "restricted",且不能与某些配置组合(注释原文:"A nonempty list requires access: restricted and cannot be combined with…"——完整约束以源码为准)。

3. 闲置生命周期:挂起与过期

v3.28.0(python)与 v7.32.0(node)同日加入 suspension 与 expiration。会话事件侧两个新类型的文档原文:

agent.session.environment.suspended
"Emitted after an idle hosted session environment is checkpointed and stopped."

agent.session.environment.expired
"Emitted after a suspended hosted session environment and its checkpoint expire."

换句话说:环境闲置 → 打 checkpoint 并停止(挂起);挂起状态超时 → 环境与 checkpoint 一起过期。webhook 侧有对应事件,文档原文是 "Sent when an agent environment is suspended and can resume from a snapshot"——挂起的环境可从快照恢复。事件对象本身带 event_id、session_id、可选 turn_id 与环境当前状态字段。

4. v3.29.0 的其余新增

10-11 的 v3.29.0 在环境线之外又加了四项(release notes Feature 行):

• billing_not_active 会话错误码——会话错误码家族新成员,名字指向计费未激活的场景;
• shida 进入 named Live voices——Live 语音家族的命名声音新增一位;
• vault updates and metadata filters——vault 侧的更新与元数据过滤;
• beta 分页限额与参数非空对齐——各 beta 资源的分页参数语义拉齐。

openai-node v7.32.0 在环境 API 之外附了一个 runners 修复:totalUsage 保留详细 token 用量(#2900),对用 runner 统计用量的项目是个值得升级的修复。

5. 常见错误与排查

• 调用 environments.create 报权限/不存在类错误:先确认版本(openai-python ≥ 3.27.0、openai-node ≥ 7.32.0),再确认 beta 权限——SDK 文档明言 "Requires access to the prewarming beta"。本文无法替你判断账号是否在 beta 内,以 API 响应为准。
• 收到 agent.session.environment.suspended 不是故障:按事件文档,这是闲置环境的预期生命周期动作,webhook 文档写明可从快照恢复。
• billing_not_active:v3.29.0 新增的会话错误码,字面指向计费未激活;排查方向是账户计费状态而非代码。具体触发条件在当日可加载渠道中没有更多说明,不展开。
• 环境怎么挂到会话上:SDK 类型层可见会话事件带 environment 状态,但"创建后会话如何引用环境 ID"的完整参数面,在当日抓取的类型文件中没有完整呈现——本文不猜测,留待下批核对。

6. 下一步

• 模型侧的同窗动态见《GPT-6 家族扩容:gpt-6-sol、gpt-6-luna、gpt-6.1-sol 进驻官方 SDK,dots 与 Intelligent UI 同窗亮相》;
• Agents 与会话 API 的前情见《gpt-6-astra 现身 OpenAI SDK：ChatModel 枚举新模型 ID 与 Safety Alerts API 解读》;
• 官方 release notes 与 tag 源码直链见文首引用清单——本文每条引号句都能在那六个链接里逐字找到。