Environment 是 Session 的执行资源,包括 Harness 运行所在的机器、工作区以及能力。Session 通过其 environment 配置创建 Environment,或挂载由 POST /agents/environments 预先创建的 Environment(独立 Environment)。Environment 模板是 Session 创建时解析的可复用准备配置。本契约涵盖这两类资源、两种放置方式、输入接纳、能力准备、Skills、Plugins 和 MCP 连接来源。
相关职责归属:
- Environment files:实时工作区上的 Files API。
- 执行器凭据:
self_hosted机器的注册、安装授权和连接状态。 - Sandbox deployment:托管
openai_hostedEnvironment 的沙箱提供商(microsandbox、E2B 或 OpenSandbox)。 - Core–Runtime protocol:
runtime_prepare传输及所有其他线上消息。 - Runtime and outer isolation:daemon 使用启动用户的权限运行工具;隔离由外层 Environment 提供。
资源与状态
路径遵循 SDK 资源方法,并位于服务的 /v1 前缀之前。链接中的固定版本源码定义了字段和联合类型。
| 资源 | 操作 | 规则 |
|---|---|---|
| Environment | GET /agents/environments/{id} | 通过 Session 配置或 POST /agents/environments 创建。返回 id、type、status,以及创建时记录的 files、plugins 和 skills。 |
| Environment 集合 | POST、GET /agents/environments | 参见独立 Environment。 |
| 模板 | POST、GET /agents/environments/templates;GET、POST、DELETE /agents/environments/templates/{id} | 请参阅 模板。 |
| Files | POST、GET /agents/environments/{id}/files | 请参阅 Environment files。 |
读取 Environment 时,Core 限定在调用方的项目范围内,隐藏所属 Session 已删除的 Environment,并返回持久化的连接状态。它不需要活跃的 Runtime,不会启动任何原生工作,也不会改变连接状态。对于两种放置方式,安装项数组都会列出由 API 管理的文件、Plugins 和 Skills:文件使用 {id, type, path, file_id, size_bytes} 且不含内容,Skills 使用 {type, name, description, skill_id, version},Plugins 使用 {type, name, description}。在本地能力目录中发现的 Capabilities 不会列出。
Session environment input 与 output 的结构不同:
none不选择任何 Environment。self_hosted输入要求提供workspace_directory;可空的capability_directories默认为空列表。输出会增加 Environment ID 和仅输出字段remote_url。输出中/workspace的默认值不会使输入字段变为可选。openai_hosted可以引用模板,并提供capability_directories、network、packages、files、plugins、skills、env和setup_commands。
| 投影 | 状态 |
|---|---|
| Environment resource | pending、ready、connected、disconnected、suspended、expired、failed |
| Session environment event | 相同的七种状态,并带可为 null 的 error |
Core 在事件中发出 ready,资源对已准备好且未挂载 Session 的独立 Environment 读作 ready(见列出和检索)。它从不报告 suspended,即使是它已做检查点并停止的空闲 hosted Environment;它也不发出 agent.session.environment.suspended、.expired 或 .reset 事件;保留期结束的 Environment 读作 expired,但没有对应事件。资源状态按下图变化,失败或过期的 Environment 不再改变:
stateDiagram-v2
[*] --> pending
pending --> ready
ready --> connected
connected --> ready
disconnected --> ready
ready --> expired
pending --> connected
connected --> disconnected
disconnected --> connected
pending --> failed
connected --> failed
disconnected --> failed
pending --> expired
connected --> expired
disconnected --> expired
Session environment 事件携带 Session 和 Environment 的身份标识以及可选的 Turn 身份标识,绝不携带配置、凭据、注册 ID 或修订号。Session 的 required_actions 可以包含 {type: "environment_connection", environment_id},这与函数调用相互独立。Environment 连接、Session 状态和 Turn 状态相互独立。
Core 在 Session 创建事务中创建 Environment 记录;Session upsert 会选出重试的胜者,而重试绝不创建或修复 Session 自有的 Environment。Environment 记录自己持有项目、不可变配置和准备输入,由 Session 引用它;一个 Environment 至多挂载一个存活的 Session。其首个状态为 pending;self_hosted Environment 在首次连接前读作 disconnected。Session 自有 Environment 的 Session 删除后,读取会隐藏该 Environment,而 Core 仍保留该记录,用于结算和清理。独立 Environment 的存续长于其 Session。Session 为 none 时没有 Environment。
托管的外层 Environment 必须排除权限范围更广的应用程序凭据和其他租户的机密。
独立 Environment
POST /agents/environments 在任何 Session 存在之前创建并初始化一个 openai_hosted Environment,使后续 Session 在已预热的计算上启动。独立 Environment 可复用:同一时刻只有一个 Session 挂载到它,该 Session 被删除后,下一个 Session 即可挂载。Environment 在多个 Session 之间保留其计算、工作区和准备结果。
创建。 请求体为 {environment, vault_ids}。environment 取 Session 的 environment 中的 openai_hosted 成员,不含 environment_id,可以指定模板;Core 解析并应用模板的方式与 Session 相同。vault_ids 可以为 null 或 [];非空列表返回 400。Idempotency-Key 为 1–256 字节,限定在项目范围内。每个项目密钥都以该项目的身份认证,因此创建者不再增加范围:列出、检索和该键都只涉及项目的 Environment。键和发送的正文都相同的重试返回处于当前状态的 Environment(包括 pending),即使所指定的模板此后已被删除;创建在一个事务中完成,因此重试不会遇到未完成的创建;不同正文返回 409 idempotency_conflict。Core 校验 hosted Session 为其 Environment 所需的接纳(部署、工作区存储、网络策略),冻结 Skills,封存 setup 和初始文件,并返回 201,Environment 状态为 pending。随后开始供给,调用方无需操作。
列出和检索。 GET /agents/environments 列出项目的独立 Environment,包括 failed 和 expired 的,使用官方分页,以 type=openai_hosted 为唯一取值;limit 见页面大小。GET /agents/environments/{id} 对两种 Environment 都有效。没有挂载 Session 且初始化已完成的 Environment,读作 ready,而不是 pending、connected 或 disconnected;挂载 Session 后读作连接状态,failed 和 expired 始终如实读出。
挂载。 带有 environment: {"type": "openai_hosted", "environment_id": "…"}(9–256 个字符)的 POST /agents/sessions 在该 Environment 上运行 Session,使用其冻结的配置。environment_id 旁的其他成员返回 400,param 为该成员(environment.packages 等),x_agents_core.environment 同样如此。Harness、模型和工具来自 Session。Core 的返回如下:
| 情况 | 响应 |
|---|---|
| 不存在、属于其他项目,或已删除的 Session 自有 Environment | 404 not_found_error |
| 已挂载到存活的 Session | 409 conflict_error,“Environment is attached to another session.”,param 为 environment.environment_id |
failed 或 expired | 409 conflict_error,“Environment has failed or expired and cannot take a session.”,param 为 environment.environment_id |
| Environment 的网络策略无法到达该 Session 的模型提供方 | 400 model_provider_unreachable,param 为 environment.environment_id |
pending 的 Environment 可以挂载:Session 的首个输入像任何 hosted 输入一样等待准备完成,已挂起或已释放的分配会被唤醒。挂载不再重复工作区接纳,并按 Environment 冻结的网络策略检查 Session 的模型提供方(上表最后一行);同时执行依赖 Session 的检查,例如 Harness 的原生历史要求。部署还必须接纳新的 hosted 工作:重置待定或接纳关闭时,挂载与内联创建一样被拒绝。两个并发挂载有且仅有一个成功。
卸载。 删除 Session 是唯一的卸载方式。Environment 立即可再次挂载,并保留其工作区和准备结果。
文件。 没有挂载 Session 时的文件路由由 Environment files 规定。
无 Session 时的生命周期。 未挂载的 Environment 无需 Harness 即可供给和初始化,其存续时间取决于沙箱提供商。支持检查点时,它在部署的空闲超时后挂起,并在快照保留期结束时过期,两者的取值见挂起策略。节点的 retained slot 已满并阻塞等待中的放置时,容量压力可以让已挂起的空闲 Environment 提前过期。不支持检查点时它无法挂起,因此在空闲超时内没有活动后过期,空闲时间从最近一次活动起算:初始化完成、卸载或之后的活动。计算在启动期限内没有运行并完成 bootstrap 的 Environment 会失败。失败的 Environment 会立即释放其计算。无论哪种提供商,确认计算丢失后它也会过期(包括 Session 持有期间被释放的计算,在该 Session 被删除后),因为 Core 从不在新计算上替换它:没有任何信息能标识要重放的工作。沙箱重置同样会让它过期。已过期的 Environment 不能挂载。已结束(expired 或 failed)的未挂载 Environment 会释放其放置和工作区。
放置方式
两种放置方式运行相同的 Runtime:daemon、所选 Harness、原生工具和工作区共同在一台机器上运行。二者唯一的差异是由谁拥有该机器。
| 对象 | 责任 |
|---|---|
| Session 与 Environment | 持久所有权、配置、待处理交互和连接观察(Core) |
| 提供商分配 | 计算资源和文件系统的生命周期:openai_hosted 使用 Core 的沙箱提供商,self_hosted 使用应用程序 |
| 设备与 daemon 连接 | 经认证的 Runtime 身份和可替换的分派传输 |
| Harness 进程与原生会话 | 原生模型和工具循环、其执行状态及原生历史 |
| 注册 | self_hosted 机器的 Environment、设备和执行器凭据的精确绑定 |
托管(openai_hosted)
部署中配置的沙箱提供商(microsandbox、E2B 或 OpenSandbox,请参阅 sandbox deployment)承载 Environment。Harness capabilities 列出了可在其中运行的 Harnesses。
- Session 创建时,无论是否包含初始输入,都会在 Worker 配置计算资源之前提交 Session、Environment 和重试身份。若创建在 bootstrap 前中断,可恢复时不会重复执行提供商的 Create。
- 置备无需调用方执行任何操作;在 Turn 启动之前,Session 会保持空闲。
- 省略或传入 null 的
network表示启用;disabled和restricted需要托管 Environment,且其沙箱 Provider 能限制出站(网络策略)。 - Core 重启会保留分配、工作区和原生身份,并且绝不重播结果不确定的工作。
- 终止清理会先在一个事务中撤销权限并结算待处理输入,然后提供商才会回收计算资源。向处于终止状态的 Environment 提交新输入会被拒绝。
- 删除 Session 会回收 Session 自有的 Environment,但绝不回收独立 Environment;删除模板两者都不回收。
自托管(self_hosted)
应用程序拥有机器。它使用干净的绝对路径 workspace_directory 和可选的绝对本地 capability_directories 创建 Session。Core 会返回 Environment ID、remote_url 以及 x_agents_core.installation 中的一条安装命令;在该机器上运行此命令会安装 daemon 并为其注册(自托管指南、执行器凭据)。
remote_url是根据 Core 的公共 URL 推导出的 daemon WebSocket URL,绝不根据请求头或 daemon 地址生成。它指定 Core 的私有 daemon 传输通道。- 注册会将精确的 Session、Environment、设备和执行器凭据绑定在一起。它不会创建任何分配,也无法将 Session 迁移到另一台设备。
- Session 的工作区必须等于
/workspace别名,或等于 Runtime 绑定到的精确规范目录。指定某个路径并不会授予对它的访问权限。 - Session 读取、列表和事件会返回带有 Environment ID、工作区及能力目录的
self_hosted输出,但绝不返回私有配置。capability_directories列出调用方选择的内容;Runtime 的安装位置保持私有。 - 计算资源、工作区和文件仍归应用程序所有。删除 Session 或撤销凭据会拒绝后续访问,但不会停止原生进程;机器所有者负责停止和清理。
- 工作区和原生历史必须能在 daemon 重启后继续存在。丢失它们绝不授权进行静默替换或重播。
应用管理的 E2B。 应用程序可以在由其使用 E2B SDK 创建、续期和销毁的 E2B sandbox 中运行 Runtime,然后将该 Runtime 注册为 self_hosted Environment(E2B Runtime guide)。Core 不为其保留 E2B 分配,也绝不续期或终止它。
所有权规则
- 将 Environment 身份、所有权、配置和生命周期保留在 Core 中,并使其与提供商计算资源、设备身份、daemon 套接字和原生会话相分离。将可变连接状态排除在不可变配置之外;替换后的所有者会使过期观察值失效。
- 调用方、设备和 Environment 连接使用彼此不同的凭据。daemon gateway 会对已注册的执行器凭据和精确设备进行认证。连接观察保留 generation 和 revision 栅栏。注册和连接都不表示已就绪。
- 轮换、撤销、Session 删除和所有权丧失都会拒绝后续访问;但它们不保证原生效果会立即停止。
- 原生历史保留在绑定的 Runtime 上。替换计算资源时必须保留或以可证明的方式恢复原生历史;绝不能静默移动已绑定的 Session 或重播未知工作。
- 持久元数据读取不需要活跃的 Runtime。实时文件读取需要获得对精确工作区的授权视图和有界操作所有权。写入、替换或撤销工作区所有者的操作也适用变更栅栏。
- 当 Session 已有已启动的 Turn,但没有记录原生 session ID 时,下一个 Turn 必须通过经验证的 Runtime 能力恢复已有历史。已提供的原生 ID 始终具有权威性。Codex 适配器仅通过原生列举和精确 ID 恢复,恢复 Session 私有原生主目录及预期工作目录中唯一且未归档的根项。历史缺失、不完整或存在歧义时会失败且不会创建新根项;记录的启动可能早于原生工作时也会失败。恢复绝不会重播被中断的输入。设备身份和 Environment 范围属于
ExecutionDevice;原生会话身份和先前 Turn 状态属于SessionExecutionBinding。 - Runtime 发现会为每个已安装的 Harness 执行一次 15 秒版本探测;缺少二进制文件会立即失败。版本结果仅表示可用性,而非 Environment 就绪状态。
输入接纳
对于带 Environment 的 Session,Core 会将尚不能启动的输入预留,直到 Environment 完成连接和准备。发送输入和创建 Session 时的初始输入定义每个请求的行为,输入错误列出全部结果。无输入的创建不会创建 Turn 或连接操作,但仍会请求 Environment 准备。
有效的节点模式创建可以在提交后等待计算容量。初始输入在等待期间仍使用同一 reservation 和期限。Placement 与代次选择 定义调度规则。
在 Session 锁内,重试会先恢复其原始预留或回执,然后由 Core 在活动 Turn 与新预留之间选择,并在后续工作中保持该目标。未加锁的读取或冲突后的重试绝不会选择不同路径。
等待预留的 POST /v1/agents/sessions/{session_id}/events 请求使用有界的池化操作,位于事务和执行租约之外;它绝不会准备或启动原生工作。只有该路由会将其响应写入期限延长至六分钟,以涵盖五分钟的数据库期限及响应时间。
预留
预留会在 Turn 接纳之前存储一个规范消息批次,截止时间依据数据库时钟设置为五分钟。
stateDiagram-v2
[*] --> pending
pending --> admitted: Turn claim
pending --> expired: deadline
pending --> cancelled: cancellation, archive or reset
pending --> failed: preparation failure
- 它要求 Session 带有 Environment,且没有活动工作。预留和直接输入共享 Session 锁和重试标识;pending 或 settled 的 key 不能通过直接接纳绕过其预留。
- pending 预留会阻止新的直接批次,包括取消;较早成功的重试仍保持可读。
- 提升操作会将原始输入、历史、预留结算和 Turn 认领(
queued到in_progress)一并提交。它要求当前持有租约的执行写入方和保留的原生准备状态;准备期间不持有数据库锁。只有首次成功且非重放的回执授权在该准备状态上执行 Start。已接纳的重试会返回原始回执,而不重新获取执行权;读取或不确定的提交绝不复授权另一次 Start。 - 提升之后、Start 之前发生崩溃时,会进入已认领 Turn 的协调流程(
execution_interrupted),即使 Session 未绑定或已删除也是如此。 - 输入处于 pending 时会拒绝删除 Session,且不会更改任何内容。认领之后删除 Session 会像处理任何活动 Turn 一样被拒绝。
- 截止时间在取得 Session 锁后检查。过期和定向取消会保留其终止身份;终止预留的重试不能影响后续预留或 Turn。
- 初始预留过期时会使 Session 失败;后续预留则会让 Session 回到空闲状态。失败事件会原子地捕获已结算的活动和 Usage。迟到的连接或创建重试不能重置或重播已过期的输入。
当 Runtime 返回 failed 结果、带有 preparation_failed 且没有 Run 时,会立即以 runtime_preparation_failed 结算待处理输入。当当前 execution_prepare 在没有 Run 且代码为 invalid_configuration、unsupported_configuration 或 unsupported_preparation 时被拒绝,也同样如此。在任何 Turn 存在之前,Core 会记录安全的 Session 失败并释放输入门控;修复本地原因后即可接受新输入。传输丢失、容量拒绝和未确认的清理在原始期限内保持可重试。Runtime 缺少所挂载 Session 的 Harness 时,会在其 executor 准备阶段以同样方式使该输入失败。Core 使用这些通用控制状态,绝不使用 Harness 特定的错误文本。
活动与必需操作
在 Turn 存在之前,Session 活动来自最近相关的预留和连接状态。离线 self_hosted Environment 上的待处理输入会请求 environment_connection;连接到达后会将其清除并设为 idle,同时 Worker 仍负责原生就绪性和接纳。没有待处理输入的离线 Environment 不会请求任何操作,而 openai_hosted 置备也绝不会请求连接。预留或连接变更会在同一事务中提交不可变的 Session 活动和使用量快照;较新的预留或活动 Turn 负责后续活动。已结算的非初始预留会将操作恢复为 idle,直至出现较新的工作。
过期
Worker 在正常 tick 中处理到期的预留,重启后继续。失败的 Turn 绝不能代替 Turn 之前的连接失败。
Runtime 能力准备
准备过程会安装 Session 选择的内容:初始文件、工具配置、Skills、Plugins、Environment MCP、npm 和 Python 软件包以及设置命令。两种放置方式使用同一条 Runtime 路径。
所有权与生命周期
资源管理负责提供商放置、容量和分配,以及 Environment 的创建、续期和回收。经认证的 Runtime 连接承载初始化、能力准备和 executor 操作;它绝不分配或销毁计算资源。提供商绝不运行 Core 初始化命令。
关闭 Executor、取消 Turn 或传输丢失都会保留已安装的快照、工作区和分配。回收是与活动工作协调的显式操作;断开的套接字不能证明原生效果已经停止。Harness onboarding 负责 Executor 和 Turn 的生命周期。
准备顺序
Core 会在 Session 创建时冻结资源版本、元数据和源选择。随后初始化按以下顺序运行,每一步都通过 runtime_prepare 使用同一个 daemon:
- 初始文件和工具配置;
- Skill 和 Plugin bundle 导入;
- npm 和 Python 软件包,然后按顺序运行设置命令;
- 能力目录快照。
运行器仅使用中立的 Environment 和 Session 身份以及一个 Runtime 对端,不包含提供商、部署或操作系统分支。Harness 差异保留在适配器中。
可移植的准备输入。 self_hosted 输入仅携带 workspace_directory 和 capability_directories。无论 Session 采用哪种工作区放置方式,还可以发送 x_agents_core.environment,这是 Core 扩展,包含 environment_template_id、files、env、packages、setup_commands、skills、plugins 和 capability_directories。它使用与 openai_hosted 输入相同的解析器和继承规则。若同一字段同时在 x_agents_core.environment 和顶层 environment 中提供,则会被拒绝,包括显式 null。self_hosted Session 只能通过此扩展指定模板。机器位置、规格大小和网络策略不是此扩展的字段。
{
"agent_id": "agent_example",
"environment": {"type": "self_hosted", "workspace_directory": "/home/user/project"},
"x_agents_core": {"environment": {"environment_template_id": "env_template_example"}}
}将 environment 改为 {"type":"openai_hosted"} 会复用相同的准备输入。资源解析、项目授权、具体 Skill 版本、加密文件内容和机密工具变量都会在 Session 创建时冻结。重试和重连会复用这些快照;新 Session 会解析新版本。self_hosted Environment 从不需要分配记录。
就绪性。 传输 connected 是一种连接观察,而不代表就绪。执行和实时文件访问都要等待初始化;随后,原生准备所有者会在接纳 Turn 前验证已安装的快照和 Harness。文件读取保留自身的就绪性和授权,不要求能力或原生就绪。部署模型凭据绝不发送到应用程序所有的机器。
传输。 初始文件、configure、npm、Python 和设置操作、惰性的 Skill 和 Plugin 归档以及最终确定选择,都会作为带有类型的 runtime_prepare 操作传输,并携带规范的 Environment 身份;protocol 负责分块和回执。文件及设置工作目录使用逻辑 /workspace 地址;Runtime 负责选择可执行文件和物理目标位置,Core 不提供任何可执行文件或主机平台字段。源选择接受可移植的 Unix 绝对路径、Windows 驱动器路径和 UNC 路径;Core 绝不会在自己的主机上解析这些路径,而 daemon 会应用其本地路径和访问检查。
已安装快照
两种来源都使用通用 Runtime 解析器,以及适用于 Linux、macOS 和 Windows 的 installed.json 清单。Runtime 操作者负责选择能力根目录(installer options);Core 和传输请求无法选择。
- 清单会将 Environment 绑定到有序的源选择摘要。准备所有者会在原生执行之前验证或创建该清单,即使选择为空也是如此。
- 设置命令运行后,初始化器会将声明的、位于工作区内的能力目录快照到 Runtime 存储中。目录字节是在设置之后读取,而不是在 Session 创建时读取。
- 文件系统锁可防止并发安装。私有完成记录仅保留操作者的安装根目录,因此已删除的快照绝不会被误认为首次准备,也不会再次被捕获。
- 快照缺失、不完整、冲突或属于外部来源时,会在不删除数据、修复或重播的情况下失败。
- 重连和替换 Executor 会加载已安装的内容,而不会重新读取源。对源的编辑只会影响新 Session。
- 对快照的递归引用,以及会逃逸出快照的目录项,都会被拒绝。
- 只读快照模式只是完整性提示,不能防止启动用户进行修改。
Executor 接纳仅验证已冻结的描述符。准备所有者会在调用原生工厂之前使能力就绪;适配器仅接收已解析的、由 Runtime 所有的 Skill 路径和 MCP 声明。复用的 Executor 会保留其原始配置。
系统依赖与 Runtime 目录
daemon 以启动它的账户身份运行,绝不使用 sudo 或提升权限。准备过程中只会安装用户目录中的依赖项。
- 系统依赖必须预先安装在托管镜像中,或由自托管机器的所有者安装。缺少可执行文件或库时,需要该依赖的操作会失败。
packages.system接受 null 或空列表(表示没有系统软件包),模板和内联配置会拒绝其他任何值(400,parampackages.system)。软件包响应包含官方要求的system: [],因此读取到的配置可以原样回传。- npm 会安装到本地 prefix,Python/pip 会安装到 Runtime 软件包目录下的本地 target;Node/npm 和 Python/pip 必须已经安装。其依赖项可被每个工作目录中的原生工具看到。
- 设置命令使用 Bash 运行;在 Windows 上必须使用 Git Bash,且不能由其他 shell 替代。默认工作目录为
/workspace。 - 在 Windows 上,npm 安装以及名为
npm或npx的 stdio MCP 命令(包括其.cmdshim)会通过 Node 调用 npm 的 JavaScript 入口点运行,而不经过额外的 shell。
Runtime 资源目录定义初始化、软件包和私有状态的位置。这些是资源路径,在 Core 中绝不是 Environment 源或操作系统开关。
每条命令都使用启动用户的权限和主机网络。进程所有权会等待退出及 I/O 结算完成。命令输出会被丢弃;确认失败时只保留一个有界整数退出状态。
使用外部工作区存储的托管计算替换后,仅持久 Environment 文件系统和已通过资格验证的 Harness 私有原生历史会保留。Setup 命令不会重放。Setup 和工具可以写入启动用户有权访问的其他位置,但冷续接不保留临时系统盘上的修改、进程内存或后台进程。持久输出应写入工作区,软件包应使用已声明的安装路径;沙箱提供商协议定义何时可以替换计算。
显式本地工具环境
安装程序的 --tool-env-file(OAC_RUNTIME_TOOL_ENV_FILE)提供 Runtime 操作者的基础工具变量。准备过程会将这些值复制到其私有初始化快照中,并由 Session 的 env 键覆盖。Runtime 绝不会重写源文件,也不会继承无关的环境凭据。设置、能力解析和 Harness 执行都会读取同一份已准备快照。即使操作者编辑了文件,重连仍会保留该快照;新 Session 会读取当前文件。Harness profile 可以引用由 Runtime 所有的文件,但不得持久保存其值的副本。配置的文件缺失或无效时,准备过程会失败。
初始化状态与失败
Environment 的初始化状态为 pending、running、complete 或 failed,且独立于任何分配、身份验证和连接发布。
stateDiagram-v2
[*] --> pending
pending --> running
running --> complete
pending --> failed
running --> failed
- Worker 的初始化调度器每次扫描 32 个 Environment,在末尾循环回绕,并依据执行并发度限制并发准备,且独立于提供商维护。
- 缺少套接字不会消耗一次 pending 尝试。每个操作都会重新检查当前权限和原始套接字;完成时还会重新检查精确绑定。
- 每个文件、Skill 或 Plugin 传输的暂存预算为两分钟。configure、软件包安装、设置命令和快照最终确定共享整个初始化过程的 30 分钟预算,Core 在每项操作中携带剩余时长,由 Runtime 执行。初始输入仍保留其五分钟接纳期限,因此大型安装应从空闲 Session 开始。
- 正在运行且所有权丧失的初始化,包括跨 Core 重启丧失所有权,会作为未确认而失败;不会重播任何内容。已完成的 Environment 在重连或原生恢复时绝不会重新安装,因此用户后续更改会保留下来。
- 失败对 Session 而言是终止状态,但不会销毁计算资源或文件。
- 每个
openai_hostedEnvironment 都从pending开始,包括没有文件和初始化设置的 Environment,并在开始初始化的事务中记录agent.session.environment.pending,在完成初始化的事务中记录agent.session.environment.ready,各恰好一次。Core 在观察到 Runtime 连接时记录agent.session.environment.connected,可能在pending之前或之后。这些都是 Session 事件,只在挂载了 Session 时记录:在挂载前已准备好的 Environment,不会向之后挂载的 Session 发出pending或ready。self_hostedEnvironment 不发出pending和ready,且除非有文件或初始化设置,否则从complete开始。
初始化失败时记录的事件和 Session 状态由 Environment 初始化失败定义。原因只指明步骤及其退出状态:
| 失败步骤 | 原因 |
|---|---|
设置命令 i,已确认退出 1–255 | Failed to provision environment: script "setup_commands[i]" failed with exit code N |
| Python 软件包,已确认退出 1–255 | Failed to provision environment: script "Python package installation" failed with exit code N |
| npm 软件包,已确认退出 1–255 | Failed to provision environment: script "npm package installation" failed with exit code N |
| 初始文件安装,确认失败 | Failed to provision environment: initial file installation failed |
| Skill 准备,确认失败 | Failed to provision environment: Skill installation failed |
| 其他情况:超时、未知效果、回执缺失或格式错误、Plugin 安装、快照最终确定、bootstrap 拒绝、Core 重启 | Failed to provision environment: initialization did not complete |
每个初始化操作都会返回有类型的 rejected、failed 或 unknown 结果,并且 daemon 会先确认进程退出和 I/O 结算完成。Core 使用固定标签和整数组成原因,因此命令、env 值、软件包名称、路径和进程输出绝不会进入原因、事件、日志或响应。失败步骤不会重试,后续步骤也不会运行。机密 env 和设置快照会与普通元数据分开加密。初始文件在所有平台上都使用原子替换写入器和工作区锚定路径;Files API 创建则保留其自己的不覆盖规则。
模板
模板是由项目拥有、供 openai_hosted Session、POST /agents/environments 和 x_agents_core.environment 使用的配置。它不包含运行中的工作区,也与 E2B 模板等提供商镜像无关。每个引用它的 Session 都会通过与内联配置相同的准备过程获得自己的 Environment。模板解析、存储和解析过程绝不会选择 Harness 或提供商,也不会依赖原生工具名称或 Harness 私有路径,因此新的 Harness 或提供商无需修改模板。
from openai import OpenAI
client = OpenAI() # reads OPENAI_BASE_URL and OPENAI_API_KEY
template = client.beta.agents.environments.templates.create(
name="Python workspace", network={"access": "enabled"},
env={"APP_MODE": "analysis"}, packages={"python": ["packaging==26.0"]},
setup_commands=[{"command": "mkdir -p /workspace/outputs"}],
)
session = client.beta.agents.sessions.create(
agent={"model": "your-configured-model"},
environment={"type": "openai_hosted", "environment_template_id": template.id},
input="Create /workspace/outputs/report.txt containing the result of 6 * 7.",
)操作
- 每个操作都需要项目 API 密钥和
OpenAI-Beta: agents=v1。模板操作无需执行部署,也不会分配计算资源。 name可选且可为 null,会逐字保留,长度为 1–256 个 Unicode 字符。network.access为enabled、disabled或restricted;省略或传入 null 表示启用。请参阅 Restricted network。- 响应会携带安全元数据,绝不会包含
env、setup_commands正文或内联文件数据。 - 列表操作使用
after、limit(默认 20;0 按 1 处理,超过 100 的值按 100 处理)和order(默认desc),并按创建时间和 ID 排序。不存在和属于外部项目的模板 ID 及游标都会返回相同的 404。 - 更新时,省略字段会保留原值,提供字段则会替换原值。Null 会清除
name和每个列表,并将network重置为启用。 - 封装或解封机密内容(文件、env、设置命令、Skills、Plugins)的写入操作和 Session 解析需要 Core 的 credential key;元数据读取则不需要。
- Session 会在创建时于其项目内解析一次
environment_template_id,冻结有效配置,并且绝不将模板 ID 传递给提供商或 Runtime。更新或删除模板绝不会改变现有 Session。创建重试会在读取模板之前恢复已记录的调用方意图,即使模板已删除也是如此;意图发生变化时会产生冲突。
继承
Session 会先应用模板,然后应用自身字段。组合仅在加密 Session 快照写入前执行一次,并使用常规验证器重新验证结果。调用方意图(省略、null 或显式提供)会单独保留,用于重试策略。
| 字段 | Session 中省略或为 null | Session 中提供 |
|---|---|---|
network | 继承整个模板策略 | 必须收窄策略:enabled 可以变为 restricted 或 disabled;restricted 可以变为其主机的子集或 disabled;disabled 不能放宽 |
env | 继承模板键 | 按键叠加;Session 值优先;{} 会保留所有模板键 |
setup_commands | 继承该序列 | 替换该序列;[] 会清除 |
files | 继承文件集 | 替换整个文件集;[] 会清除 |
packages | 继承两个管理器 | 分别解析 python 和 npm:省略或为 null 的管理器会被继承,列表会替换原值,[] 会清除;system 会被拒绝 |
skills、plugins、capability_directories | 继承列表 | 替换列表;[] 会清除 |
作为比较,不带模板的内联 openai_hosted Session 会将省略或为 null 的 network 视为启用。
准备复用
Core 可以用同一 Project 中较早一次准备的结果启动托管 Environment,前提是两者在 Template 组合之后的有效配置完全相同,且距该次准备不超过 24 小时。每个 Session 仍然得到自己的副本。此时设置命令和包安装不会为该 Session 再次运行。只复用 /environment(见生命周期与文件系统范围),HOME 和其他与计算实例本地相关的改动不会复用。设置过程不得产生每个 Session 唯一的值,不得执行必须按 Session 发生的外部副作用,也不得获取 24 小时内就会过期的凭据;需要这些行为的配置必须有所不同,例如在 env 或 files 上。未声明准备缓存的提供商始终完整准备。
受限网络
restricted 要求在 allowed_domains 中提供 1–100 个精确 ASCII 主机名;子域名和重定向目标需要各自的条目。通配符、URL 或端口语法、IP 字面量、Unicode 和尾随点都会被拒绝。读取操作会返回提供的拼写、顺序和重复项;比较操作使用单独的小写去重副本。
托管 Session 的有效 network 在部署的网络上限内收窄,并且该策略在沙箱的整个生命周期内生效,包括包安装和设置命令:
enabled:沙箱可访问上限允许的范围。disabled:沙箱只能访问 Core、Session 的模型提供商和主机 53 端口上的 DNS 服务器。模型提供商仅在公开地址上的base_url端口可达;私有的模型提供商主机只有在上限的额外域名覆盖其名称时才可达。需要网络的包安装和设置命令按普通设置错误失败。restricted:沙箱可访问所列域名、Core 和模型提供商(条件同disabled)。上限允许公网时,域名在公开地址上被允许;上限的额外域名按名称或*.条目覆盖该域名时,在其解析出的地址上被允许。其他域名在创建 Session 时被拒绝,错误码为sandbox_network_outside_cap,param指向该allowed_domains条目。上限之后缩小时,沙箱尝试以同一错误失败。
限制(适配器规则):
- 上限按名称或
*.条目列出的模型提供商主机与所列域名一样可达,不限于其端口。 - 在 E2B 上,受限域名只能通过 80 和 443 端口访问;模型提供商使用其他端口时,其公网地址的所有端口均可达。
- 在 OpenSandbox 上,Core 主机、允许的域名和模型提供商主机在其公网地址的每个端口上都可达。
部署的沙箱 Provider 无法限制出站时,disabled 和 restricted 返回 sandbox_network_unsupported。self_hosted Environment 只接受 enabled,因为 Core 无法在不由它运行的机器上强制策略。
Env 与设置命令
Agent 代码可以读取 env 值,但它们绝不会出现在公开元数据或初始化诊断中。名称必须匹配 ^[A-Za-z_][A-Za-z0-9_]*$,且值不能包含 NUL。Core 保留 PATH、OPENAI_API_KEY 以及所有以 OAC_ 或 CODEX_ 开头的名称。文件和软件包会在设置命令之前安装;退出状态非零的设置命令会使初始化失败;效果未知时不会重试任何命令;已完成设置在重连时绝不会再次运行。
初始文件
files 条目会将文件放置在 /workspace 内的绝对目标路径,来源可以是内联标准 Base64 data,也可以是项目所有的已上传 file_id。
| 限制 | 值 |
|---|---|
| 每个配置的文件数 | 50 |
| 内联文件 | 5 MiB |
| 所有内联内容 | 10 MiB |
| 引用文件 | 50 MiB |
| Session 或模板请求正文 | 16 MiB |
路径必须规范、互不相同且位于逻辑工作区内部;Runtime 会将每次写入锚定到其绑定的工作区。这是 API 路径范围,不是对以同一用户身份运行的原生工具的限制。模板元数据会将内联文件显示为 type、path 和 size,将引用显示为 type、path 和 file_id;无论内联文件还是引用,每个 Session 都会获得全新的文件 ID 和大小。文件数据不会出现在普通配置、响应、事件或命令参数中。模板会保留引用;每个 Session 会授权并冻结自己的加密源字节,因此之后删除源文件无法改变这些字节。
Skills
模板和内联配置都接受项目所有的 Skill 引用及内联 Skill ZIP。通过固定版本 SDK 上传目录,然后引用其默认版本:
skill = client.skills.create(files=[
("report/SKILL.md", b"---\nname: report\ndescription: Create the report.\n---\nFollow the report procedure.", "text/markdown"),
])
template = client.beta.agents.environments.templates.create(
skills=[{"type": "skill_reference", "skill_id": skill.id}],
)固定版本的 /v1/skills 资源、版本及内容路由使用项目 API 密钥,且不使用 Agents beta 标头。ZIP 上传使用 files,目录上传则重复使用 files[]。Upload a bundle 负责 bundle 格式、上传限制和 SDK 单文件限制;versions and metadata 负责默认版本和删除规则。
省略或传入 null 版本的引用会在 Session 创建时选择默认版本,"latest" 会选择最新版本,正版本号字符串则选择该版本。模板响应会保留未解析的选择器(默认版本为 version: null);Session 元数据会显示 {type, skill_id, version, name, description},其中版本为具体值。Session 会在其创建事务中冻结所选版本的字节和元数据;之后默认版本发生变化、源被删除或模板被更新,都无法改变这些内容。
内联 Skill 携带 name、description 和 Base64 ZIP source(media_type 为 application/zip)。归档包含一个顶层文件夹,其中有 SKILL.md 和可选的支持文件;清单中的 name 和 description 必须与请求一致。Frontmatter 可以包含 name、description、license、compatibility 和字符串 metadata;原生 hooks、权限控制和 subagent 指令都会被拒绝。只允许常规文件:路径遍历、链接、重复目标位置、特殊文件和无效清单都会被拒绝。内容在安装期间保持惰性,并保留可执行位。内联元数据只显示 type、name 和 description。
Plugins 与能力目录
Plugin 是带有 type、name 和 description 的内联 ZIP,其单个归档根目录包含 .codex-plugin/plugin.json。清单中的 skills 指定 Skill 目录;整个包布局都会保留。公开 Plugin 元数据只显示 type、name 和 description。
openai_hosted 和模板的 capability_directories 接受 /workspace 内的干净绝对路径,初始文件和设置命令可以填充这些路径。self_hosted 能力目录是机器上的绝对本地路径。通过目录发现的 Skills 绝不会显示为 skills 或 plugins 条目。目录缺失、Skill 名称重复、清单不受支持以及存在非常规文件时,初始化会失败。
| 归档与安装限制 | 值 |
|---|---|
| 每个归档 | 压缩后 5 MiB,展开后 20 MiB,1,000 个条目 |
| 内联 Skills | 总计 50 个,压缩后共 10 MiB,展开后共 50 MiB |
| Plugins | 总计 50 个,压缩后共 10 MiB,展开后共 50 MiB |
| 已安装快照 | 50 个 Skills、50 个 Plugins、50 MiB |
Skills、Plugins 与 Environment MCP
Skills 及其不可变版本是项目资源,独立于 Session 和原生安装。
- 版本分配、默认版本变更和串行化由 Versions and metadata 定义,Bundle 加密由 Upload a bundle 定义。元数据读取绝不会加载或解密 Bundle。删除 Skill 会回收其版本,但不会影响已冻结的 Session。
- 引用会在 Session 创建事务中、upsert 建立所有权之后解析。被引用的资源按稳定顺序锁定,版本、元数据和字节会一并冻结。公开引用元数据、未解析的模板意图和已解析的 Runtime Bundle 始终彼此独立;引用绝不会报告为内联内容。
内联和引用的 Skills 使用相同的机密快照与安装程序。Runtime 会在设置和原生执行之前,将它们安装到能力根目录下的 skills/<name>。适配器只注册所选的 Skill 根目录:Codex 将其注册为显式额外根目录,MiniMax Code 通过其原生目录进行注册,Claude 则将其作为私有状态路径下的用户 Skills,使原生列出与本地 ~/.claude/skills 相同的裸名称。Claude 拒绝包含 .claude-plugin 的 Skill,因为原生会将其作为插件加载,连同其 hooks 和 MCP 服务器。Skill 根目录不会启用 MCP 服务器,只有 Plugin MCP 会启用。Codex 与本地运行一样递归扫描每个 Skill 根目录,因此嵌套的 SKILL.md 会注册另一个原生 Skill。原生 Harness 配置绝不会整体透传。
Plugin MCP
Plugin 可以在 .codex-plugin/plugin.json 中通过 mcpServers: "./.mcp.json" 声明 MCP 服务器,也可以在省略路径时使用根目录下的 .mcp.json。该文件包含以服务器名称为键的 mcpServers。将 Plugin 根目录选为能力目录会激活其 MCP 声明;选择父目录则会发现 Skills,但不会激活嵌套 MCP 服务器。
共享解析器接受 HTTP url、bearer_token_env_var 和字面量 http_headers(与公开 MCP 标头一样为非机密),以及 stdio command、args、选定的 env_vars 和包相对路径 cwd。不支持公开的 env_http_headers。Runtime 会重新解析已冻结的已安装包,并且只从已初始化的 env 中解析选定值;缺少值时会失败,而不会回退到模型或 daemon 变量。
stdio 服务器通过 daemon 的 stdio helper 启动;该 helper 会解析已安装的声明,并以 Harness 的权限启动命令。在 Unix 上,helper 会将自身替换为服务器;在 Windows 上,它会在所属进程树内部转发 stdio。已初始化的值会覆盖声明中的变量。进程组和 Windows Jobs 负责取消及后代进程清理,而不负责隔离。
Harness capabilities 负责受支持的 Plugin 传输及每个 Harness 的限制。
重复的服务器身份会被拒绝。Claude 会拒绝 URL 或标头值中的 ${(原生差异)。MiniMax ACP HTTP 声明会保留在 Session 本地的原生内存中;令牌绝不会进入原生配置文件或进程参数。无法通过 Plugin 清单设置必需初始化和工具允许列表。
有效绑定
Runtime 会在适配器投影之前,通过 agent.ResolveMCPBindings 解析公开 HTTP 声明和已安装 Plugin MCP。每个瞬时绑定都会保留其连接来源、传输、可为 null 的工具允许列表、必需标志、凭据权限以及已安装 stdio 身份。绑定绝不会持久化或记录;重复身份和不可用的选定凭据都会被拒绝。MiniMax 会读取其 Session 私有的原生 runtime 名称注册表,以获取精确的首帧身份,并针对两种传输交叉检查已完成的原生结果;适配器绝不会伪造延迟启动事件或猜测身份。
公开 MCP 连接来源
Agent 的 HTTP MCP 工具(declaration)具有 connection_origin。省略或传入 null 表示 service,在 self_hosted Session 中也是如此,stdio 服务器除外,其唯一来源是 environment。该来源会从已保存配置经过 Session 快照一直保留到 Runtime 请求,后者要求精确的线上版本;service 请求绝不会变为 environment 连接。
| 来源 | 连接发起位置 | 允许的放置方式 |
|---|---|---|
service | Core 的服务端执行主机 | 仅 none |
environment | Environment 的工作区 | openai_hosted 和 self_hosted |
Core 的 Harness profile 会声明 MCPOrigins;接纳和分派会将来源与放置方式以及 Runtime 公布的 HTTP、bearer 和必需初始化能力进行核对,Runtime 会在调用适配器之前再次验证来源。不存在按 Harness 名称或提供商分支选择不同路径的逻辑。
Harness capabilities 负责每个 Harness 的来源支持和策略限制。
两种来源都支持匿名 HTTP 和 HTTPS bearer 凭据。所附加 Vault 的选择会冻结凭据身份,包括唯一的隐式 URL 匹配或匿名选择。只有该凭据经项目授权后,才会进入瞬时 Runtime 请求;绝不会搜索 Core 默认值或无关 Vault。解密失败或凭据缺失时,执行会失败且不会回退到匿名。公开 Environment MCP 保留 project_vault 权限,Plugin 凭据保留 environment_configuration 权限;两者都不会覆盖重复的服务器标签。Bearer 令牌绝不会进入持久化的原生配置或进程参数。
工具允许列表和必需初始化遵循 HTTP MCP contract。