文件存储 在 AgentSandbox 沙箱中使用 AgentCFS

一、概述

注意：说明：

二、前提条件

·已 注册腾讯云账号，并具备文件存储（CFS）操作权限，授权方式请参见 访问管理 。

·已获取腾讯云 API 密钥（SecretId / SecretKey），用于调用创建模板、启动沙箱等 API，获取方式请参见 访问秘钥管理。

·若通过 E2B SDK 启动沙箱，需额外准备 e2b_ 前缀的 API Key（与腾讯云 API 密钥不同，请勿混用），获取方式请参见 创建与查看 API Key。

·文件系统、沙箱模板与沙箱实例的部署地域需保持一致。

三、步骤1：创建 AgentCFS 文件系统

1. 登录 文件存储控制台，单击新建，进入 新建文件系统 页面。

2. 配置基础信息与存储类型。

3. 确认费用后单击立即创建。创建完成后，在文件系统列表中记录文件系统 ID（形如 cfs-xxxxxxxx），后续创建沙箱模板挂载存储时需要使用。

四、步骤2：创建沙箱模板

创建沙箱工具（模板）时挂载步骤1创建的 AgentCFS 文件系统。你可以通过控制台或 API 两种方式创建。

方式一：控制台创建方式二：API 创建

1. 登录 Agent Runtime 控制台，进入 Agent 沙箱 > 沙箱页面，单击新建沙箱工具。

2. 配置沙箱工具信息。

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 两种方式启动。

方式一：控制台启动方式二：E2B SDK 启动方式三：腾讯云 SDK 启动

1. 在沙箱工具详情页的实例列表页签，单击启动实例。

2. 配置启动参数。

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)

腾讯云 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有域名风险)# 连通性自检与基本读写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 接入点的创建、完整接口支持范围与更多用法，请参见 TurboS3接入点操作指南、TurboS3使用限制。

八、创建模板时提示挂载路径不存在

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) 后台执行，再轮询日志文件获取结果。