创建托管运行环境,配置容器、依赖、网络、初始文件和 Skill。
接口
POST /agents/environments
创建一个托管运行环境。成功返回 201,表示环境已登记并开始异步准备;准备完成前创建引用该环境的 Session 可能失败。
请求体environmentobject (必选)环境配置,见下表
属性 type string (必选)环境类型,固定为 openai_hostedenvironment_template_id string (可选)环境模板 ID;模板必须属于当前工作空间。模板通过环境模板管理。env object (可选)环境变量;变量名需匹配 [A-Za-z_][A-Za-z0-9_]*,不能是 PATH,也不能以保留前缀开头;值不能包含 NULpackages object (可选)预装包,按 npm、python、system 分组network object (可选)网络策略,见下表
属性 access string (可选)网络访问模式,enabled、disabled 或 restrictedallowed_domains array<string> (可选)允许的域名,access=restricted 时必须非空,只接受主机名,不能包含协议、端口或通配符array (可选)初始文件,当前使用 file_id 引用源文件
属性 type string (必选)文件引用类型,固定为 file_idpath string (必选)环境内绝对路径,必须在 /workspace/ 内file_id string (必选)通过 POST /agents/file 上传后得到的源文件 IDobject (可选)桌面配置,当前只接受 enabled=false,enabled=true 返回 400setup_commands array (可选)初始化命令,按顺序执行。每项包含必填的 command 和可选的 cwd,cwd 默认为 /workspaceskills array (可选)Skill,当前使用 skill_reference,最多 32 项
属性 type string (必选)Skill 引用类型,固定为 skill_referenceskill_id string (必选)技能资源 IDversion string (可选)Skill 版本;省略时解析 latest 并冻结具体版本array (可选)能力发现目录,必须在 /workspace/ 内array<string> / null (可选)挂载的 Vault,最多 10 个plugins 非空时当前拒绝;desktop.enabled=true 当前拒绝。 skill_id 来自 Skill API。先通过创建 Skill或列出 Skill获取可用的 skill_id 和版本。创建支持可选的 Idempotency-Key Header。同一工作空间内使用相同的键和请求正文时返回已有资源;键相同但正文不同返回 409。挂载 unrestricted Credential 时,network.access 必须为 restricted,allowed_domains 必须非空且合法。示例:"skills": [{"type": "skill_reference", "skill_id": "skill_xxx", "version": "1.0"}] | 请求示例 |
响应字段idstring环境 IDobject stringEnvironment 对象类型,固定为 agent.environmenttype string环境类型,固定为 openai_hostedstatus string环境状态:pending、ready、connected、disconnected、suspended、expired、failedfiles array已安装文件的安全元数据,不返回文件内容。
属性 id string环境文件 IDtype string文件引用类型,固定为 file_idpath string环境内文件路径size_bytes integer文件字节数file_id string原始源文件 IDarray已安装 Skill 的安全元数据,不返回 Skill 包内容。
属性 type stringSkill 引用类型,固定为 skill_referencename string技能名称description string技能说明skill_id string技能资源 IDversion string已冻结的具体版本array插件列表,当前托管环境返回 [];历史记录中的插件字段不代表可以创建创建返回 201 不表示环境已经 ready。使用环境前先获取状态并确认 ready。 | 响应示例 |
错误码
| HTTP 状态码 | 错误类型 / 错误码 | 解决方案 |
|---|---|---|
400 | invalid_request_error / missing_required_parameter,param=environment | 在请求体提供 environment |
400 | invalid_request_error / invalid_request_error | 按 environment 字段说明修正 type 和配置 |
404 | not_found_error / not_found_error | 使用当前工作空间内存在且可访问的模板或环境 |
409 | conflict_error / conflict_error | 同一幂等键使用相同请求正文 |
503 | server_error / environment_unavailable 或 template_storage_unavailable | 稍后重试;持续失败时提交工单并提供 x-request-id |
{"error":{"type","code","message","param"}},网关错误可能使用不同结构。排查时保留 HTTP 状态、x-request-id 和脱敏后的请求正文。