面向 AI 助手:本页的 Markdown 版本位于 https://ark.volcengine.com/region:cn-beijing/docs/create-environment-api.md,全部文档索引见 https://ark.volcengine.com/llms.txt。

创建环境

POST https://ark.cn-beijing.volces.com/api/v3/environments

创建 Environment,用于配置托管智能体的运行环境。创建成功后,可在创建 Session 时通过返回的 Environment ID 引用该环境。

鉴权#

本接口支持鉴权方式如下,详情请参见 Base URL 及鉴权。

  • API Key 鉴权,请在 API Key 管理 页面,获取长效 API Key。

请求参数#

Body 参数#

config object 必选  |  环境配置

定义 Environment 的运行方式和启动配置。

type string 必选  |  环境类型

config.type

Environment 的运行方式。cloud 表示由火山方舟提供运行环境,self_hosted 表示由调用方提供运行环境。

build_script string  |  预构建脚本

config.build_script

依赖包安装完成后执行的预构建脚本,用于提前下载依赖、编译项目或生成后续 Session 可复用的文件。脚本内容必须使用有效的 UTF-8 编码,且不能包含 NUL 字符。

env object  |  环境变量

config.env

Environment 运行时使用的环境变量,以变量名和变量值组成的字符串键值对形式传入。

networking object  |  出网策略

config.networking

Environment 的出网配置。创建 cloud 环境时必填;创建 self_hosted 环境时无需提供。

type string 必选  |  出网策略类型

config.networking.type

Environment 的出网方式。可选值:unrestricted、limited。

allow_package_managers boolean  |  允许包管理器

config.networking.allow_package_managers

限定出网模式下,是否允许访问包管理器软件源。

allowed_hosts string[]  |  主机白名单

config.networking.allowed_hosts

限定出网模式下,允许沙箱直接访问的外部域名列表。

packages object  |  依赖包配置

config.packages

创建云环境时需要安装的依赖包。配置后,使用该 Environment 创建的 Session 可以直接使用这些依赖,无需额外执行安装命令。

apt string[]  |  apt 包

config.packages.apt

Environment 预构建阶段通过 apt 安装的系统包。

cargo string[]  |  Cargo 包

config.packages.cargo

Environment 预构建阶段通过 Cargo 安装的 Rust crate。

gem string[]  |  gem 包

config.packages.gem

Environment 预构建阶段通过 RubyGems 安装的 Ruby 包。

go string[]  |  go 包

config.packages.go

Environment 预构建阶段通过 Go 工具链安装的模块依赖。

npm string[]  |  npm 包

config.packages.npm

Environment 预构建阶段通过 npm 安装的 Node.js 包。

pip string[]  |  pip 包

config.packages.pip

Environment 预构建阶段通过 pip 安装的 Python 包。

type string  |  配置类型

config.packages.type

依赖包配置的类型标识。

取值固定为 packages。

setup_script string  |  启动脚本

config.setup_script

每个 Session 沙箱启动阶段执行的初始化脚本,用于准备本次运行所需的目录、短期数据或运行时配置。需要读取环境变量、Session 文件或其他运行时资源的初始化逻辑应放在该脚本中。

spec string 默认值 1x  |  资源规格

config.spec

创建云环境时使用的 CPU 和内存规格。1x、2x、4x、8x 分别对应 2、4、8、16 vCPU,每个 vCPU 搭配 2 GiB 内存。省略时默认使用 1x。

template_id string 默认值 base  |  模板 ID

config.template_id

创建云环境时使用的逻辑模板 ID:base 适用于常规命令行和代码执行任务;browser 适用于网页访问、页面解析和浏览器自动化任务;省略时使用 base。

tos object  |  产物存储配置

config.tos

指定智能体产物的持久化存储位置。

bucket string  |  TOS 桶

config.tos.bucket

存储智能体产物的 TOS Bucket 名称。

prefix string  |  对象前缀

config.tos.prefix

智能体产物在 TOS Bucket 内的基础目录前缀。平台注册 outputs 产物时,会以 {prefix}outputs/{env-id}/{session-id}/ 作为 Files API 写入前缀。

最终对象路径以 Files API 响应中的 tos.object_key 为准,通常还会包含 ark_processed/{file_id}/{file_type}/{filename}。

name string 必选  |  环境名称

Environment 的名称,用于在当前项目中识别和管理该环境。

description string  |  环境描述

用于说明 Environment 的用途,最长 300 个字符。

metadata object  |  自定义元数据

用于记录 Environment 的业务属性,以字符串键值对形式传入,便于关联和管理资源。

scene string 默认值 default  |  场景标记

Environment 所属的业务场景。可选值:default、dreams。

响应参数#

created_at string  |  创建时间

Environment 创建时间,采用 RFC 3339 格式的 UTC 时间。

id string  |  环境 ID

Environment ID,由服务端生成,以 env- 开头。

name string  |  环境名称

Environment 的名称。

type string  |  对象类型

对象类型,固定为 environment。

updated_at string  |  更新时间

Environment 最后更新时间,采用 RFC 3339 格式的 UTC 时间。

archived_at string  |  归档时间

Environment 首次归档的时间,采用 RFC 3339 格式的 UTC 时间。Environment 未归档时,不返回该字段。

config object  |  环境配置

Environment 当前生效的运行配置。

type string  |  环境类型

config.type

Environment 的运行方式。cloud 表示由火山方舟提供运行环境,self_hosted 表示由调用方提供运行环境。

build_script string  |  预构建脚本

config.build_script

Environment 配置的预构建脚本,在依赖包安装后执行。

env object  |  环境变量

config.env

Environment 运行时使用的环境变量,以字符串键值对形式返回。

networking object  |  出网策略

config.networking

Environment 当前生效的出网配置。对于 self_hosted Environment,服务端固定返回 type 为 unrestricted。

type string  |  出网策略类型

config.networking.type

Environment 的出网方式。可选值:unrestricted、limited。

allow_package_managers boolean  |  允许包管理器

config.networking.allow_package_managers

限定出网模式下,是否允许访问包管理器软件源。

allowed_hosts string[]  |  主机白名单

config.networking.allowed_hosts

限定出网模式下,允许沙箱直接访问的外部域名列表。

packages object  |  依赖包配置

config.packages

Environment 配置的依赖包。

apt string[]  |  apt 包

config.packages.apt

Environment 预构建阶段通过 apt 安装的系统包。

cargo string[]  |  Cargo 包

config.packages.cargo

Environment 预构建阶段通过 Cargo 安装的 Rust crate。

gem string[]  |  gem 包

config.packages.gem

Environment 预构建阶段通过 RubyGems 安装的 Ruby 包。

go string[]  |  go 包

config.packages.go

Environment 预构建阶段通过 Go 工具链安装的模块依赖。

npm string[]  |  npm 包

config.packages.npm

Environment 预构建阶段通过 npm 安装的 Node.js 包。

pip string[]  |  pip 包

config.packages.pip

Environment 预构建阶段通过 pip 安装的 Python 包。

type string  |  配置类型

config.packages.type

依赖包配置的类型标识。

取值固定为 packages。

setup_script string  |  启动脚本

config.setup_script

Environment 配置的启动脚本,每个 Session 沙箱启动时执行。

spec string  |  资源规格

config.spec

Environment 当前生效的云沙箱资源规格。1x、2x、4x、8x 分别对应 2、4、8、16 vCPU,每个 vCPU 搭配 2 GiB 内存。

template_id string  |  模板 ID

config.template_id

Environment 当前生效的云环境模板。base 表示基础模板,browser 表示浏览器任务模板。

tos object  |  产物存储配置

config.tos

智能体产物的持久化存储位置。

bucket string  |  TOS 桶

config.tos.bucket

存储智能体产物的 TOS Bucket 名称。

prefix string  |  对象前缀

config.tos.prefix

智能体产物在 TOS Bucket 内的基础目录前缀。平台注册 outputs 产物时,会以 {prefix}outputs/{env-id}/{session-id}/ 作为 Files API 写入前缀。

最终对象路径以 Files API 响应中的 tos.object_key 为准,通常还会包含 ark_processed/{file_id}/{file_type}/{filename}。

description string  |  环境描述

Environment 的用途说明。

metadata object  |  自定义元数据

Environment 的自定义业务属性,以字符串键值对形式返回。

scene string  |  场景标记

Environment 所属的业务场景。可选值:default、dreams。