OpenAI 创建智能体环境
post /agents/environments
在创建会话之前创建 OpenAI 托管环境。需要预热 Beta 功能的访问权限。
请求头参数
"Idempotency-Key": optional string
minLength: 1, maxLength: 256
请求体参数
内容类型为 application/json。
environment: object { type, capability_directories, desktop, 8 more }
必填的托管类型及其配置。
type: "openai_hosted" (default: "openai_hosted")
对象类型,固定为 openai_hosted。
"openai_hosted"
capability_directories: optional array of string or null
包含可向智能体提供的能力的目录。默认为空列表。
minItems: 0, maxItems: 16384
desktop: optional object { enabled } or null
桌面配置。省略或传入 null 时继承模板设置,无模板设置时默认禁用。
enabled: boolean
是否配置桌面及其浏览器代理。
env: optional map[string] or null
向智能体提供的环境变量。
environment_template_id: optional string
先于内联配置应用的可复用托管环境模板。省略的字段继承模板,网络覆盖配置只能保持或收紧模板的网络策略。
minLength: 0, maxLength: 64
files: optional array of HostedEnvironmentFileParam or null
智能体启动前可用的文件。默认为空列表。
minItems: 0, maxItems: 50
FileID object { file_id, path, type }
此前通过 OpenAI Files API 上传的文件。
file_id: string
已上传文件的 ID。
minLength: 1, maxLength: 256
path: string
/workspace 内的目标绝对路径。
minLength: 1, maxLength: 4096
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { data, path, type }
直接以标准 Base64 数据提供的文件。
data: string
采用标准 Base64 编码的文件内容。
minLength: 0, maxLength: 6990508
path: string
/workspace 内的目标绝对路径。
minLength: 1, maxLength: 4096
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
network: optional object { access, allowed_domains, blocked_domains } or null
环境的网络访问策略。省略时,由 API 版本决定是否启用网络访问。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: optional array of string or null
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 16384
blocked_domains: optional array of string or null
网络访问受限时,执行器和浏览器均禁止访问的域名。列表非空时须设置 access: restricted,且 allowed_domains 必须为空。不支持通配符域名。
minItems: 0, maxItems: 100
packages: optional object { npm, python, system } or null
要安装到环境中的软件包。软件包列表默认为空。
npm: optional array of string or null
要全局安装的 npm 软件包。默认为空列表。
minItems: 0, maxItems: 16384
python: optional array of string or null
要安装的 Python 软件包。默认为空列表。
minItems: 0, maxItems: 16384
system: optional array of string or null
要安装的系统软件包。默认为空列表。
minItems: 0, maxItems: 16384
plugins: optional array of HostedPluginParam or null
以内联 ZIP 归档提供的插件。默认为空列表。
minItems: 0, maxItems: 32
description: string
.codex-plugin/plugin.json 中声明的插件描述。
minLength: 0, maxLength: 1048576
name: string
.codex-plugin/plugin.json 中声明的插件名称。
minLength: 1, maxLength: 64
source: InlineCapabilitySourceParam
提供以标准 Base64 编码的 ZIP 数据。
data: string
采用标准 Base64 编码的 ZIP 归档数据。
minLength: 1, maxLength: 70254592
media_type: "application/zip" (default: "application/zip")
归档文件的媒体类型,固定为 application/zip。
"application/zip"
type: "base64" (default: "base64")
对象类型,固定为 base64。
"base64"
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
setup_commands: optional array of SetupCommandParam or null
按顺序执行的机密初始化命令。响应始终省略命令正文。
minItems: 0, maxItems: 16
command: string
要执行的 Shell 命令。
minLength: 0, maxLength: 65536
cwd: optional string or null
工作目录的绝对路径,默认为 /workspace。
minLength: 0, maxLength: 4096
skills: optional array of HostedSkillParam or null
通过 ID 引用或以内联 ZIP 归档提供的技能。默认为空列表。
minItems: 0, maxItems: 200
SkillReference object { skill_id, type, version }
引用通过 Skills API 上传的技能。
skill_id: string
通过 /v1/skills 创建的技能 ID。
minLength: 1, maxLength: 64
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: optional string or null
技能版本,可以是正整数或 latest。省略时选择默认版本。
minLength: 0, maxLength: 1048576
Inline object { description, name, source, type }
直接在会话请求中提供技能 ZIP。
description: string
SKILL.md 中声明的技能描述。
minLength: 0, maxLength: 1048576
name: string
SKILL.md 中声明的技能名称。
minLength: 1, maxLength: 64
source: InlineCapabilitySourceParam
提供以标准 Base64 编码的 ZIP 数据。
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
vault_ids: optional array of string or null
OpenAI 托管环境可访问的凭证库 ID,最多 10 个。
minItems: 0, maxItems: 10
返回值
EnvironmentInfo object { id, files, object, 4 more }
可返回的独立执行环境资源的元数据。
id: string
环境 ID。
minLength: 0
files: array of HostedEnvironmentFile
环境中已安装的文件。响应省略文件内容。
minItems: 0, maxItems: 2000
HostedEnvironmentFileID object { id, file_id, path, 2 more }
从 OpenAI Files API 复制的文件。
id: string
执行环境中会话范围内的文件 ID。
minLength: 0
file_id: string
已上传文件的 ID。
minLength: 0
path: string
文件在环境内的绝对路径。
minLength: 0
size_bytes: integer
文件解码后的大小,单位为字节。
format: int64, minimum: 0
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { id, path, size_bytes, type }
创建会话时以内联方式提供的文件。
id: string
执行环境中会话范围内的文件 ID。
minLength: 0
path: string
文件在环境内的绝对路径。
minLength: 0
size_bytes: integer
文件解码后的大小,单位为字节。
format: int64, minimum: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
object: "agent.environment" (default: "agent.environment")
对象类型,固定为 agent.environment。
"agent.environment"
plugins: array of HostedPlugin
环境中已安装的插件。响应省略归档内容。
minItems: 0, maxItems: 2000
description: string
已安装插件的描述。
minLength: 0
name: string
已安装插件的名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
skills: array of HostedSkill
环境中已安装的技能。响应省略归档内容。
minItems: 0, maxItems: 2000
HostedSkillReference object { description, name, skill_id, 2 more }
从 Skills API 安装的技能。
description: string
已安装技能的描述。
minLength: 0
name: string
已安装技能的名称。
minLength: 0
skill_id: string
引用的技能 ID。
minLength: 0
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: string
此会话实际安装的技能版本。
minLength: 0
Inline object { description, name, type }
从内联 ZIP 归档安装的技能。
description: string
已安装技能的描述。
minLength: 0
name: string
已安装技能的名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
status: "pending" or "ready" or "connected" or 4 more
环境当前的连接状态。
"pending"
"ready"
环境已成功配置,可附加到会话或投入使用。
"connected"
"disconnected"
"suspended"
沙箱已停止,可从其私有检查点恢复。
"expired"
"failed"
type: "openai_hosted" or "self_hosted"
环境由 OpenAI 还是由应用托管。
"openai_hosted"
"self_hosted"
示例
## 从环境变量读取 API 密钥。
curl https://api.openai.com/v1/agents/environments \
-H 'Content-Type: application/json' \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"environment": {
"type": "openai_hosted"
}
}'
201 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"id": "id",
"files": [
{
"id": "id",
"file_id": "file_id",
"path": "path",
"size_bytes": 0,
"type": "file_id"
}
],
"object": "agent.environment",
"plugins": [
{
"description": "description",
"name": "name",
"type": "inline"
}
],
"skills": [
{
"description": "description",
"name": "name",
"skill_id": "skill_id",
"type": "skill_reference",
"version": "version"
}
],
"status": "pending",
"type": "openai_hosted"
}
创建后,可获取智能体环境查看其连接状态。

TRAE-AI编程


更多建议: