动态挂载 AgenticBucket

功能介绍

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

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

适用范围

AgenticBucket 的产品说明和资源管理方式参见AgenticBucket 概述。

• 已创建 AgenticBucket，并获取完整名称。

• 已确定要使用的 BucketSpace 完整名称。BucketSpace 无需预先创建；首次挂载时如果不存在，系统会自动创建。

• 已获取 AgenticBucket 所在地域的 OSS Endpoint。同地域访问建议使用内网 Endpoint，例如 https://oss-<REGION>-internal.aliyuncs.com，不需要额外配置 VPC（Virtual Private Cloud，专有网络）。

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

• 已准备 RAM（Resource Access Management，访问控制）角色，其信任策略允许函数计算服务扮演该角色，并具备目标存储所需的访问权限。角色配置方法参见配置 RAM 角色，存储权限策略参见创建 AgenticBucket Volume。

安装 SDK

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

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

挂载配置

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

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

{
  "mountPoints": [
    {
      "agenticBucket": "<AGENTIC-BUCKET-FULL-NAME>",
      "bucketName": "<BUCKET-SPACE-FULL-NAME>",
      "mountDir": "/mnt/agentic-bucket",
      "bucketPath": "/",
      "endpoint": "https://oss-<REGION>-internal.aliyuncs.com",
      "readOnly": false
    }
  ]
}

bucketName 使用 BucketSpace 完整名称，bucketPath 选择其下的路径。需要只读访问时，将 readOnly 设置为 true。

智能体沙箱通过 RAM 角色获取 STS（Security Token Service，安全令牌服务）临时凭证，无需关闭 AgenticBucket 的 BlockPublicAccess，也无需在挂载配置中提供长期 AK/SK。挂载配置不会扩大 RAM 角色的授权范围。

环境变量说明

挂载并验证

先设置环境变量，替换示例中的占位符；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 AGENTIC_BUCKET_NAME="<AGENTIC-BUCKET-FULL-NAME>"
export BUCKET_SPACE_NAME="<BUCKET-SPACE-FULL-NAME>"
export OSS_ENDPOINT="https://oss-<REGION>-internal.aliyuncs.com"
export SANDBOX_ROLE_ARN="acs:ram::<ACCOUNT-ID>:role/<ROLE-NAME>"

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

将以下代码保存为 11_sandbox_agentic_bucket.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/agentic-bucket"
marker_path = f"{mount_dir}/hello-agentic-bucket-{uuid4().hex}.txt"
agentic_bucket_config = {
    "mountPoints": [
        {
            "agenticBucket": require_env("AGENTIC_BUCKET_NAME"),
            "bucketName": require_env("BUCKET_SPACE_NAME"),
            "mountDir": mount_dir,
            "bucketPath": "/",
            "endpoint": require_env("OSS_ENDPOINT"),
            "readOnly": False,
        }
    ]
}

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.agenticbucket": json.dumps(agentic_bucket_config),
            "fc.sandbox.auth.role": require_env("SANDBOX_ROLE_ARN"),
        },
    )

    sandbox.files.write(marker_path, "hello agentic bucket\n")
    marker_written = True
    content = sandbox.files.read(marker_path)
    if content != "hello agentic bucket\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("AgenticBucket 动态挂载读写验证成功")

运行示例：

python 11_sandbox_agentic_bucket.py

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

行为说明

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

使用限制

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

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

• 同一个 Sandbox 中的本地挂载目录不能重复，该限制跨存储类型生效。

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

常见问题