Function Compute:Create an AgenticFS Volume

CreateVolume only creates Volume metadata. It does not create, delete, or copy AgenticFS data.

Prerequisites

For AgenticFS product concepts, see What is AgenticFS. Related resources are created and managed in the NAS console.

Before you begin, prepare the following:

• Volumes are in invited preview. Submit an Alibaba Cloud support ticket to request access.

• A Team has been created in the FC Agent Sandbox console, and the Team ID has been obtained.

• An AgenticFS FileSystem, AgenticSpace, and Access Point have been created, and the Access Point address has been obtained. The root directory address format is as follows:

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

• The Alibaba Cloud identity that calls the POP (Public Open Platform) SDK has the fcsandbox:CreateVolume permission. Querying Volumes requires fcsandbox:ListVolumes and fcsandbox:GetVolume, and deleting Volumes requires fcsandbox:DeleteVolume.

Note: Before you create a sandbox, make sure that the corresponding AgenticFS Access Point is in the active state. Otherwise, the createSandbox call may time out or fail. Log on to the AgenticFS console, find the corresponding FileSystem, open the FileSystem details page, and then click Mount Usage to check the status of the mount point.

To create a Team and obtain the Team ID, see Create a Team.

Permission configuration

The RAM identity that calls the Volume API needs the following permissions. Replace the placeholders:

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

In production, Volume resources can be granted precisely at Team scope:

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

Install the SDK

The FC Agent Sandbox OpenAPI currently supports Java, Python, Go, and TypeScript SDKs. For the scope of support, installation, and versioning, see Alibaba Cloud SDK and API Guide. This document uses Python for demonstration purposes.

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

Before running the example, set the following environment variables:

export ALIBABA_CLOUD_ACCESS_KEY_ID="<your-access-key-id>"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="<your-access-key-secret>"
# When using an STS temporary credential, also set:
# 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"

Replace the Access Point address and Volume name with your actual values.

The 1000/1000 values in the example are the UID and GID of the default sandbox user and group. When using a custom template, set them according to the actual runtime user of the template.

FCSANDBOX_ENDPOINT does not include https://. If the SDK already ships with a built-in endpoint for the target region, this variable can be omitted; the SDK resolves it based on FCSANDBOX_REGION_ID.

Create an AgenticFS Volume

For request parameters, response parameters, and error codes, see CreateVolume - Create a Volume on the OpenAPI portal.

The following example creates an AgenticFS Volume and prints the result. Save the code as 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"missing environment variable: {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 did not return a 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 created")

Run the example:

python 08_create_agenticfs_volume.py

Successful creation only means that the Volume metadata has been created. See Mount an AgenticFS Volume to mount the Volume into a sandbox and verify the mount by reading and writing files.

Mount a subdirectory under an Access Point

You can set server_addr directly to a subdirectory under an Access Point.

1. Call CreateVolume with the subdirectory address to create the target Volume.

2. Create a sandbox and mount the Volume by name. If the remote subdirectory does not exist, the system automatically creates it on the first mount.

3. Read and write files directly in the mounted directory to confirm that the Volume is usable.

Example server_addr of the target Volume:

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

CreateVolume only creates Volume metadata. The AgenticFS data plane becomes available only after the mount succeeds and reads and writes are complete. The subdirectory path cannot contain whitespace characters, control characters, repeated separators, ., or .., and cannot end with /.

The following example mounts a subdirectory under an Access Point and verifies file reads and writes.

Before you run the example, set the environment variables listed above, and configure the sandbox environment variables by following Mount an AgenticFS Volume. The example generates a unique subdirectory under the Access Point root directory specified by AGENTICFS_SERVER_ADDR.

Save the following code as 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"missing environment variable: {name}")
    return value


access_point_addr = require_env("AGENTICFS_SERVER_ADDR")
if not access_point_addr.endswith(":/"):
    raise RuntimeError("AGENTICFS_SERVER_ADDR must be an Access Point root address ending with :/")

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 did not return a Volume")

    volume = response.body.volume
    print(
        f"Volume metadata created: volume_name={volume.volume_name}, "
        f"server_addr={server_addr}; the AgenticFS data plane has not been accessed yet"
    )

    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"file content mismatch: {content!r}")

    print(f"AgenticFS subdirectory mount read/write verification succeeded: {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),
            )

Run the example:

python 09_mount_agenticfs_subdir.py

Manage Volumes

Use ListVolumes to list Volumes, GetVolume to view details, and DeleteVolume to delete a Volume that is no longer needed.

Deleting a Volume only removes its mount configuration from FC Agent Sandbox. It does not delete AgenticFS resources or their data.

Limits

• server_addr must be an AgenticFS Access Point address. Regular NAS mount addresses or URLs with protocol prefixes are not allowed.

• server_addr is limited to 128 characters.

• Volume names must be unique within a Team.

FAQ