OpenAI 创建智能体环境

2026-11-18 17:52 更新

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"
}

创建后,可获取智能体环境查看其连接状态。

以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号