创建 AgenticFS Volume

AgenticFS Volume 保存已有 AgenticSpace Access Point 的挂载配置。创建完成后，可以在创建 Sandbox 时按 Volume 名称挂载。

CreateVolume 只创建 Volume 元数据，不会创建、删除或复制 AgenticFS 数据。

前提条件

AgenticFS 的产品说明参见什么是 AgenticFS。相关资源在 NAS 控制台创建和管理。

使用前需要准备：

Volume 目前仍处于邀测阶段，需要提交阿里云工单申请开通。
已在函数计算云沙箱控制台创建 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 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/*

安装 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 解析。

请求参数、返回参数和错误码以 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 下的子目录。

使用子目录地址调用 CreateVolume 创建目标 Volume。
创建 Sandbox 并按 Volume 名称挂载。若远端子目录不存在，系统会在首次挂载时自动创建。
直接在挂载目录中读写文件，确认 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 名称不能重复。

常见问题

POP SDK 返回 `Forbidden` 错误码

检查调用身份是否具备 fcsandbox:CreateVolume 权限，以及是否有目标 Team 的 Volume 资源权限。

返回 `TeamNotFound` 错误码

检查 Team ID、地域和账号是否匹配。

返回 `CreateVolumeNotSupported` 或 `NotFound` 错误码

确认当前账号、地域和 Team 已开通 Volume 与 AgenticFS 能力。

返回 `InvalidParameter` 错误码

根据 CreateVolume API 文档检查 Access Point 地址和请求参数。

返回 `VolumeConflict` 错误码

同一 Team 中已存在同名 Volume。可通过 ListVolumes 查询 Volume 列表，通过 GetVolume 查看详情。确认不再使用后，通过 DeleteVolume 删除，或更换 Volume 名称。

前提条件

权限配置

安装 SDK