本文介绍如何为方舟 Managed Agents 创建和管理云端沙箱环境,包括环境模板、资源规格、出网策略、预构建脚本、环境变量、启动脚本和产物存储。
Environment 描述 Agent 运行时使用的沙箱模板。一个 Environment 可以被多个 Session 复用,但每个 Session 会启动独立的沙箱实例,文件系统状态彼此隔离。
Managed Agents 同时支持云环境和自托管环境。本页只介绍由方舟管理沙箱的云环境。如果你需要在企业基础设施中执行工具或访问内网资源,选择自托管环境,详情请参见 自托管环境概述。 在控制台单击 创建 Environment,按需配置以下内容:
- 环境模板:选择基础模板。base 适合常规命令行、代码执行和文件处理任务;browser 适合需要浏览器运行依赖的网页访问、页面解析或自动化任务。
- 资源规格:选择云沙箱的 CPU 和内存规格。未选择时默认使用 1x。
- 初始化脚本:设置每个 Session 启动时执行的初始化命令,例如创建目录或拉取本次任务所需的数据。
- 产物存储:可选。需要长期保留 Agent 产物时,选择自己的 TOS 目录;不选择时使用方舟公共 TOS。
说明
创建 Environment 时使用清晰且唯一的名称,便于区分开发、测试和生产等不同用途。
参考以下示例代码,使用 API 创建环境:
主要配置项:
- 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 可以直接使用这些依赖,无需重复安装。依赖版本可以显式锁定,未指定版本时安装最新版本。
- 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。
说明
不要在 config.setup_script 中安装多个 Session 都要使用的依赖,否则每次启动 Session 都会重复安装。固定依赖写入 config.packages;依赖安装后的编译、下载和缓存生成写入 config.build_script。
云环境支持两种出网策略。选择策略时,先判断 Agent 的工具执行是否需要访问任意公网目标,还是只需要访问少量固定域名。
创建限定出网的云环境时,参考以下示例:
限定出网策略包含以下配置项:
- 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 的沙箱挂载目录。
将产物写入自己的 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 更新存储位置:
注意
先更新 Environment,再创建需要使用新存储配置的 Session。已有 Session 继续使用创建时的存储配置,不会自动切换到新的 Bucket 或 prefix。
创建 Environment 后,在创建 Session 时传入 environment_id,即可复用该 Environment 的运行配置和产物存储配置。
如果只有某次任务需要使用不同的产物存储位置,可以在创建 Session 时使用 Environment 覆写,不需要修改可复用的 Environment。详情请参见 覆写产物存储。 了解 Environment 与 Session 的关系
- 多个 Session 可以引用同一个 Environment,但每个 Session 都会获得独立的沙箱实例。
- Environment 本身不做版本化管理。如果你频繁更新环境配置,建议在业务侧记录变更,以便追溯某个 Session 使用的是哪一版配置。
- 归档 Environment 后,已有 Session 继续使用创建时保存的环境配置;后续不能更新该 Environment,也不能用它创建新 Session。
- 删除 Environment 前,必须先删除所有关联 Session。status 为 terminated(已终止)或 archived_at 已有值(已归档)的 Session 仍保留关联关系,也需要先删除。
你可以列出、查看、更新、归档或删除 Environment。
更新 Environment 时,可以修改名称、描述和运行配置。字段规则和生效范围,详情请参见 更新环境。 不再希望新 Session 使用某个 Environment,但仍需保留配置供查询时,选择 归档环境;确定不再保留 Environment 时,先删除所有关联 Session,再 删除环境。 归档只改变 Environment 配置的可用性,不会迁移或备份云沙箱、方舟公共 TOS 中的临时产物,以及你自己的 TOS Bucket 中的对象。已有 Session 继续使用创建时保存的环境配置。
云沙箱默认包含常见语言运行时、数据库和工具。需要确认具体内置版本、目录用途或完整清单时,详情请参见 云沙箱参考。