Introduction
The Tencent Cloud COS Agent Bucket, a new bucket type designed for AI Agent and multi-user scenarios, simplifies the process of building multi-user cloud spaces. This document describes the complete workflow from service activation to the first successful file upload and download. The workflow consists of four main steps: creating an Intelligent Agent Bucket, creating a space, uploading files, and viewing usage and downloading/sharing files.
Preparations
Enabling COS Service
In the Tencent Cloud console, search for Object Storage and go to the COS console. Then, activate the COS service by following the on-screen instructions. If you have already activated the service, skip this step. Enabling SMH Service
The underlying service of the Agent Bucket is powered by Tencent Cloud Smart Media Hosting (SMH). Before using it, go to the SMH console to activate the SMH service. Granting Permissions to the Service Role
When you create an Agent Bucket for the first time, you must grant the service-linked role SMH_QCSLinkedRoleCOS access to your COS resources. Go to the Role Management page to complete the authorization. Configuring the Python SDK
Some examples use the Python SDK to perform operations. Therefore, you must complete the environment configuration and preparation for the SDK in advance. The Agent Bucket uses the same SDK as COS. For details, see the Quick Start guide for the COS Python SDK. Operation Steps
Step 1: Creating an Agent Bucket
We need to create a bucket for AI Agent or multi-tenant scenarios.
1. In the left sidebar of the COS console, click Bucket List to go to the Bucket List page. 2. Select the Agent Bucket List tab, click Create Agent Bucket, and optionally add remarks for business identification, for example, agent-bucket-demo.
3. Click Confirm to complete the creation.
Step 2: Creating a Space
After an Agent Bucket is created, you must create a Space within the bucket to host data for a single Agent instance or end user.
1. In the left sidebar of the COS console, click Bucket List to go to the Bucket List page. 2. Select the Agent Bucket List tab, click the bucket you just created, and go to the bucket details page.
3. Click the Space Management tab to go to the Space List page.
4. Click Create Space, enter the following configuration information, and keep the default settings for other configurations.
Space ID: It supports letters and numbers and must be 1 to 32 characters in length.
Quota: Set the storage quota for this space, for example, 5GB. Leaving it blank indicates no quota limit.
Remarks: Optional. It is used for business identification, for example, user-001 or agent-instance-A.
5. Click Confirm Creation to complete the creation.
Step 3: Uploading Files
The Agent Bucket is fully compatible with the COS protocol, and file paths are organized as <SpaceID>/<ObjectKey>. Currently, you can use the console, REST API, or COS SDK to upload files.
Note:
Console operation entry for uploading files to an Agent Bucket: On the Space Details page in Space Management, click the Upload File button.
SpaceId: It corresponds to the first-level directory of an ObjectKey. To create the corresponding SpaceId, you must first upload an empty first-level directory object using the PUT Object API.
ObjectKey: The object path under the corresponding Space.
Using the Python SDK as an example, this section demonstrates how to upload files to a specified space. For descriptions of the field parameters of the put_object method, see the PUT Object API documentation.
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.put_object(
Bucket='smh3km4897kxxxxx-12596xxxxx',
Key='sp-001abc/avatar.png',
Body=open('./avatar.png', 'rb'),
)
print(response['ETag'])
Step 4: Viewing Usage and Downloading Shares
After the file upload is completed, you can view space usage, download files, or generate shareable links in the console or via the SDK.
Viewing Usage
Console operation instructions are as follows:
Go to the Overview tab on the bucket details page to view the relevant data:
Total Spaces: The total number of spaces under the current bucket.
Total Storage: Total storage of all spaces.
Total Files: Total number of files in all spaces.
Basic Information: Name, region, access domain, and other information.
Downloading Files for Sharing
The following example uses the Python SDK to demonstrate how to download files from a specified space and obtain shareable links.
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')