动态挂载 AgenticFS

功能介绍

创建 Sandbox 时，可以通过 metadata 将 AgenticSpace Access Point 或其子目录挂载到 Sandbox 内，无需预先创建 Volume。挂载后，应用通过本地挂载目录访问数据。

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

适用范围

AgenticFS 的产品说明参见什么是 AgenticFS，相关资源在 NAS 控制台创建和管理。

• 已创建 AgenticFS、AgenticSpace 和启用 RAM（Resource Access Management，访问控制）认证的 AgenticSpace Access Point（以下简称 Access Point），并确认 Access Point 处于 active 状态。

• 已获取 Access Point 地址，例如 ap-<ACCESS-POINT-ID>.<FILE-SYSTEM-ID>-<SUFFIX>.<REGION>.nas.aliyuncs.com:/。

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

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

• 已准备 RAM 角色，信任策略允许函数计算服务扮演，并具备目标存储所需的访问权限。角色创建方法参见创建 RAM 角色，存储权限策略参见创建 AgenticFS Volume。

安装 SDK

创建并激活 Python 虚拟环境，然后安装 E2B SDK：

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

挂载配置

创建 Sandbox 时，在 metadata 中提供以下配置：

创建时直接挂载，需同时通过 fc.sandbox.network.vpc 提供完整 VPC 配置，值为 JSON 字符串。模板或同一请求中 Volume 的 VPC 配置不能替代该 metadata。

fc.sandbox.storage.agenticfs 的 JSON 结构如下。提交时需将其序列化为字符串，不能直接传入 Python 字典或 JavaScript 对象：

{
  "userID": 1000,
  "groupID": 1000,
  "mountPoints": [
    {
      "serverAddr": "ap-<ACCESS-POINT-ID>.<FILE-SYSTEM-ID>-<SUFFIX>.<REGION>.nas.aliyuncs.com:/project-a",
      "mountDir": "/mnt/agenticfs"
    }
  ]
}

metadata 键必须使用全小写的 fc.sandbox.storage.agenticfs。配置中的字段名也区分大小写，必须使用 userID、groupID、serverAddr 和 mountDir。平台自动启用 TLS，不要传入 enableTLS；配置采用严格 JSON 解析，readOnly 等未声明字段会导致请求失败。

环境变量说明

挂载并验证

先设置环境变量，替换示例中的占位符；API 地址、模板和存储需使用匹配的地域及网络配置：

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="<TEMPLATE-ID>"

export AGENTICFS_SERVER_ADDR="ap-<ACCESS-POINT-ID>.<FILE-SYSTEM-ID>-<SUFFIX>.<REGION>.nas.aliyuncs.com:/"
export AGENTICFS_USER_ID="1000"
export AGENTICFS_GROUP_ID="1000"

export SANDBOX_VPC_ID="vpc-xxxxxxxx"
export SANDBOX_SECURITY_GROUP_ID="sg-xxxxxxxx"
export SANDBOX_VSWITCH_ID="vsw-xxxxxxxx"
export SANDBOX_ROLE_ARN="acs:ram::<ACCOUNT-ID>:role/<ROLE-NAME>"

示例会在挂载目录中创建带随机标识的独立测试文件，写入并读取校验后删除该文件，再释放本次创建的 Sandbox。请使用具备读写权限的挂载配置。

将以下代码保存为 12_sandbox_agenticfs.py：

import json
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"
agenticfs_config = {
    "userID": int(require_env("AGENTICFS_USER_ID")),
    "groupID": int(require_env("AGENTICFS_GROUP_ID")),
    "mountPoints": [
        {
            "serverAddr": require_env("AGENTICFS_SERVER_ADDR"),
            "mountDir": mount_dir,
        }
    ],
}
vpc_config = {
    "vpcId": require_env("SANDBOX_VPC_ID"),
    "securityGroupId": require_env("SANDBOX_SECURITY_GROUP_ID"),
    "vSwitchIds": [require_env("SANDBOX_VSWITCH_ID")],
}

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"),
        metadata={
            "fc.sandbox.storage.agenticfs": json.dumps(agenticfs_config),
            "fc.sandbox.network.vpc": json.dumps(vpc_config),
            "fc.sandbox.auth.role": require_env("SANDBOX_ROLE_ARN"),
        },
    )

    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 动态挂载读写验证成功")

运行示例：

python 12_sandbox_agenticfs.py

输出 AgenticFS 动态挂载读写验证成功 表示本次读写、测试文件清理和 Sandbox 释放已完成。

行为说明

释放 Sandbox 不会删除底层存储数据。测试文件由示例主动删除，其他数据的保留和清理需通过存储服务或挂载目录单独处理。

使用限制

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

• 本地挂载目录不能使用 /bin、/opt、/var、/dev 等系统目录及其子目录，也不能包含 .cache 等隐藏目录。如需通过隐藏目录访问数据，可挂载到符合要求的目录后，再创建指向挂载目录的符号链接。

• 同一个 Sandbox 中的本地挂载目录不能重复，包括不同存储类型的挂载目录。

• 同一个 Sandbox 最多包含 5 个 AgenticFS 挂载点，按创建时与后续追加的挂载累计计算，包括直接配置和引用 Volume 的挂载。

• 同一个 Sandbox 中的多个 AgenticFS 挂载点共用同一组 userID 和 groupID：单次挂载配置内的所有挂载点共用该组取值，追加挂载指定的 UID/GID 也不得与当前 Sandbox 已有配置冲突。

常见问题