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。