帮你快速理解、总结文档立即下载
文档中心>对象存储>智能体存储>快速入门

快速入门

最近更新时间：2026-07-13 17:47:33

我的收藏

本页目录：

简介

腾讯云智能体桶（COS Agent Bucket）作为一项面向 AI Agent 与多用户场景的新型存储桶，简化了构建多用户云空间的难度。本文介绍从开通服务到首次完成文件上传与下载的完整流程，包含四个主要步骤：创建智能体桶、创建空间、上传文件、查看用量与下载分享。

准备工作

开通 COS 服务

在 腾讯云控制台 中，搜索对象存储，进入对象存储控制台，按照界面提示开通 COS 服务。如果您已开通，请跳过该步骤。

开通 SMH 服务

智能体桶的底层服务由腾讯云智能媒资托管提供支持。使用前请进入 智能媒资托管控制台，开通 SMH 服务。

服务角色授权

首次新建智能体桶时，需授权服务关联角色 SMH_QCSLinkedRoleCOS 访问您的 COS 资源。请前往 角色管理页面 完成授权。

完成 Python SDK 的配置

部分示例中使用了 Python SDK 执行相关操作，因此需要提前完成 SDK 的环境配置与准备。智能体桶跟 COS 使用相同的 SDK，请参考 COS Python SDK 的 快速入门。

操作步骤

步骤1：创建智能体桶

我们需要创建一个用于 AI Agent 或多租户场景的存储桶。
1. 在 对象存储控制台 左侧导航栏中单击存储桶列表，进入存储桶列表页。
2. 选择智能体桶列表页签，单击创建智能体桶，可选添加备注信息用于业务标识，例如 agent-bucket-demo。
3. 点击确认创建，即创建成功。

步骤2：创建空间

智能体桶创建成功后，需要在桶内创建空间（Space），用于承载单个 Agent 实例或终端用户的数据。
1. 在 对象存储控制台 左侧导航栏中单击存储桶列表，进入存储桶列表页。
2. 选择智能体桶列表页签，单击刚才创建的存储桶，进入桶详情页。
3. 单击空间管理页签，进入空间列表页。
4. 单击创建空间，输入以下配置信息，其他配置保持默认即可。
空间 ID：支持英文字母和数字，1~32个字符。
配额：设置该空间的存储配额，例如5GB，留空表示不限制配额。
备注：可选，用于业务标识，例如 user-001 或 agent-instance-A。
5. 单击确认创建即创建完成。

步骤3：上传文件

智能体桶完全兼容 COS 协议，文件路径按 <SpaceID>/<ObjectKey> 组织。当前可使用控制台、REST API 或 COS SDK 完成文件上传。
说明：
智能体桶上传文件的控制台操作入口：空间管理的空间详情页面，单击上传文件按钮。
SpaceId: 对应 ObjectKey 一级目录，需要预先通过 PUT Object 接口上传大小为空的一级目录对象来创建对应的 SpaceId。
ObjectKey：对应 Space 下的对象路径。
以 Python SDK 为例，演示如何向指定空间上传文件。关于 put_object 方法的字段参数说明，请参考 PUT Object API 文档。
# -*- coding=utf-8 -*-
import os
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client

# 1. 设置用户属性
secret_id = os.getenv("COS_SECRET_ID")     # 用户的 SecretId
secret_key = os.getenv("COS_SECRET_KEY")   # 用户的 SecretKey
region = 'ap-chengdu'                      # 智能体桶所在地域
scheme = 'https'

config = CosConfig(
    Region=region,
    SecretId=secret_id,
    SecretKey=secret_key,
    Scheme=scheme,
)
client = CosS3Client(config)

# 2. 上传文件到指定空间
# Key 格式为 <SpaceID>/<ObjectKey>
# Body 为对象内容
response = client.put_object(
    Bucket='smh3km4897kxxxxx-12596xxxxx',
    Key='sp-001abc/avatar.png',            
    Body=open('./avatar.png', 'rb'),
)
print(response['ETag'])

步骤4：查看用量与下载分享

完成文件上传后，可在控制台或通过 SDK 查看空间用量、下载文件或生成分享外链。

查看用量

控制台操作指引如下：
进入桶详情页"概览"页签，可查看相关数据：
总空间数：当前桶下空间总数。
总存储量：所有空间存储量之和。
总文件数：所有空间文件数之和。
基本信息：名称、地域、访问域名等信息。

下载分享

下面以 Python SDK 为例，演示如何下载指定空间内的文件并获取分享外链。
# -*- coding=utf-8 -*-
import os
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client

secret_id = os.getenv("COS_SECRET_ID")
secret_key = os.getenv("COS_SECRET_KEY")
region = 'ap-chengdu'
scheme = 'https'

config = CosConfig(
    Region=region,
    SecretId=secret_id,
    SecretKey=secret_key,
    Scheme=scheme,
)
client = CosS3Client(config)

# 下载文件到本地
response = client.get_object(
    Bucket='smh3km4897kxxxxx-12596xxxxx',
    Key='sp-001abc/avatar.png',
)
response['Body'].get_stream_to_file('./avatar-downloaded.png')

中国站