## 一、Agent 时代的存储困境

过去二十年，企业用对象存储（COS）的规矩很简单：一个业务、一个应用，对应一个桶（Bucket），桶里随便放，权限自己管。这套流程用了几十年没出过大乱子，直到 AI Agent 爆发式增长。

传统方案面对海量 Agent 只有两条路，且两条都是死胡同：

- **方案 A：一个 Agent 一个桶。** 干净利落，但云厂商对账号可建桶数量都有上限。Agent 数量一旦冲到几千、几万，桶还没开完，账单和监控先崩。
- **方案 B：所有 Agent 共用一个桶，靠路径前缀区分。** `s3://company-bucket/agent_001/files/...` 看着省事，代价是隔离这道墙全靠业务代码自己砌。权限判断漏一行、路径拼错一个字符，Agent A 就能翻进 Agent B 的目录，安全事故从存储问题变成程序员问题。

Agent 往往攥着比人类更多的自动化权限，一次误读可能就是批量数据事故。

腾讯云给出的第三条路，是在 Bucket 和文件之间插入一个新的逻辑层级——**Space（空间）**，并把隔离、配额、权限、分享、去重、回收站这些"网盘能力"下沉到存储系统本身。

## 二、核心概念：Agent Bucket 与 Space

Agent Bucket（智能体桶）是腾讯云面向 AI Agent 与多租户场景推出的新型存储桶类型，在 COS 标准桶能力基础上新增了 Space 逻辑层与网盘能力。

**Agent Bucket**：一个应用对应一个智能体桶，桶名由系统自动生成（格式 `smh<随机串>-<APPID>`，全局唯一、创建后不可修改），默认跟随 COS 桶规则。

**Space（空间）**：桶内的一级逻辑隔离单元，对应业务概念中的"一个 Agent 实例 / 一个终端用户 / 一个共享盘"。每个 Space 拥有：

- 独立的存储配额（可设上限，留空即不限）
- 独立的读写限速
- 独立的 AccessToken（访问令牌）与权限策略
- 独立的用量统计

单个 Agent Bucket 默认可承载 **1000 万** 个 Space（联系扩容可达 **10 亿**），单个 Space 内可存储 **百亿量级** 文件。在业务侧，"用户空间 / 实例空间 / 共享盘"可以直接映射到这套存储层级，应用层不必再维护多租户表与权限表。

一句话理解：**Bucket 像一栋写字楼的物业合同，Space 像楼里一间间带锁的房间，AccessToken 是钥匙，配额和限速是电表。** 以前要么整栋楼签一份合同太贵太慢，要么所有人把东西堆在大厅用胶带写名字——现在的做法是，一栋楼里开出无数带锁的房间。

```mermaid
flowchart TB
    AB["Agent Bucket<br/>系统自动命名 smh-xxx-APPID<br/>单账号默认 200 个"]
    subgraph G1["Space 01 · 用户/智能体 A"]
        O1["对象：报告/图片/代码/记忆"]
    end
    subgraph G2["Space 02 · 用户/智能体 B"]
        O2["对象：独立凭证+配额+限速"]
    end
    subgraph G3["Space N · 共享空间"]
        O3["公共知识库 / 技能库"]
    end
    AB --- G1
    AB --- G2
    AB --- G3
    style AB fill:#0ea5e9,color:#fff
    style G1 fill:#06b6d4,color:#fff
    style G2 fill:#06b6d4,color:#fff
    style G3 fill:#3b82f6,color:#fff
```

## 三、产品体验：从开通到上传的四步上手

Agent Bucket 完全兼容 COS 协议，可使用现有 SDK 与工具开发，学习成本极低。完整链路只需四步，全部在控制台与 SDK 内完成。

**新用户免费体验6个月**
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/9796a1aa85a7c0f7d4c1882079628849.png)

![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/c5ddc0e078ba27d6f289005e6fb35964.png)

![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/083b682fe5740cd2c906966fd9d9791d.png)

**四步核心流程**

1、**创建智能体桶**：若COS未开通需要先开通COS，然后在控制台左侧"存储桶列表" → 切到"智能体桶列表"标签页 → 点击"创建智能体桶"，可填业务备注（如 `agent-bucket-demo`）。
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/08418928e2209dfde525ed8089d05873.png)
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/3ba4ebc86ade2ced67ff3b8703d547e1.png)
2、**进行授权**：SMH 智能体桶服务角色未授权，然后确认创建。
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/933b0854e437d3eab191574689afeca0.png)
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/ae96d139ed5acf37c3cfe426c1416f83.png)
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/54689f5afb5ab0dc0bb28d534cada35e.png)
3、 **创建空间（Space）**：进入桶详情 → "空间管理" → "创建空间"，填写 Space ID（1–32 位字母数字）、配额（如 1GB，留空不限）、备注（如 `user-001`）。
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/d155a2c28240ee9255adcafa85c8da2d.png)
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/76e91f19f62f22ce24fdc3e373c35dde.png)
4、**上传文件**：控制台、REST API、COS SDK 均可。
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/f036cb335b410f3dd61aaf006d0a9ecc.png)
5、 **查看用量与分享**：桶详情"概览"可看总空间数、总存储量、总文件数。
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/4b7c642e98978cfa2e6ce55db4247e81.png)

![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/1375a022309aa5879fe72e86abc1ebf4.png)

## 四、Web UIKit接入Agent Bucket实践

SMH Web UI Kit​ 是一款基于 React 的开箱即用云盘 UI 组件库。它深度对接腾讯云 SMH（智能媒体托管）服务，开发者仅需传入基础配置与 Token 获取函数，即可在现有应用中快速集成完整的功能，免去从零搭建文件管理前端的繁琐工作。
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/013830c5f511fe8deabeeada1105a8e2.png)

1、进入到SMH控制台在开发者指引中获取密钥，LibraryId、AccessDomain、LibrarySecret。
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/9bfbb1a9f4f0266a436063703103516f.png)
2、此处快速生成一个用于联调的临时 Token，这里设置的有效期是1天。
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/2a03319764d1cbac3c22d257e35668b6.png)
3、在本地构建一个项目。
```
run/
├── backend/                 # 后端 Token 签发服务（持有 librarySecret）
│   ├── server.js
│   ├── package.json
│   └── .env.example
└── frontend/                # React + Vite + smh-web-uikit 
    ├── src/App.jsx
    ├── src/main.jsx
    ├── index.html
    ├── vite.config.js
    ├── package.json
    └── .env.example
```

**server.js**
```JavaScript
// 后端 Token 签发服务（Agent Bucket + SMH Web UIKit）
// 作用：持有 librarySecret，向前端签发 space_admin 级别的短时 accessToken
// ⚠️ librarySecret 绝不能出现在前端代码或返回给浏览器的任何响应里

// 加载 .env（必须在读取 process.env 之前）。无 .env 时静默跳过，回退到占位符。
require('dotenv').config();

const express = require('express');

// ===== 改成你的真实值（或改用环境变量注入）=====
const LIBRARY_ID = process.env.SMH_LIBRARY_ID || 'smhxxxxxxxxxxxxx';       // 桶名 smh<id> 段
const LIBRARY_SECRET = process.env.SMH_LIBRARY_SECRET || 'your_library_secret'; // 仅后端持有
const BASE_PATH = process.env.SMH_BASE_PATH || 'https://smhxxxxxxx.api.tencentsmh.cn'; // SMH 专属域名
// =========================================================

const app = express();

// 允许前端跨端口（Vite 默认 5173）直连本后端，无需额外代理
app.use((req, res, next) => {
  res.header('Access-Control-Allow-Origin', '*');
  res.header('Access-Control-Allow-Methods', 'POST, GET, OPTIONS');
  res.header('Access-Control-Allow-Headers', 'Content-Type');
  if (req.method === 'OPTIONS') return res.sendStatus(204);
  next();
});

app.use(express.json());

// 前端调用的统一入口
app.post('/api/generate-space-token', async (req, res) => {
  const { spaceId } = req.body;
  if (!spaceId) return res.status(400).json({ error: 'spaceId required' });

  const params = new URLSearchParams({
    library_id: LIBRARY_ID,
    library_secret: LIBRARY_SECRET, // ⚠️ 仅后端持有，绝不下发前端
    Grant: 'space_admin',           // 本空间内最大权限
    Period: '7200',                 // 过期时间 2 小时
    spaceId,
  });

  try {
    const response = await fetch(`${BASE_PATH}/api/v1/token?${params}`);
    const tokenData = await response.json();
    if (!tokenData.accessToken) {
      return res.status(502).json({ error: 'SMH token failed', raw: tokenData });
    }
    res.json({
      accessToken: tokenData.accessToken,
      expiresAt: Date.now() + 2 * 60 * 60 * 1000, // 毫秒级时间戳
    });
  } catch (e) {
    res.status(500).json({ error: String(e) });
  }
});

app.listen(3000, () => console.log(`Token server → http://localhost:3000  (lib=${LIBRARY_ID})`));

```
**App.jsx**
```JavaScript
import React, { useCallback, useState } from 'react';
import { SpaceDrive } from 'smh-web-uikit';

// ===== 配置：优先读 Vite 环境变量（.env），否则用占位值 =====
// 创建 .env 写入：VITE_BASE_PATH=...  VITE_LIBRARY_ID=...  VITE_SPACE_ID=...
export const BASE_PATH =
  import.meta.env.VITE_BASE_PATH || 'https://smhxxxxxxx.api.tencentsmh.cn';
export const LIBRARY_ID =
  import.meta.env.VITE_LIBRARY_ID || 'smhxxxxxxxxxxxxx'; // 桶名 smh<id> 段
export const SPACE_ID =
  import.meta.env.VITE_SPACE_ID || 'space-xxxxx'; // 你的 Agent Bucket Space（必须真实存在）

// Token 后端地址（与 backend/server.js 路由一致）
const TOKEN_ENDPOINT = 'http://localhost:3000/api/generate-space-token';

export default function App() {
  // 把 Token 错误显式显示在页面上，避免"空白页无从排查"
  const [tokenError, setTokenError] = useState(null);

  // getAccessToken：必须用 useCallback 保持引用稳定，
  // 否则组件会因函数变化反复重新初始化（官方"注意事项"）。
  const getAccessToken = useCallback(async (spaceId = SPACE_ID) => {
    try {
      const res = await fetch(TOKEN_ENDPOINT, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ spaceId }),
      });
      if (!res.ok) {
        const err = await res.json().catch(() => ({}));
        const detail = err?.raw?.code || err?.error || `HTTP ${res.status}`;
        throw new Error(`Token 签发失败 [${detail}]`);
      }
      const data = await res.json();
      setTokenError(null);
      return {
        accessToken: data.accessToken,
        expiresAt: data.expiresAt, // 支持毫秒/秒级时间戳、ISO8601、Date
      };
    } catch (e) {
      setTokenError(e.message);
      throw e; // 继续向上抛，让 SpaceDrive 知道初始化失败
    }
  }, []);

  return (
    <div style={{ height: '100vh', width: '100vw' }}>
      {tokenError && (
        <div
          style={{
            background: '#fef2f2',
            color: '#b91c1c',
            borderBottom: '1px solid #fecaca',
            padding: '12px 16px',
            font: '14px/1.6 system-ui, sans-serif',
          }}
        >
          <strong>⚠️ 无法加载云盘：</strong>
          {tokenError}
          <br />
          排查：① 后端 <code>node server.js</code> 是否在 3000 端口运行；②
          <code>VITE_SPACE_ID</code>（当前={SPACE_ID}）是否在 SMH / Agent Bucket 库里<strong>真实存在</strong>；
          ③ <code>VITE_LIBRARY_ID / VITE_BASE_PATH</code> 是否正确。
        </div>
      )}
      <SpaceDrive
        basePath={BASE_PATH}
        libraryId={LIBRARY_ID}
        spaceId={SPACE_ID}
        getAccessToken={getAccessToken}
        title="Agent Bucket 云盘"
        uiMode="full"
        enableRecycleBin
        enableSearch
      />
    </div>
  );
}

```
**main.jsx**
```JavaScript
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App.jsx';

// 引入 SMH Web UIKit 全局样式（路径以实际安装版本为准）
import 'smh-web-uikit/dist/style.css';

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
);

```
3、进入`cd run/backend`，执行`npm install`
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/d4e91217765e2f135707f05ea6cc654f.png)
4、`cp .env.example .env  `，编辑.env填入实际值。
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/f0de743ff196bbe9863a5a905aa4668c.png)
5、启动后端，`npm start `，成功如下图所示。
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/df0303edb182cdec93074b775a0565d8.png)
6、先手动验证后端能签 Token（不开前端也能测）：
```TXT
curl -X POST http://localhost:3000/api/generate-space-token \
  -H "Content-Type: application/json" \
  -d '{"spaceId":"space-xxxxx"}'
```
成功返回如下：
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/b6bd6c1189a6201bf32f7d8ade6644e5.png)
7、新开一个终端，输入`cd run/frontend`，然后再执行`npm install `
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/09285667e77abb6981e110847ea58dff.png)
8、`cp .env.example .env`  ，然后编辑 .env，填入 basePath / libraryId / spaceId（不含 secret）
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/1e4482aa18c148bf6f1ab87a29385232.png)
9、启动前端，`npm run dev`，成功显示如下。
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/c465dda5bccb2efd48a3e4a3f6aef917.png)
10、打开浏览器验证，访问 `http://localhost:5173/`。页面应渲染出 SMH 云盘界面（标题 "Agent Bucket 云盘"），自动用后端签发的 `space_admin` Token 拉取该 Space 的文件列表。
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/f2a977ff12f319210791a5cb983931d3.png)
可以看到和云端上内容一致。
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/2a7448872f4260d4480a0021e93d86da.png)
11、在本地上传一个文件。
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/68d60331ce9968db06e5cccd298a7d64.png)

![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/966b0d7d7f0236e75c8615f18ddb6596.png)

上传成功后在 Agent Bucket 控制台也有了这个文件。
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/f24cce382efe8152fbc943011014fb43.png)
说明**两层接口打通**：Web UIKit（SMH 治理层）↔ 后端 Token 服务 ↔ 我的 Agent Bucket Space。

**关键注意**

- **`librarySecret` 仅后端**：任何人拿到它都能签任意 Space 的 Token，务必收好。
- **`getAccessToken` 引用要稳定**：本例用 `useCallback` 包裹，避免组件反复重新初始化。
- **卸载清理**：真实项目里组件卸载建议调 `clearConfig()` 防内存泄漏（本最小样例未做卸载处理）。
- **分享/预览/回收站**：这些能力由 SMH 治理层提供，需 SMH 侧 `adminEnabled` 与 `ownerEnabled` 均为开启状态才能用；Web UIKit 只是把它们做成了前端入口。
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/2333dc7968c982db980b0aeb0641f32c.png)
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/219fc9901e60fef97cf2300140c24e63.png)
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/1539d605acade6a7e87211be102501c8.png)
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/760333b605d9d7c5573e495208e6d9d0.png)
- **回收站删除**：文件在删除之后Agent Bucket空间管理显示没有了，但文件数不变；只有在回收站彻底删除之后文件数才会减少，才会释放总存储量。
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/3d5988a67835aa85bcdbef9824e4716c.png)
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/06ccb7bdb77d5af22a65900733754151.png)
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/27bf87410d241fd569770c6759646d38.png)
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/ff54561eb4b4b575dcda2bf56bd2d5bf.png)
## 五、应用场景：三类落地范式

**1. AI Agent 云空间。** 为每个 Agent 实例分配独立 Space，或多人创建项目共享 Space，存放 Agent 操作的中间结果、用户上传文件、AI 生成的报告/图片/代码。
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/8611f295f052da55fcff44ab25e37f7f.png)

**2. 网盘 / 相册应用。** 企业面向终端用户提供个人存储时，为每个终端用户创建一个 Space。
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/1f19eb1fc09cf313cfe4d439a1597395.png)
**3. 企业共享空间。** 企业内部同时存在"公共资产沉淀"与"员工私域数据"两类需求。
![image.png](https://developer.qcloudimg.com/http-save/yehe-7617106/3d7a65a1e6e42107388b2d04882c03c9.png)

## 六、最佳实践：把方案做对而非做快

| 维度 | 反模式 | 推荐做法 |
|------|--------|----------|
| 空间命名 | 用中文/特殊字符、超 32 位 | SpaceId 仅字母数字、1–32 位，建议 `user-<id>` / `agent-<id>` 可回溯 |
| 凭证管理 | 主账号密钥直接下发 Agent | 子用户最小权限 + 独立 AccessToken，用完即销 |
| 配额权益 | 全部留空不限 | 按等级设配额/限速，VIP 与基础用户差异化，支撑商业化结算 |
| 去重成本 | 忽视全局去重 | 复用同一份源文件，跨空间秒传命中，存储成本压一大块 |
| 误删兜底 | 依赖备份恢复 | 启用回收站，Agent 产物误删可找回，不依赖整库回滚 |


**Agent Bucket 把"多租户隔离 + 网盘能力"下沉到对象存储系统层**，开发者用标准 S3 接口即可为亿级 Agent 快速搭建原生独立空间，无需自研多租户表与权限校验代码。**降低的是"从零自建多租户文件空间"的成本，而非消灭所有架构选择**。对数据必须自控、或坚持多云统一抽象的团队，继续自建依然合理。




过去二十年，企业用对象存储（COS）的规矩很简单：一个业务、一个应用，对应一个桶（Bucket），桶里随便放，权限自己管。这套流程用了几十年没出过大乱子，直到 AI Agent 爆发式增长。

腾讯云 Agent Bucket 实战：从开通到 Web UIKit 接入跑通

Agent Bucket 把"多租户隔离 + 网盘能力"下沉到对象存储系统层**，开发者用标准 S3 接口即可为亿级 Agent 快速搭建原生独立空间，无需自研多租户表与权限校验代码。

云计算

人工智能

架构设计

腾讯云推出AgentBucket智能体桶，创新引入Space逻辑层解决AI Agent海量存储隔离难题。在Bucket与文件间新增独立配额、限速、权限的空间隔离单元，单桶支持千万级Space，百亿级文件。兼容COS协议，配合WebUIKit快速搭建网盘能力，实现多租户数据安全管控，降低自研成本。

代码解释

对象存储

智能体

多云

路由

Agent

ReAct 

Solid

JSON

Vite

对象存储COS新用户低至1元！


热销域名限时优惠，新客首年免费！


domain

让每一个 Agent，都跑在云上

lexiang

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

腾讯云 Agent Bucket 实战：从开通到 Web UIKit 接入跑通-腾讯云开发者社区-腾讯云

腾讯云 Agent Bucket 实战：从开通到 Web UIKit 接入跑通

腾讯云 Agent Bucket 实战：从开通到 Web UIKit 接入跑通

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐