本文介绍如何为方舟 Managed Agents 创建和管理云端沙箱环境，包括预装依赖包、环境变量、启动脚本和产物存储。 **Environment** 描述 Agent 运行时使用的沙箱模板。一个 Environment 可以被多个 Session 复用，但每个 Session 会启动独立的沙箱实例，文件系统状态彼此隔离。 Managed Agents 同时支持云环境和自托管环境。本页只介绍由方舟管理沙箱的云环境。如果你需要在企业基础设施中执行工具或访问内网资源，选择自托管环境，详情请参见 [自托管环境概述](https://ark.volcengine.com/region:cn-beijing/docs/self-hosted-environment-overview)。 ## 创建环境你可以在控制台的 [Environments](https://ark.volcengine.com/region:cn-beijing/managed-agents/environments?projectName=default) 页面创建 Environment，也可以使用 API 创建。在控制台单击 **创建 Environment**，按需配置以下内容： * 类型：选择云托管环境。 * 预装包：配置沙箱启动前安装的系统包和语言依赖。 * 环境变量：配置注入沙箱进程的非敏感键值对。 * 初始化脚本：配置沙箱启动阶段执行的脚本。 * 产物存储：可选。需要长期保留 Agent 产物时，选择自己的 TOS 目录；不选择时使用方舟公共 TOS。 > **说明** > 创建 Environment 时使用清晰且唯一的名称，便于区分开发、测试和生产等不同用途。参考以下示例代码，使用 API 创建环境： ```bash 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": "", "config": { "type": "cloud", "networking": { "type": "unrestricted" }, "packages": { "pip": ["pandas"], "apt": ["curl"] }, "env": { "MY_KEY_0": "value_0", "MY_KEY_1": "value_1" } } } EOF ) ENVIRONMENT_ID=$(jq -er '.id' <<<"$environment") echo "Environment ID: $ENVIRONMENT_ID" ``` 主要配置项： * `name`：Environment 名称，在当前项目内需要唯一。 * `description`：Environment 的说明信息。 * `config.type`：运行环境类型，云托管环境取值为 `cloud`。 * `config.networking.type`：沙箱的出站网络访问策略。`unrestricted` 允许完整出站网络访问，但仍受通用安全拦截列表限制。 * `config.packages`：沙箱启动前预安装的依赖包。依赖会在使用同一 Environment 的 Session 之间缓存。若同时配置多个包管理器，系统按 `apt`、`cargo`、`gem`、`go`、`npm`、`pip` 的顺序执行。依赖版本可以显式锁定，未指定版本时安装最新版本。 |字段 |包管理器 |示例 | |---|---|---| |`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.setup_script`：沙箱启动阶段执行的初始化脚本。需要在每次启动沙箱时准备目录、下载资源或执行自定义初始化命令时配置。 * `config.tos`：Agent 最终产物的 TOS 存储位置。需要长期保留 Agent 生成的报告、文件或代码时配置；不配置时产物使用方舟公共 TOS。 ## 配置产物存储需要将产物长期保存在自己的 TOS Bucket 时，为 Environment 配置 `config.tos`；继续使用方舟公共 TOS 时，省略该字段。无论选择哪种存储方式，Agent 都将最终交付物写入沙箱内的 `/mnt/session/outputs/`。 |你的配置 |产物位置 |你需要做什么 | |---|---|---| |不配置 `config.tos` |方舟公共 TOS |在平台 TTL 到期前下载所需文件。删除 Session 时，平台会清理默认存储中的关联产物。 | |配置 `config.tos` |你的 TOS Bucket，完整对象路径为 `{prefix}outputs/{env-id}/{session-id}/{file}` |在 TOS 中管理对象生命周期。删除 Session 不会删除 Bucket 中的对象。 | 将产物写入自己的 TOS Bucket 时，需要满足以下条件： * 目标 Bucket 已在方舟项目中完成授权，详情请参见 [用户对象存储（TOS）授权](https://ark.volcengine.com/region:cn-beijing/docs/project-configuration#4eb1b277)。 * Bucket 与 Managed Agents 服务须部署在同一地域，跨地域 Bucket 会在预检查阶段被拒绝。 * `bucket` 和 `prefix` 必须同时提供，不能只配置其中一个字段。 * `prefix` 使用相对路径，例如 `ark-files/`。最终对象路径会自动追加 `outputs/{env-id}/{session-id}/{file}`。以下示例演示创建带产物存储的 Environment、更新存储位置，以及清空配置，使后续 Session 改用方舟公共 TOS： ```Bash # 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": "", "config": { "type": "cloud", "networking": { "type": "unrestricted" }, "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": "", "prefix": "new-prefix/" } } } EOF ) jq '{id, tos: .config.tos}' <<<"$updated_environment" # Example output: # { # "id": "env-20260723142038-xxxxx", # "tos": {"bucket": "", "prefix": "new-prefix/"} # } # Clear the configuration so future sessions use the default storage. cleared_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 '{ "config": { "tos": {} } }' ) jq '{id, tos: (.config.tos // null)}' <<<"$cleared_environment" # Example output: # { # "id": "env-20260723142038-xxxxx", # "tos": null # } ``` > **注意** > 先更新 Environment，再创建需要使用新存储配置的 Session。已有 Session 使用创建时冻结的配置快照，不会自动切换到新的 Bucket 或 `prefix`。 ## 在 Session 中使用环境创建 Environment 后，在创建 Session 时传入 `environment_id`，即可复用该 Environment 的运行配置和产物存储配置。 ```bash 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 ) # 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" ``` ## 预置运行时云沙箱默认包含常见语言运行时、数据库和工具。需要确认具体内置版本、目录用途或完整清单时，详情请参见 [云沙箱参考](https://ark.volcengine.com/region:cn-beijing/docs/cloud-sandbox-reference)。

火山方舟