Function Compute：掛載 AgenticFS Volume

前提條件

• 已為目標 Team 建立 AgenticFS Volume，並擷取 Volume 名稱。

• 已準備綁定同一 Team 的雲沙箱 API Key。Volume 和 API Key 不能跨 Team 使用。

• 已準備與 AgenticFS Access Point 網路連通的 VPC、vSwitch 和安全性群組。

• 已準備函數執行 RAM Role。該 Role 具備 AgenticFS 掛載和讀寫權限，且信任策略允許Function Compute服務扮演。

• 已準備雲沙箱 API URL、Domain 和可用模板。

注意：建立 Sandbox 前，必須確保對應的 AgenticFS Access Point 處於 active 狀態，否則 createSandbox 調用可能逾時或失敗。您可以登入 AgenticFS 控制台，找到對應的 FileSystem，進入 FileSystem 詳情頁面，然後單擊掛載使用查看掛載點狀態。

配置許可權

請將以下權限原則授予函數執行 RAM Role：

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "nas:ClientMount",
        "nas:ClientWrite",
        "nas:ClientRootAccess"
      ],
      "Resource": "*"
    }
  ]
}

該 Role 的信任策略還必須允許Function Compute服務扮演。相關配置參見權限原則及樣本。

安裝 SDK

本文使用 Python E2B SDK 示範。volume_mounts 需要 E2B Python SDK 2.31.0 或以上版本。

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>.e2b.fc.aliyuncs.com"
export E2B_DOMAIN="<region>.e2b.fc.aliyuncs.com"
export E2B_TEMPLATE="code-interpreter-v1"

export AGENTICFS_VOLUME_NAME="agent-workspace"
export FCSANDBOX_VPC_ID="vpc-xxxxxxxx"
export FCSANDBOX_SECURITY_GROUP_ID="sg-xxxxxxxx"
export FCSANDBOX_VSWITCH_ID="vsw-xxxxxxxx"
export FCSANDBOX_ROLE_ARN="acs:ram::<account-id>:role/<execution-role>"

掛載並驗證

以下樣本將 AgenticFS Volume 掛載到 /mnt/agenticfs，並驗證檔案讀寫。將代碼儲存為 02_mount_agenticfs_volume.py：

import json
import os

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


vpc_config = {
    "vpcId": require_env("FCSANDBOX_VPC_ID"),
    "securityGroupId": require_env("FCSANDBOX_SECURITY_GROUP_ID"),
    "vSwitchIds": [require_env("FCSANDBOX_VSWITCH_ID")],
}

mount_dir = "/mnt/agenticfs"
marker_path = f"{mount_dir}/hello-agenticfs.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")},
        metadata={
            "fc.sandbox.network.vpc": json.dumps(vpc_config),
            "fc.sandbox.auth.role": require_env("FCSANDBOX_ROLE_ARN"),
        },
    )

    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 掛載，AgenticFS 資料不依賴 Sandbox 生命週期。

使用限制

• 建立 Sandbox 時，fc.sandbox.network.vpc 必須包含 vpcId、securityGroupId 和非空的 vSwitchIds。模板中的 VPC 配置不能替代該 metadata。

• 同一個 Sandbox 最多掛載 5 個 AgenticFS Volume。

• 同一個 Sandbox 掛載多個 AgenticFS Volume 時，各 Volume 的 user_id 和 group_id 必須完全一致。

• 掛載目錄最大長度為 128 個字元，必須是正常化的絕對 Unix 路徑，不能為 /，不能包含前後空格或 ..。

• 同一個 Sandbox 中的掛載目錄不能重複。建議使用 /mnt/agenticfs 或其子目錄，避免覆蓋模板內已有目錄。

常見問題