You need to enable JavaScript to run this app.
文档中心
火山方舟

火山方舟

复制全文
下载 pdf
配置 Agent 环境
配置云环境
复制全文
下载 pdf
配置云环境
本文介绍如何为方舟 Managed Agents 创建和管理云端沙箱环境,包括环境模板、资源规格、出网策略、预构建脚本、环境变量、启动脚本和产物存储。​
Environment 描述 Agent 运行时使用的沙箱模板。一个 Environment 可以被多个 Session 复用,但每个 Session 会启动独立的沙箱实例,文件系统状态彼此隔离。​
Managed Agents 同时支持云环境和自托管环境。本页只介绍由方舟管理沙箱的云环境。如果你需要在企业基础设施中执行工具或访问内网资源,选择自托管环境,详情请参见 自托管环境概述。​
创建环境​
你可以在控制台的 Environments 页面创建 Environment,也可以使用 API 创建。​
在控制台单击 创建 Environment,按需配置以下内容:​
  • 类型:选择云托管环境。​
  • 环境模板:选择基础模板。base 适合常规命令行、代码执行和文件处理任务;browser 适合需要浏览器运行依赖的网页访问、页面解析或自动化任务。​
  • 资源规格:选择云沙箱的 CPU 和内存规格。未选择时默认使用 1x。​
  • 预装包:配置预构建阶段安装的系统包和语言依赖。​
  • 预构建脚本:配置依赖安装后执行的构建脚本。​
  • 环境变量:配置注入沙箱进程的非敏感键值对。​
  • 初始化脚本:设置每个 Session 启动时执行的初始化命令,例如创建目录或拉取本次任务所需的数据。​
  • 产物存储:可选。需要长期保留 Agent 产物时,选择自己的 TOS 目录;不选择时使用方舟公共 TOS。​
说明​
创建 Environment 时使用清晰且唯一的名称,便于区分开发、测试和生产等不同用途。​
参考以下示例代码,使用 API 创建环境:​
​
environment=$(​
curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/environments" \​
-H "Authorization: Bearer $ARK_API_KEY" \​
-H "Content-Type: application/json" \​
-d @- <<'EOF'​
{​
"name": "<ENVIRONMENT_NAME>",​
"config": {​
"type": "cloud",​
"networking": {​
"type": "unrestricted"​
},​
"template_id": "browser",​
"spec": "4x",​
"packages": {​
"pip": ["pandas"],​
"apt": ["curl"]​
},​
"build_script": "python -c \"import pandas; print('prebuild ready')\"",​
"env": {​
"MY_KEY_0": "value_0",​
"MY_KEY_1": "value_1"​
},​
"setup_script": "mkdir -p /workspace/bootstrap && echo ready > /workspace/bootstrap/status.txt"​
}​
}​
EOF​
)​
​
ENVIRONMENT_ID=$(jq -er '.id' <<<"$environment")​
​
echo "Environment ID: $ENVIRONMENT_ID"​
​
主要配置项:​
  • name:Environment 名称,在当前项目内需要唯一。​
  • description:Environment 的说明信息。​
  • config.type:运行环境类型,云托管环境取值为 cloud。​
  • config.networking.type:沙箱的出站网络访问策略。unrestricted 不限制访问目标,但仍受平台通用安全拦截策略约束;limited 只允许访问显式配置的域名和平台运行必需的网络规则。​
  • config.template_id:云环境模板。base 为默认模板,适合常规命令行和代码执行任务;browser 预置浏览器运行依赖,适合需要访问网页或执行浏览器自动化的任务。模板能力差异,详情请参见 环境模板。​
  • config.spec:云沙箱资源规格。未配置时默认使用 1x。1x、2x、4x、8x 分别对应 2、4、8、16 vCPU,每个 vCPU 搭配 2 GiB 内存。可选规格与资源映射,详情请参见 沙箱规格。​
  • config.packages:在预构建阶段安装系统包和语言依赖。配置后,使用该 Environment 的 Session 可以直接使用这些依赖,无需重复安装。依赖版本可以显式锁定,未指定版本时安装最新版本。​
  • ​
    字段​
    包管理器​
    示例​
    apt​
    系统包(apt-get)​
    "ffmpeg"​
    cargo​
    Rust(cargo)​
    "ripgrep@14.0.0"​
    gem​
    Ruby(gem)​
    "rails:7.1.0"​
    go​
    Go modules​
    "golang.org/x/tools/cmd/goimports@latest"​
    npm​
    Node.js(npm)​
    "express@4.18.0"​
    pip​
    Python(pip)​
    "pandas==2.2.0"​
    ​
  • config.env:注入沙箱进程的环境变量。需要让 Agent 读取非敏感业务参数时配置,例如时区或服务地址。​
  • config.build_script:在 config.packages 安装完成后执行,用于提前下载依赖、编译项目或生成后续 Session 可复用的文件。​
  • config.setup_script:每个 Session 沙箱启动阶段执行的初始化脚本。需要为本次 Session 准备目录、拉取运行时数据,或者读取环境变量和 Session 文件时配置。​
  • config.tos:Agent 最终产物的 TOS 存储位置。需要长期保留 Agent 生成的报告、文件或代码时配置;不配置时产物使用方舟公共 TOS。​
注意​
config.networking、config.template_id、config.spec、config.packages、config.build_script、config.env、config.setup_script 和 config.tos 仅适用于 cloud 类型的 Environment。创建或更新自托管环境时,只传 config.type: self_hosted。​
说明​
服务端会校验完整 config 的大小。创建或更新后的配置超过当前上限时,接口返回 HTTP 400 InvalidParameter,错误信息中会给出允许的最大字节数。更新接口按合并后的完整配置校验。​
为 Session 准备依赖和初始化内容​
创建 Environment 时,可以提前准备多个 Session 都会使用的依赖和文件,也可以为每个 Session 配置单独的初始化逻辑。​
根据内容是否需要在多个 Session 中重复使用,选择 config.packages、config.build_script 或 config.setup_script。​
​
你的需求​
建议配置​
使用效果​
让每个 Session 都能直接使用同一批系统包、语言依赖或固定版本工具。​
config.packages​
使用该 Environment 创建的 Session 可以直接使用这些依赖,无需再次运行安装命令。​
编译项目、下载基础模型文件或生成缓存,并让后续 Session 继续使用这些内容。​
config.build_script​
脚本在依赖安装完成后执行,生成的文件、缓存和构建产物可以被后续 Session 使用。​
根据本次任务准备目录、拉取短期数据,或读取环境变量和 Session 文件。​
config.setup_script​
每个 Session 启动时执行一次,只为当前 Session 准备运行内容。​
​
说明​
不要在 config.setup_script 中安装多个 Session 都要使用的依赖,否则每次启动 Session 都会重复安装。固定依赖写入 config.packages;依赖安装后的编译、下载和缓存生成写入 config.build_script。​
配置出网策略​
云环境支持两种出网策略。选择策略时,先判断 Agent 的工具执行是否需要访问任意公网目标,还是只需要访问少量固定域名。​
​
策略​
适用场景​
关键配置​
unrestricted​
沙箱需要访问多个不固定的公网目标,例如通用网页抓取、临时下载资源或调试外部 API。​
只需要设置 config.networking.type 为 unrestricted。​
limited​
沙箱只应该访问固定外部服务,例如企业 API、指定对象存储域名或固定回调地址。​
设置 config.networking.type 为 limited,并在 allowed_hosts 中列出允许访问的域名。​
​
创建限定出网的云环境时,参考以下示例:​
​
environment=$(​
curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/environments" \​
-H "Authorization: Bearer $ARK_API_KEY" \​
-H "Content-Type: application/json" \​
-d @- <<'EOF'​
{​
"name": "<ENVIRONMENT_NAME>",​
"config": {​
"type": "cloud",​
"networking": {​
"type": "limited",​
"allowed_hosts": [​
"api.example.com",​
"*.example-cdn.com"​
],​
"allow_package_managers": true​
},​
"packages": {​
"pip": ["requests"]​
}​
}​
}​
EOF​
)​
​
ENVIRONMENT_ID=$(jq -er '.id' <<<"$environment")​
​
echo "Environment ID: $ENVIRONMENT_ID"​
​
限定出网策略包含以下配置项:​
  • allowed_hosts:允许沙箱直接访问的外部域名列表。只支持裸域名或最左侧通配符域名,例如 api.example.com、*.example-cdn.com。不要填写 URL、端口、路径、查询参数、IP 地址或 localhost。​
  • allow_package_managers:是否额外允许包管理器访问平台配置的软件源域名。开启后,沙箱可以为 apt、cargo、gem、go、npm、pip 依赖访问对应软件源;关闭或省略时,packages 不会自动放行外部软件源。​
注意​
limited 是失败关闭策略。省略 allowed_hosts 且未开启 allow_package_managers 时,沙箱不会额外放行外部域名。更新 Environment 后,只有之后创建或升级的 Session 使用新策略,已有 Session 继续使用创建时冻结的配置。​
配置产物存储​
需要将产物长期保存在自己的 TOS Bucket 时,为 Environment 配置 config.tos;继续使用方舟公共 TOS 时,省略该字段。config.tos 控制平台将 outputs 产物注册到 Files API 时使用的持久化位置,不等同于 resources 中 type: tos 的沙箱挂载目录。​
​
你的配置​
产物位置​
你需要做什么​
不配置 config.tos​
方舟公共 TOS​
在平台 TTL 到期前下载所需文件。删除 Session 时,平台会清理默认存储中的关联产物。​
配置 config.tos​
你的 TOS Bucket。平台从 outputs 目录注册产物时,Files API 写入前缀为 {prefix}outputs/{env-id}/{session-id}/;最终对象路径以响应中的 tos.object_key 为准​
在 TOS 中管理对象生命周期。删除 Session 不会删除 Bucket 中的对象。​
​
将产物写入自己的 TOS Bucket 时,需要满足以下条件:​
  • Bucket 与 Managed Agents 服务须部署在同一地域,跨地域 Bucket 会在预检查阶段被拒绝。​
  • bucket 和 prefix 必须同时提供,不能只配置其中一个字段。​
  • prefix 使用相对路径,例如 ark-files/。Prefix 无需预先创建。​
  • 平台从 outputs 目录注册产物时,会在该前缀后追加 outputs/{env-id}/{session-id}/ 作为 Files API 写入前缀。最终对象路径以响应中的 tos.object_key 为准,通常还会包含 ark_processed/{file_id}/{file_type}/{filename}。​
  • 直接调用 Files API 并传入 tos[prefix] 时,不会追加 Environment ID 或 Session ID,但 Files API 仍会在该前缀下生成服务侧处理目录。​
以下示例演示创建带产物存储的 Environment,以及为后续 Session 更新存储位置:​
​
# Create an environment that stores outputs in your TOS bucket.​
environment=$(​
curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/environments" \​
-H "Authorization: Bearer $ARK_API_KEY" \​
-H "Content-Type: application/json" \​
-d @- <<'EOF'​
{​
"name": "<ENVIRONMENT_NAME>",​
"config": {​
"type": "cloud",​
"networking": {​
"type": "unrestricted"​
},​
"tos": {​
"bucket": "<TOS_BUCKET>",​
"prefix": "ark-files/"​
}​
}​
}​
EOF​
)​
​
ENVIRONMENT_ID=$(jq -er '.id' <<<"$environment")​
echo "Environment ID: $ENVIRONMENT_ID"​
# Example output: Environment ID: env-20260723142038-xxxxx​
​
# Replace the output storage configuration for future sessions.​
updated_environment=$(​
curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/environments/$ENVIRONMENT_ID" \​
-H "Authorization: Bearer $ARK_API_KEY" \​
-H "Content-Type: application/json" \​
-d @- <<'EOF'​
{​
"config": {​
"tos": {​
"bucket": "<NEW_TOS_BUCKET>",​
"prefix": "new-prefix/"​
}​
}​
}​
EOF​
)​
​
jq '{id, tos: .config.tos}' <<<"$updated_environment"​
# Example output:​
# {​
# "id": "env-20260723142038-xxxxx",​
# "tos": {"bucket": "<NEW_TOS_BUCKET>", "prefix": "new-prefix/"}​
# }​
​
注意​
先更新 Environment,再创建需要使用新存储配置的 Session。已有 Session 继续使用创建时的存储配置,不会自动切换到新的 Bucket 或 prefix。​
在 Session 中使用环境​
创建 Environment 后,在创建 Session 时传入 environment_id,即可复用该 Environment 的运行配置和产物存储配置。​
​
session=$(​
curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/sessions" \​
-H "Authorization: Bearer $ARK_API_KEY" \​
-H "Content-Type: application/json" \​
-d @- <<EOF​
{​
"agent": "$AGENT_ID",​
"environment_id": "$ENVIRONMENT_ID",​
"title": "Quickstart session"​
}​
EOF​
)​
​
SESSION_ID=$(jq -er '.id' <<<"$session")​
​
echo "Session ID: $SESSION_ID"​
​
如果只有某次任务需要使用不同的产物存储位置,可以在创建 Session 时使用 Environment 覆写,不需要修改可复用的 Environment。详情请参见 覆写产物存储。​
了解 Environment 与 Session 的关系​
  • 多个 Session 可以引用同一个 Environment,但每个 Session 都会获得独立的沙箱实例。​
  • Session 之间不共享文件系统状态。​
  • Environment 本身不做版本化管理。如果你频繁更新环境配置,建议在业务侧记录变更,以便追溯某个 Session 使用的是哪一版配置。​
  • 归档 Environment 后,已有 Session 继续使用创建时保存的环境配置;后续不能更新该 Environment,也不能用它创建新 Session。​
  • 删除 Environment 前,必须先删除所有关联 Session。status 为 terminated(已终止)或 archived_at 已有值(已归档)的 Session 仍保留关联关系,也需要先删除。​
管理环境​
你可以列出、查看、更新、归档或删除 Environment。​
​
# List environments​
environments=$(​
curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/environments" \​
-H "Authorization: Bearer $ARK_API_KEY"​
)​
​
# Retrieve a specific environment​
environment=$(​
curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/environments/$ENVIRONMENT_ID" \​
-H "Authorization: Bearer $ARK_API_KEY"​
)​
​
# Update environment name, description, and prebuild config​
environment=$(​
curl -sS --fail-with-body -X POST "https://ark.cn-beijing.volces.com/api/v3/environments/$ENVIRONMENT_ID" \​
-H "Authorization: Bearer $ARK_API_KEY" \​
-H "Content-Type: application/json" \​
-d @- <<'EOF'​
{​
"name": "<UPDATED_ENVIRONMENT_NAME>",​
"description": "<UPDATED_ENVIRONMENT_DESC>",​
"config": {​
"spec": "8x",​
"build_script": "python -c \"print('updated prebuild')\""​
}​
}​
EOF​
)​
​
# Archive an environment while retaining its configuration​
environment=$(​
curl -sS --fail-with-body \​
"https://ark.cn-beijing.volces.com/api/v3/environments/$ENVIRONMENT_ID/archive" \​
-H "Authorization: Bearer $ARK_API_KEY" \​
-H "Content-Type: application/json" \​
-d '{}'​
)​
​
# Delete an environment (only if no sessions reference it)​
curl -sS --fail-with-body -X DELETE \​
"https://ark.cn-beijing.volces.com/api/v3/environments/$ENVIRONMENT_ID" \​
-H "Authorization: Bearer $ARK_API_KEY"​
​
更新 Environment 时,可以修改名称、描述和运行配置。字段规则和生效范围,详情请参见 更新环境。​
不再希望新 Session 使用某个 Environment,但仍需保留配置供查询时,选择 归档环境;确定不再保留 Environment 时,先删除所有关联 Session,再 删除环境。​
归档只改变 Environment 配置的可用性,不会迁移或备份云沙箱、方舟公共 TOS 中的临时产物,以及你自己的 TOS Bucket 中的对象。已有 Session 继续使用创建时保存的环境配置。​
预置运行时​
云沙箱默认包含常见语言运行时、数据库和工具。需要确认具体内置版本、目录用途或完整清单时,详情请参见 云沙箱参考。​
​
最近更新时间:2026.11.10 15:35:29
这个页面对您有帮助吗?
有用
有用
无用
无用