挂载 AgenticFS Volume

功能介绍

挂载后，Sandbox 可以通过文件路径访问 AgenticFS，数据不随 Sandbox 释放而删除。

如需向运行中的 Sandbox 追加挂载，请参见追加挂载 Volume。

适用范围

• 已为目标 Team 创建 AgenticFS Volume，并获取 Volume 名称。

• 已准备绑定同一 Team 的智能体沙箱 API Key。Volume 和 API Key 不能跨 Team 使用。具体操作，请参见创建 API Key。

• 已准备与 AgenticFS Access Point 网络连通的 VPC（Virtual Private Cloud，专有网络）、交换机和安全组。

• 已准备 RAM（Resource Access Management，访问控制）角色。该角色具备 AgenticFS 挂载和读写权限，且信任策略允许函数计算服务扮演。具体操作，请参见配置 RAM 角色。

• 已准备智能体沙箱 API URL、Domain 和可用模板。

注意：创建 Sandbox 前，必须确保对应的 AgenticFS Access Point 处于 active 状态，否则 createSandbox 调用可能超时或失败。可登录AgenticFS 控制台，找到对应的文件系统，进入详情页面，然后单击挂载使用查看 Access Point 状态。

创建 Sandbox 时使用的 VPC 配置必须包含 vpcId、securityGroupId 和非空的 vSwitchIds，且能够访问目标存储。模板中的 VPC 配置不能替代该挂载配置。

使用第二代运行时（MicroVM，微型虚拟机）自定义模板时，推荐在创建模板时设置 buildConfig.installStorageClients，由 Template Build 自动安装挂载所需的 AgenticFS 客户端。具体操作，请参见本文步骤一：在创建模板时预装存储客户端。

操作步骤

python3 -m venv .venv
source .venv/bin/activate
pip install "e2b==2.31.0"

export E2B_API_KEY="<YOUR-E2B-API-KEY>"
export E2B_API_URL="https://api.<REGION>.sandbox.aliyuncs.com"
export E2B_DOMAIN="<REGION>.sandbox.aliyuncs.com"
export E2B_TEMPLATE="code-interpreter-v1"

export AGENTICFS_VOLUME_NAME="agent-workspace"

import os
from uuid import uuid4

from e2b import Sandbox


def require_env(name: str) -> str:
    value = os.environ.get(name, "").strip()
    if not value:
        raise RuntimeError(f"缺少环境变量: {name}")
    return value


mount_dir = "/mnt/agenticfs"
marker_path = f"{mount_dir}/hello-agenticfs-{uuid4().hex}.txt"
sandbox = None
marker_written = False

try:
    sandbox = Sandbox.create(
        template=require_env("E2B_TEMPLATE"),
        timeout=300,
        api_key=require_env("E2B_API_KEY"),
        api_url=require_env("E2B_API_URL"),
        domain=require_env("E2B_DOMAIN"),
        volume_mounts={mount_dir: require_env("AGENTICFS_VOLUME_NAME")},
    )

    info = sandbox.get_info()
    print(f"volume_mounts={info.volume_mounts}")

    sandbox.files.write(marker_path, "hello agenticfs\n")
    marker_written = True
    content = sandbox.files.read(marker_path)
    if content != "hello agenticfs\n":
        raise RuntimeError(f"文件内容不一致: {content!r}")
finally:
    try:
        if sandbox is not None and marker_written:
            sandbox.files.remove(marker_path)
    finally:
        if sandbox is not None:
            sandbox.kill()

print("AgenticFS Volume 挂载读写验证成功")

python 02_mount_agenticfs_volume.py

行为说明

• volume_mounts 使用 {挂载目录: Volume 名称} 格式，不使用 Volume ID。

• Sandbox 暂停后再恢复时会恢复 Volume 挂载。

• 释放 Sandbox 不会删除 AgenticFS 中的数据。测试文件由示例主动删除，其他数据的保留和清理需单独处理。

• 本文复用 Volume 的 mountConfig.vpcConfig。需要覆盖时，可在创建 Sandbox 的 metadata 中通过 fc.sandbox.network.vpc 提供完整 VPC 配置；两处均配置时，以 metadata 为准。

使用限制

• 同一 Sandbox 中最多支持 5 个 AgenticFS 挂载点。数量包含创建时和后续追加的挂载，也包含直接提供存储配置的挂载。

• 挂载目录必须是规范化的绝对 Unix 路径，不能为 /，不能包含前后空格、重复分隔符、. 或 .. 路径段。

• 挂载目录不能使用 /bin、/opt、/var、/dev 等系统目录及其子目录，也不能包含 .cache 等以 . 开头的隐藏目录。

• 如需通过隐藏目录访问挂载内容，可先挂载到符合要求的目录，再使用 ln -s 创建指向该挂载目录的符号链接。

• 同一 Sandbox 中的挂载目录不能重复。

• 挂载目录最大长度为 128 个字符。

• 创建 Sandbox 时，多个 AgenticFS Volume 的 userID 和 groupID 配置必须一致。追加挂载时，新增挂载的 UID（User ID，用户 ID）/GID（Group ID，用户组 ID）不得与当前 Sandbox 已有配置冲突。

常见问题