概述
AgentCFS 是腾讯云文件存储(CFS)面向 Agent 沙箱场景推出的共享存储能力,可为大量 Agent 沙箱提供可共享、安全隔离、休眠态可达的数据底座。本文介绍如何从零创建 AgentCFS 文件系统、创建并启动挂载了该文件系统的 Agent 沙箱,并在沙箱内验证存储挂载。
说明:
本文示例中的
AKIDxxxx、SKxxxx、cfs-xxxxxxxx、subnet-xxx、sg-xxx、<UIN>、e2b_xxxxxxxx 等均为占位符,请替换为您自己的真实值。前提条件
已获取腾讯云 API 密钥(
SecretId / SecretKey),用于调用创建模板、启动沙箱等 API,获取方式请参见 访问秘钥管理。若通过 E2B SDK 启动沙箱,需额外准备
e2b_ 前缀的 API Key(与腾讯云 API 密钥不同,请勿混用),获取方式请参见 创建与查看 API Key。文件系统、沙箱模板与沙箱实例的部署地域需保持一致。
操作步骤
步骤1:创建 AgentCFS 文件系统
2. 配置基础信息与存储类型。

配置项 | 说明 |
文件系统名称 | 输入64位以内的名称,支持中文、字母、数字、 _、-。 |
地域 / 可用区 | 选择与沙箱一致的地域和可用区。 |
架构类型 | 选择 Agent 文件系统。 |
存储类型 | 根据业务时延要求选择 Agent CFS 标准型(延迟不敏感的共享空间,适用周期任务、离线分析等)或 Agent CFS 性能型(延迟敏感场景,适用 VibeCoding、在线办公 Agent、客服助手等)。 |
存储量 | 按需设置起步容量:AgentCFS 标准型起步10TiB,AgentCFS 性能型起步20TiB。 |
自动扩容策略 | 可选。开启后达到容量阈值自动扩容,降低容量超额风险。 |
加密 / 标签 | 按需开启加密、添加标签。 |
3. 确认费用后单击立即创建。创建完成后,在文件系统列表中记录文件系统 ID(形如
cfs-xxxxxxxx),后续创建沙箱模板挂载存储时需要使用。步骤2:创建沙箱模板
创建沙箱工具(模板)时挂载步骤1创建的 AgentCFS 文件系统。您可以通过控制台或 API 两种方式创建。
1. 登录 Agent Runtime 控制台,进入 Agent 沙箱 > 沙箱页面,单击新建沙箱工具。

2. 配置沙箱工具信息。

配置项 | 说明 |
基本信息 | 填写工具名称:最长50字符,仅支持字母、数字、分隔符 -,且以字母开头。选择生命周期:选择限时沙箱或常驻沙箱。 |
资源与健康 | 设置 CPU、内存等资源规格。 健康检查可使用推荐配置。 存储配置:单击添加存储配置,存储类型选择 CFS,填写以下信息: 存储类型:选择 CFS。 名称:存储配置名称,将作为后续启动沙箱配置的索引。 文件系统:选择 步骤1 创建的 AgentCFS 文件系统( cfs-xxxxxxxx)。CFS 路径:CFS 内的挂载源路径,默认根目录 /。挂载路径:以 / 开头的绝对路径,不能为根路径 /,不能以 / 结尾(如 /workspace/data)。读写权限:选择读写或只读。 |
镜像与启动 | 填写容器镜像地址、镜像版本(Tag,不填默认 latest)与启动命令。 |
3. 单击确定完成创建。
调用
CreateSandboxTool 接口创建沙箱模板。与标准模板相比,仅需在 StorageMounts 中配置 CFS 挂载:StorageSource.Cfs.FileSystemId:步骤一创建的文件系统 ID。StorageSource.Cfs.Path:CFS 内的挂载源路径,该路径必须在文件系统内已存在。MountPath:挂载到沙箱内的目标路径。import jsonfrom tencentcloud.common import credentialfrom tencentcloud.common.profile.client_profile import ClientProfilefrom tencentcloud.common.profile.http_profile import HttpProfilefrom tencentcloud.ags.v20250920 import ags_client, models# 1) 凭证(使用腾讯云 API 密钥)cred = credential.Credential("AKIDxxxx", "SKxxxx")http = HttpProfile(); http.endpoint = "ags.tencentcloudapi.com"cp = ClientProfile(); cp.httpProfile = httpclient = ags_client.AgsClient(cred, "ap-beijing", cp)# 2) 组装请求req = models.CreateSandboxToolRequest()req.from_json_string(json.dumps({"ToolName": "cfs-sandbox-demo","ToolType": "custom","Persistent": True,"RoleArn": "qcs::cam::uin/<UIN>:roleName/<ROLE>","CustomConfiguration": {"Image": "ccr.ccs.tencentyun.com/qcloud/centos:latest","ImageRegistryType": "personal","Command": ["/envd"],"Ports": [{"Name": "envd", "Port": 49983, "Protocol": "TCP"}],"Resources": {"CPU": "2", "Memory": "4Gi"},"Probe": {"HttpGet": {"Path": "/health", "Port": 49983, "Scheme": "HTTP"},"ReadyTimeoutMs": 30000, "ProbeTimeoutMs": 2000,"ProbePeriodMs": 1000, "SuccessThreshold": 1, "FailureThreshold": 30}},"NetworkConfiguration": {"NetworkMode": "VPC","VpcConfig": {"SubnetIds": ["subnet-xxx"], "SecurityGroupIds": ["sg-xxx"]}},"StorageMounts": [{"Name": "brucetest","StorageSource": {"Cfs": {"FileSystemId": "cfs-xxxxxxxx", "Path": "/"}},"MountPath": "/workspace/data"}]}))# 3) 调用,拿到 ToolIdresp = client.CreateSandboxTool(req)print(resp.to_json_string()) # {"ToolId": "sdt-xxxxxxxx", "RequestId": "..."}
说明:
记录返回的
ToolId 与 ToolName,下一步启动沙箱时需指定带 CFS 挂载的 ToolName。步骤3:启动沙箱
基于步骤2创建的模板启动沙箱实例。您可以通过控制台或 API 两种方式启动。
1. 在沙箱工具详情页的实例列表页签,单击启动实例。

2. 配置启动参数。

配置项 | 说明 |
基本信息 | 确认工具 ID / 名称,设置 AuthMode 与超时时间。 |
镜像与启动 | 确认镜像、版本与启动命令。 |
网络与权限 | 端口配置:放开指定端口的网络通信。 DNS 配置:支持配置指定 DNS 服务的地址,覆盖沙箱默认的 DNS 配置。 |
高级配置 > 存储配置 |
3. 单击确认启动。
E2B SDK 通用、轻量,适合大多数 Agent 运行时集成场景。
import os, jsonfrom e2b_code_interpreter import Sandbox# 1) 环境变量(按 Tool 所在地域填写 domain,使用 e2b_ 前缀的 key)os.environ["E2B_DOMAIN"] = "ap-beijing.tencentags.com"os.environ["E2B_API_KEY"] = "e2b_xxxxxxxx"# 2) template = 步骤二创建的带 CFS 挂载的 ToolNamesbx = Sandbox.create(template="cfs-sandbox-demo",timeout=3600, # 沙箱存活秒数,到期自动回收metadata={"x-mounts": json.dumps([{"name": "brucetest", # 必需:匹配工具配置的存储名称"mountPath": "/workspace/data", # 可选:沙箱内挂载路径"readOnly": False, # 可选:读写权限"subPath": "user-123" # 可选:文件系统内子路径,需已存在}])},)print("sandbox_id =", sbx.sandbox_id)# 3) 在沙箱内执行命令,务必 user="root" 才能访问挂载点res = sbx.commands.run("df -hT /workspace/data; touch /workspace/data/hello && echo WRITE-OK",user="root",)print(res.stdout)
注意:
template 需填写 Tool 的 ToolName,而非 ToolId(sdt-xxxxxxxx)。连接已存在的持久化沙箱请使用
Sandbox.connect("<sandbox_id>"),不要重复 create。腾讯云 Python SDK 走 AGS 原生接口
CreateSandbox,与创建模板使用同一套凭证/SDK,适合已深度使用腾讯云 SDK 的平台侧集成。import jsonfrom tencentcloud.common import credentialfrom tencentcloud.common.profile.client_profile import ClientProfilefrom tencentcloud.common.profile.http_profile import HttpProfilefrom tencentcloud.ags.v20250920 import ags_client, models# 1) 凭证(与创建模板同一套腾讯云 API 密钥)cred = credential.Credential("AKIDxxxx", "SKxxxx")http = HttpProfile(); http.endpoint = "ags.tencentcloudapi.com"cp = ClientProfile(); cp.httpProfile = httpclient = ags_client.AgsClient(cred, "ap-beijing", cp)# 2) 基于步骤二创建的 Tool 启动沙箱req = models.CreateSandboxRequest()req.from_json_string(json.dumps({"ToolName": "cfs-sandbox-demo","TimeoutSeconds": 3600,"StorageMounts": [{"Name": "brucetest","MountPath": "/workspace/data","SubPath": "user-123","ReadOnly": False}]}))# 3) 调用,拿到 SandboxIdresp = client.CreateSandbox(req)print(resp.to_json_string()) # {"SandboxId": "...", "RequestId": "..."}
说明:
拿到
SandboxId 后,后续在沙箱内执行命令仍走 E2B 通道(Sandbox.connect(SandboxId)),命令执行同样需 user="root" 才能访问挂载点。步骤4:登录沙箱验证存储
沙箱启动后,可登录实例验证 AgentCFS 是否挂载成功。
1. 在实例列表中找到运行中的实例,单击登录实例进入沙箱终端。
2. 执行
df -h 查看挂载情况,可看到 AgentCFS 已挂载到指定路径(如 /workspace/data)。
3. 在挂载路径下执行读写操作(如
touch /workspace/data/hello),确认存储可正常读写。(可选)通过 TurboS3 在休眠态访问数据
当沙箱处于休眠 / 暂停等非运行状态时,若仍需查看、上传、下载对应数据,可为文件系统开启 TurboS3接入点,通过标准 S3接口访问数据,使数据访问与沙箱生命周期解耦。
以下为在 VPC 内使用 boto3访问 TurboS3的最小连通性示例:
import boto3from botocore.client import Configimport urllib3; urllib3.disable_warnings()s3 = boto3.client("s3",endpoint_url="https://<您的S3域名>", # 创建 S3 服务后获取的内网域名region_name="ap-beijing",aws_access_key_id="AKIDxxxx", # 腾讯云 API 密钥aws_secret_access_key="SKxxxx",config=Config(signature_version="s3v4",s3={"addressing_style": "virtual"}), # 必须用 virtual模式,hostpath有域名风险verify=False,)# 连通性自检与基本读写print([b["Name"] for b in s3.list_buckets()["Buckets"]]) # 列出桶s3.put_object(Bucket="cfs-xxxxxxxx", Key="demo/hello.txt", Body=b"hello turbos3\\n") # 写print(s3.get_object(Bucket="cfs-xxxxxxxx", Key="demo/hello.txt")["Body"].read()) # 读
注意:
TurboS3域名仅在您指定的 VPC 内生效,须在该 VPC 内的沙箱或主机上访问,并放通 TCP 443。
boto3客户端务必使用 virtualhost(
addressing_style="virtual")常见问题
创建模板时提示挂载路径不存在
StorageMounts 中的 Path 必须是文件系统内已存在的路径。请先确认该目录已创建,或使用根目录 /。接口鉴权失败
创建模板与启动沙箱(腾讯云 SDK 方式)使用腾讯云 API 密钥;通过 E2B SDK 启动沙箱使用
e2b_ 前缀的 key,两者请勿混用。沙箱内访问挂载点权限不足
在沙箱内执行命令时须指定
user="root",例如 sbx.commands.run(..., user="root")。沙箱内 pip 安装依赖超时
该 VPC 通常无公网出口,请改用内网源:
pip install -i http://mirrors.tencentyun.com/pypi/simple --trusted-host mirrors.tencentyun.com <包名>。SDK 执行长任务超时(deadline_exceeded)
对于耗时较长的命令,使用
sbx.commands.run(..., background=True) 后台执行,再轮询日志文件获取结果。