追加挂载 AgenticFS

AgenticFS 挂载参数

以下字段位于 inlineVolumeMounts.agenticFS 中；选择直接提供配置时，按表中要求填写：

本地挂载目录

mountDir 和 namedVolumeMounts[].path 表示 Sandbox 内的本地挂载目录，与 Access Point 地址中的远端目录分别配置。建议使用 /home、/mnt、/tmp 或 /data 的子目录，目录限制参见使用限制。

直接提供挂载配置

以下示例将 Access Point 指定的目录追加到 /mnt/agenticfs，并验证读写。请确保 RAM 角色和目录权限允许读写。

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

将以下代码保存为 append_agenticfs.py，确认 mount_dir 未被已有挂载占用：

import os
from uuid import uuid4

import httpx
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


def verify_read_write(sandbox: Sandbox, mount_dir: str) -> None:
    marker_path = f"{mount_dir}/mount-check-{uuid4().hex}.txt"
    expected = f"append mount check {uuid4().hex}\n"
    sandbox.files.write(marker_path, expected)
    try:
        content = sandbox.files.read(marker_path)
        if content != expected:
            raise RuntimeError(f"文件内容校验失败: {marker_path}")
    finally:
        sandbox.files.remove(marker_path)
    print(f"读写校验通过，测试文件已删除: {mount_dir}")


api_key = require_env("E2B_API_KEY")
api_url = require_env("E2B_API_URL").rstrip("/")
domain = require_env("E2B_DOMAIN")
sandbox_id = require_env("SANDBOX_ID")
mount_dir = "/mnt/agenticfs"

payload = {
    "inlineVolumeMounts": {
        "agenticFS": {
            "mountPoints": [{
                "serverAddr": require_env("AGENTICFS_SERVER_ADDR"),
                "mountDir": mount_dir,
            }],
        },
    },
}

response = httpx.post(
    f"{api_url}/sandboxes/{sandbox_id}/fc-volume-mounts",
    headers={"X-API-Key": api_key},
    json=payload,
    timeout=120.0,
)
if response.status_code != 204:
    raise RuntimeError(f"追加挂载失败: HTTP {response.status_code}, {response.text}")

sandbox = Sandbox.connect(
    sandbox_id,
    timeout=300,
    api_key=api_key,
    api_url=api_url,
    domain=domain,
)

verify_read_write(sandbox, mount_dir)

运行示例：

python append_agenticfs.py

示例未设置 userID 和 groupID。新增挂载的 UID/GID 不得与当前 Sandbox 已有配置冲突。此要求也适用于按名称引用 Volume 的追加挂载。远端子目录的配置说明参见动态挂载 AgenticFS。

引用已有 Volume

已有 AgenticFS Volume 时，首次运行前将上述脚本中的 payload 定义替换为以下内容，其他代码保持不变。请将 name 替换为同一 Team 中的 Volume 名称，读写校验要求该 Volume 允许读写。

payload = {
    "namedVolumeMounts": [{
        "name": "agenticfs-workspace",
        "path": mount_dir,
    }],
}

以上两种方式选择一种运行。同一个挂载目录不能重复追加；挂载已成功但校验失败时，只需重新执行连接和验证代码，不要再次提交追加请求。

直接配置与引用 Volume 组合使用时，将两种配置放入同一个请求体，并为每个挂载点指定不同的本地挂载目录。引用 Volume 的完整操作和多卷示例参见追加挂载 Volume。

请求被 API Key 策略拒绝

错误消息为 request is not allowed by API key policy 时，检查 API Key 策略是否允许本次挂载方式和存储类型，参见API Key 管理。这类拒绝发生在接口授权阶段，调整存储 RAM 角色不能解决。

按名称挂载时提示找不到 Volume

核对请求中的 Volume 名称、API Key 所属 Team 和 API 地址的地域，确认使用同一 Team 中的 Volume 名称，而非 Volume ID。详细说明参见追加挂载 Volume。

按名称挂载时提示 Volume 不可用

通过 GetVolume 查询 Volume 的状态和状态原因，确认处于可用状态后再挂载；存在失败原因时，先处理该原因。详细说明参见追加挂载 Volume。

追加挂载提示 Sandbox 未运行

错误消息为 sandbox must be running 时，确认目标 Sandbox 已进入 running 状态。已暂停的 Sandbox 需先恢复运行；已释放的 Sandbox 需重新创建。

追加挂载提示缺少 RAM 角色

错误消息包含 FC Function execution Role is required，表示当前 Sandbox 未配置所需的 RAM 角色。追加接口沿用当前角色，不会从新增 Volume 的 mountConfig.role 为 Sandbox 设置角色。

需要准备具备目标存储访问权限的角色，并在重新创建 Sandbox 时配置。具体方法参见创建 RAM 角色。

追加挂载提示 Sandbox 的 VPC 配置不完整

错误消息包含 FC Function complete VPC configuration is required 时，缺少配置的是当前 Sandbox。追加请求或新增 Volume 的 mountConfig.vpcConfig 不会补齐它。

需要在重新创建 Sandbox 时配置完整的 vpcId、securityGroupId 和非空 vSwitchIds。创建时可直接通过 metadata 提供，或在引用 Volume 时使用该 Volume 保存的 VPC 配置。

追加挂载提示 UID/GID 冲突

错误消息包含 requested storage UID/GID conflicts with the active FC Session 时，新增挂载指定的 UID/GID 与当前 Sandbox 已有配置冲突。

直接提供配置时，核对 inlineVolumeMounts.agenticFS.userID 和 groupID；引用 Volume 时，核对该 Volume 的 UID/GID 配置。使用与当前 Sandbox 兼容的配置；需要使用不同身份配置时，应另行创建 Sandbox。

追加挂载提示目录重复

错误消息包含 duplicate mount path 或 duplicate mount dir 时，检查本次请求内是否有重复的本地挂载目录，以及目录是否已被 Sandbox 中的其他挂载占用。不同存储类型也不能共用同一个本地挂载目录。

已有挂载无需再次提交；新增挂载应使用未占用的目录。追加接口不能覆盖或替换已有挂载。

本次只追加一个挂载点，为什么仍提示数量超限

挂载数量按 Sandbox 中已有和本次新增的挂载累计计算，直接配置和引用 Volume 的挂载都需计入。不能只检查本次请求的数量。

按本文使用限制核对相应存储类型的挂载数量。达到上限时，可将新增存储挂载到另一个 Sandbox；更换本地挂载目录不会减少已有挂载数量。

若问题仍未解决，或接口提示服务暂时不可用，请保留完整错误信息和请求 ID，联系产品支持。