Function Compute：建立 AgenticFS Volume

CreateVolume 只建立 Volume 中繼資料，不會建立、刪除或複製 AgenticFS 資料。

前提條件

AgenticFS 的產品說明參見什麼是 AgenticFS。相關資源在 NAS 控制台建立和管理。

使用前需要準備：

• Volume 目前仍處於邀測階段，需要提交阿里雲工單申請開通。

• 已在Function Compute雲沙箱控制台建立 Team，並擷取 Team ID。

• 已建立 AgenticFS FileSystem、AgenticSpace 和 Access Point，並擷取 Access Point 地址。根目錄地址格式如下：

  ap-<access-point-id>.<file-system-id>-<suffix>.<region>.nas.aliyuncs.com:/

• 調用 POP SDK 的阿里雲身份具備 fcsandbox:CreateVolume 許可權；查詢 Volume 需要 fcsandbox:ListVolumes 和 fcsandbox:GetVolume 許可權；刪除 Volume 還需要 fcsandbox:DeleteVolume 許可權。

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

Team 的建立和 Team ID 擷取方式參見建立 Team。

許可權配置

建立Volume所需RAM帳號許可權

調用 Volume API 的 RAM 身份需要以下許可權，請替換預留位置：

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "fcsandbox:CreateVolume",
        "fcsandbox:ListVolumes",
        "fcsandbox:GetVolume",
        "fcsandbox:DeleteVolume"
      ],
      "Resource": "*"
    }
  ]
}

生產環境支援按 Team 精確授權 Volume 資源：

acs:fcsandbox:<region>:<account-id>:teams/<team-id>/volumes/*

沙箱動態掛載RAM角色要求的權限

為 Volume 中配置的 RAM 角色添加以下權限原則：

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

安裝 SDK

雲沙箱 OpenAPI 當前支援 Java、Python、Go 和 TypeScript SDK。支援範圍、安裝方式和版本以阿里雲 SDK & API 說明為準。本文使用 Python 示範。

python3 -m venv .venv
source .venv/bin/activate
pip install "alibabacloud_fcsandbox20260509>=1.3.0"

運行樣本前設定以下環境變數：

export ALIBABA_CLOUD_ACCESS_KEY_ID="<your-access-key-id>"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="<your-access-key-secret>"
# 使用 STS 臨時憑證時還需要設定：
# export ALIBABA_CLOUD_SECURITY_TOKEN="<your-security-token>"

export FCSANDBOX_REGION_ID="cn-hangzhou"
export FCSANDBOX_ENDPOINT="fcsandbox.cn-hangzhou.aliyuncs.com"
export FCSANDBOX_TEAM_ID="<team-id>"

export AGENTICFS_SERVER_ADDR="ap-<access-point-id>.<file-system-id>-<suffix>.<region>.nas.aliyuncs.com:/"
export AGENTICFS_VOLUME_NAME="agent-workspace"
export AGENTICFS_USER_ID="1000"
export AGENTICFS_GROUP_ID="1000"

請將 Access Point 地址和 Volume 名稱替換為實際值。

樣本中的 1000/1000 是 Sandbox 預設使用者和使用者組的 UID/GID。使用自訂模板時，請按模板中的實際運行使用者佈建。

FCSANDBOX_ENDPOINT 不包含 https://。如果 SDK 已內建目標地區的 Endpoint，可以不設定該變數，由 SDK 根據 FCSANDBOX_REGION_ID 解析。

建立 AgenticFS Volume

請求參數、返回參數和錯誤碼以 OpenAPI 門戶的 CreateVolume - 建立 Volume 為準。

以下樣本建立 AgenticFS Volume 並輸出建立結果。將代碼儲存為 08_create_agenticfs_volume.py：

import os

from alibabacloud_fcsandbox20260509 import models
from alibabacloud_fcsandbox20260509.client import Client as FCSandboxClient
from alibabacloud_tea_openapi import models as open_api_models


def require_env(name: str) -> str:
    value = os.environ.get(name, "").strip()
    if not value:
        raise RuntimeError(f"缺少環境變數: {name}")
    return value


config = open_api_models.Config(
    access_key_id=require_env("ALIBABA_CLOUD_ACCESS_KEY_ID"),
    access_key_secret=require_env("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
    security_token=os.environ.get("ALIBABA_CLOUD_SECURITY_TOKEN"),
    region_id=require_env("FCSANDBOX_REGION_ID"),
)
if os.environ.get("FCSANDBOX_ENDPOINT"):
    config.endpoint = os.environ["FCSANDBOX_ENDPOINT"]

pop_client = FCSandboxClient(config)
team_id = require_env("FCSANDBOX_TEAM_ID")

response = pop_client.create_volume(
    models.CreateVolumeRequest(
        body=models.CreateVolumeInput(
            team_id=team_id,
            volume_name=require_env("AGENTICFS_VOLUME_NAME"),
            agentic_fsvolume_config=models.AgenticFSVolumeConfig(
                server_addr=require_env("AGENTICFS_SERVER_ADDR"),
                user_id=int(require_env("AGENTICFS_USER_ID")),
                group_id=int(require_env("AGENTICFS_GROUP_ID")),
            ),
        )
    )
)

if response.body is None or response.body.volume is None:
    raise RuntimeError("CreateVolume 未返回 Volume")

volume = response.body.volume
print(f"request_id={response.body.request_id}")
print(f"volume_id={volume.volume_id}")
print(f"volume_name={volume.volume_name}")
print(f"storage_class={volume.storage_class}")
print(f"status={volume.status}")

print("AgenticFS Volume 建立成功")

運行樣本：

python 08_create_agenticfs_volume.py

建立成功僅表示 Volume 中繼資料建立成功。參見掛載 AgenticFS Volume將該 Volume 掛載到 Sandbox，並通過實際讀寫確認掛載可用。

掛載 Access Point 下的子目錄

server_addr 可以直接指定 Access Point 下的子目錄。

1. 使用子目錄地址調用 CreateVolume 建立目標 Volume。

2. 建立 Sandbox 並按 Volume 名稱掛載。若遠端子目錄不存在，系統會在首次掛載時自動建立。

3. 直接在掛載目錄中讀寫檔案，確認 Volume 可用。

目標 Volume 的 server_addr 樣本：

ap-<access-point-id>.<file-system-id>-<suffix>.<region>.nas.aliyuncs.com:/project-a

CreateVolume 僅建立 Volume 中繼資料；掛載成功並完成讀寫後，才表示 AgenticFS 資料面可用。子目錄路徑不能包含空白字元、控制字元、重複分隔字元、. 或 ..，也不能以 / 結尾。

以下樣本掛載 Access Point 下的子目錄並驗證檔案讀寫。

運行前，設定上文列出的環境變數，並按照掛載 AgenticFS Volume配置 Sandbox 環境變數。樣本會在 AGENTICFS_SERVER_ADDR 指定的 Access Point 根目錄下產生唯一子目錄。

將以下代碼儲存為 09_mount_agenticfs_subdir.py：

import json
import os
import uuid

from alibabacloud_fcsandbox20260509 import models
from alibabacloud_fcsandbox20260509.client import Client as FCSandboxClient
from alibabacloud_tea_openapi import models as open_api_models
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


access_point_addr = require_env("AGENTICFS_SERVER_ADDR")
if not access_point_addr.endswith(":/"):
    raise RuntimeError("AGENTICFS_SERVER_ADDR 必須是以 :/ 結尾的 Access Point 根目錄地址")

suffix = uuid.uuid4().hex[:12]
subdir = f"project-a-{suffix}"
volume_name = f"agenticfs-subdir-{suffix}"
server_addr = f"{access_point_addr}{subdir}"
mount_dir = "/mnt/agenticfs"
marker_path = f"{mount_dir}/hello-agenticfs.txt"

config = open_api_models.Config(
    access_key_id=require_env("ALIBABA_CLOUD_ACCESS_KEY_ID"),
    access_key_secret=require_env("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
    security_token=os.environ.get("ALIBABA_CLOUD_SECURITY_TOKEN"),
    region_id=require_env("FCSANDBOX_REGION_ID"),
)
if os.environ.get("FCSANDBOX_ENDPOINT"):
    config.endpoint = os.environ["FCSANDBOX_ENDPOINT"]

pop_client = FCSandboxClient(config)
team_id = require_env("FCSANDBOX_TEAM_ID")
volume = None
sandbox = None
marker_written = False

try:
    response = pop_client.create_volume(
        models.CreateVolumeRequest(
            body=models.CreateVolumeInput(
                team_id=team_id,
                volume_name=volume_name,
                agentic_fsvolume_config=models.AgenticFSVolumeConfig(
                    server_addr=server_addr,
                    user_id=int(require_env("AGENTICFS_USER_ID")),
                    group_id=int(require_env("AGENTICFS_GROUP_ID")),
                ),
            )
        )
    )
    if response.body is None or response.body.volume is None:
        raise RuntimeError("CreateVolume 未返回 Volume")

    volume = response.body.volume
    print(
        f"Volume 中繼資料建立成功: volume_name={volume.volume_name}, "
        f"server_addr={server_addr}; 此時尚未訪問 AgenticFS 資料面"
    )

    vpc_config = {
        "vpcId": require_env("FCSANDBOX_VPC_ID"),
        "securityGroupId": require_env("FCSANDBOX_SECURITY_GROUP_ID"),
        "vSwitchIds": [require_env("FCSANDBOX_VSWITCH_ID")],
    }
    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: volume_name},
        metadata={
            "fc.sandbox.network.vpc": json.dumps(vpc_config),
            "fc.sandbox.auth.role": require_env("FCSANDBOX_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}")

    print(f"AgenticFS 子目錄掛載讀寫驗證成功: {server_addr}")
finally:
    try:
        if sandbox is not None:
            try:
                if marker_written:
                    sandbox.files.remove(marker_path)
            finally:
                sandbox.kill()
    finally:
        if volume is not None:
            pop_client.delete_volume(
                volume.volume_id,
                models.DeleteVolumeRequest(team_id=team_id),
            )

運行樣本：

python 09_mount_agenticfs_subdir.py

管理 Volume

通過 ListVolumes 查詢 Volume 列表，通過 GetVolume 查看詳情，通過 DeleteVolume 刪除不再使用的 Volume。

刪除 Volume 只刪除雲沙箱側的掛載配置，不會刪除 AgenticFS 資源或其中的資料。

使用限制

• server_addr 必須使用 AgenticFS Access Point 地址，不能使用普通 NAS 掛載地址或帶協議首碼的 URL。

• server_addr 當前最大長度為 128 個字元。

• 同一 Team 中的 Volume 名稱不能重複。

常見問題