追加挂载 AgenticBucket

AgenticBucket 挂载参数

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

本地挂载目录

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

直接提供挂载配置

以下示例将 BucketSpace 的根目录追加到 /mnt/agentic-bucket，并设置 readOnly=False 以验证读写。请确认 RAM 角色也具备对应存储的读写权限。

export AGENTIC_BUCKET_NAME="<AGENTIC-BUCKET-FULL-NAME>"
export BUCKET_SPACE_NAME="<BUCKET-SPACE-FULL-NAME>"
export OSS_ENDPOINT="https://oss-<REGION>-internal.aliyuncs.com"

将以下代码保存为 append_agentic_bucket.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/agentic-bucket"

payload = {
    "inlineVolumeMounts": {
        "agenticBucket": {
            "mountPoints": [{
                "agenticBucket": require_env("AGENTIC_BUCKET_NAME"),
                "bucketName": require_env("BUCKET_SPACE_NAME"),
                "bucketPath": "/",
                "endpoint": require_env("OSS_ENDPOINT"),
                "mountDir": mount_dir,
                "readOnly": False,
            }],
        },
    },
}

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_agentic_bucket.py

引用已有 Volume

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

payload = {
    "namedVolumeMounts": [{
        "name": "agentic-bucket-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 角色。

追加挂载提示目录重复

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

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

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

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

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

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