OpenAI 沙箱生命周期

智能体会话可以比执行环境存在得更久。采用 self_hosted 时，由应用管理计算资源和文件。

启动环境

创建会话后，应用可通过提供商 SDK 或 API启动计算资源，再使用会话环境 ID 和环境密钥连接执行器。

应用提交输入并控制提供商资源，执行器向Agents API建立出站连接交换命令与结果。

每个会话的环境只指定一个管理组件，并保存会话与提供商计算资源的映射。重复或并发请求不应创建重复环境。

由 Webhook 启动计算资源

也可等输入需要环境连接时再启动。API 在等待执行器前发出 agent.session.action_required，其中 required_action.type: "environment_connection"。Webhook 处理器据此启动或重新连接环境。

示例见 Webhook 管理沙箱。

Webhook控制器验证请求、检查会话，再启动或重连提供商沙箱，执行器向OpenAI建立出站连接。

查看竖版图片

按 Webhook 配置订阅 agent.session.action_required 与 agent.session.failed。签名密钥、用于读取会话的凭证，与执行器使用的环境密钥分开保存。多个提供商处理器共用项目时，按会话归属路由事件。

处理器与工作进程分工如下：

验证并入队。验证 webhook 签名。只有 data.required_action.type 为 environment_connection 时才把连接请求入队，同时把会话失败事件入队。成功入队后再返回成功 HTTP 响应。
检查当前状态。工作进程重新读取会话，忽略已删除会话和已解决动作。自托管会话仍需连接时，用 session.environment.id 与 session.environment.remote_url 启动或重连执行器；会话仍处于失败状态时，释放计算资源。

会话事件流以 agent.session.requires_action 表示同一请求。function_call 所需的是函数结果，不是启动环境。等到轮次创建或 agent.session.in_progress 才启动离线执行器已经太迟。

部署处理器后，创建自托管会话并发送输入。工作目录和智能体筛选条件须与处理器配置一致；执行器在截止时间前连上，原提交会继续执行。

保持环境可用或停止环境

可在轮次之间保持计算资源运行以便复用，也可在轮次结束后保留一段宽限期再停止。关闭过程须与新任务协调：收到连接请求或开始执行时取消待关闭操作，真正停止前再次检查状态。

单独的空闲事件不是安全的关闭信号：连接请求消除后，等待中的输入可能还没启动轮次，就已经出现空闲事件。无法协调关闭与新输入时，应让环境保持运行。

断连后重新连接

agent.session.environment.connected 与 agent.session.environment.disconnected 报告连接状态；配置期间还可能出现 agent.session.environment.pending 或 agent.session.environment.failed。这些状态事件不是启动计算资源的请求，应由 environment_connection 所需动作触发启动，并另行检查提供商健康状态。

轮次中途断连可能让工具失败，即使该轮次最终完成，也要检查工具结果和最终回答。断连不会自动通过 webhook 请求重连，也不会重启已终止命令；后续输入可以再次请求连接。

输入时的连接等待最长五分钟。客户端与代理超时需覆盖这一过程。超时后提交失败；初始输入还可能异步失败，使会话处于 failed。

进程崩溃后，API 不保证恢复待处理输入。重试前检查请求或会话结果，原请求仍在等待时不要重复提交。迟到的连接不会重放已超时输入。

复用环境 ID 不会恢复替换计算资源上的文件。需要保存文件时，使用提供商存储或快照。

清理

先停止接收新输入，并与正在启动的环境协调，避免清理后仍有计算资源运行。

删除会话和停止提供商计算资源是两项独立操作。删除会话既不会停止环境，也不会发出删除 webhook。