Create an OSS Agentic Bucket and a Bucket Space - Object Storage Service

Creating an Agentic Bucket and a Bucket Space is a prerequisite for using Agentic Bucket. This topic describes how to create an Agentic Bucket via the console, and how to create a Bucket Space under the Agentic Bucket by using the console, the OSS API, or an OSS SDK.

Prerequisites

Important

The Agentic Bucket feature is available only in the China (Hangzhou), China (Beijing), and Japan (Tokyo) regions. Before you use the feature, submit a ticket to apply for activation.

You have activated OSS.
If you use a Resource Access Management (RAM) user to perform the operations, the RAM user is granted the permissions that are required for Agentic Bucket operations. For information about how to grant permissions to a RAM user, see RAM Policy.
If you create a Bucket Space by calling an API operation or by using an OSS SDK, you have created an AccessKey pair to sign OSS API requests. The OSS SDK samples in this topic read the credentials from environment variables.

Procedure

Naming — The full name of an Agentic Bucket consists of the name prefix that you specify and the -{UID}-{region}-ab-apsr suffix that the system automatically appends. The full name of a Bucket Space consists of the name prefix and the -{UID}-{region}-bs-apsr suffix. In both suffixes, {UID} is your Alibaba Cloud account ID.

Naming rules — The name prefix must be at least 3 characters in length and can contain only lowercase letters, digits, and hyphens. The name prefix cannot start or end with a hyphen. The full name, including the automatically appended suffix, cannot exceed 63 characters in length. Because the length of the suffix varies with the Alibaba Cloud account ID and the region, the maximum length available for the name prefix varies accordingly. For example, if the Alibaba Cloud account ID is 1234567890123456 and you enter my-agentic as the name prefix of an Agentic Bucket in the China (Hangzhou) region, the full name of the Agentic Bucket after creation is my-agentic-1234567890123456-cn-hangzhou-ab-apsr.

Access to a Bucket Space — The standard OSS Internet endpoint of a Bucket Space cannot be accessed directly. To access a Bucket Space, you must first bind a custom wildcard domain name to the Agentic Bucket, and then access the Bucket Space by using a domain name in the format {bucketspace-name}.{base wildcard domain name}.

Step 1: Create an Agentic Bucket

The parameters that you configure when you create an Agentic Bucket serve as a template for the Bucket Spaces that are subsequently created under the Agentic Bucket. These parameters include the storage class, redundancy type, ACL, versioning, server-side encryption, and Block Public Access. After the Agentic Bucket is created, you can modify the template parameters by calling the Agentic Bucket attribute configuration operation. The modifications take effect only for the Bucket Spaces that are created after the modification.

Log on to the OSS console and go to the Agentic Bucket list page.
Click Create Agentic Bucket.

In the Create dialog box, configure the following parameters:

Parameter	Description
Name prefix	Enter the name prefix of the Agentic Bucket. The system automatically appends the `-{UID}-{region}-ab-apsr` suffix to form the full name. The naming rules are described at the beginning of the Procedure section.
Region	Select the region in which the Agentic Bucket resides. Only the regions that are listed in Prerequisites are supported, and the options that are displayed in the console prevail.
Storage class	Select the storage class of the Agentic Bucket. Default value: `Standard`. Valid values: `Standard`, `Infrequent Access`, and `Archive`.
Redundancy type	Select the data redundancy type of the Agentic Bucket. `ZRS` (zone-redundant storage) is recommended by default. Valid values: `ZRS` (zone-redundant storage) and `LRS` (locally redundant storage).
Access control list (ACL)	Select the access control list (ACL) of the Agentic Bucket. Default value: `private`. Valid values: `private`, `public-read`, and `public-read-write`.
Versioning	Specify whether to enable versioning. By default, versioning is disabled. After versioning is enabled, historical versions of the data that is overwritten or deleted in a Bucket Space are retained to prevent accidental deletion and overwriting.
Server-side encryption	Select the server-side encryption method of the Agentic Bucket. Default value: `None`. Valid values: `None`, `AES256`, `SM4`, and `KMS`.
Real-time log query	Specify whether to enable real-time log query. By default, real-time log query is disabled.
Block Public Access	Specify whether to enable Block Public Access. By default, Block Public Access is enabled. After it is enabled, public access to all Bucket Spaces under the Agentic Bucket is blocked.

Click OK.
The Agentic Bucket appears on the Agentic Bucket list page, where you can view its endpoints. The endpoints are in the format {full name}.oss-{region}.aliyuncs.com (Internet endpoint) and {full name}.oss-{region}-internal.aliyuncs.com (internal endpoint). These endpoints are used for the management configuration of the Agentic Bucket itself. You can access the OSS Internet endpoint that corresponds to the Agentic Bucket directly.

Step 2: Create a Bucket Space

A Bucket Space is created under an Agentic Bucket. All configurations of the Bucket Space, such as the storage class, redundancy type, ACL, versioning, server-side encryption, and Block Public Access, can be directly inherited from the Agentic Bucket to which the Bucket Space belongs.

Important

You cannot create a Bucket Space when the Agentic Bucket is in the disabled state.

You can create a Bucket Space in the OSS console, by calling an API operation, or by using an OSS SDK. Use the console to create Bucket Spaces one at a time. Use the API or an SDK to create Bucket Spaces programmatically.

Console

On the Agentic Bucket list page, click the Agentic Bucket that you want to manage to go to its Bucket Space management page.
Click Create Bucket Space.
Configure the name of the Bucket Space. The full name of the Bucket Space ends with -bs-apsr, and the naming constraints are the same as those of an Agentic Bucket. After you confirm the settings, click OK to complete the creation.
The Bucket Space appears in the list of Bucket Spaces under the Agentic Bucket.

API

Call the PutBucket operation. Set Host to the full name of the Bucket Space followed by the OSS endpoint domain name, and specify the Agentic Bucket to which the Bucket Space belongs by using the x-oss-agentic-bucket request header or query parameter. The request does not accept other PutBucket request headers or a request body. The API call can use an internal endpoint if the request is initiated from an internal network environment in the same region, or a custom wildcard domain name (CNAME) that is bound to the Agentic Bucket to which the Bucket Space belongs.

The following sample request specifies the Agentic Bucket in the x-oss-agentic-bucket request header:

PUT / HTTP/1.1
Host: my-agent-sandbox-1234567890123456-cn-hangzhou-bs-apsr.oss-cn-hangzhou-internal.aliyuncs.com
x-oss-agentic-bucket: my-agentic-1234567890123456-cn-hangzhou-ab-apsr
Date: GMT Date
Authorization: SignatureValue

The following sample request specifies the Agentic Bucket in the x-oss-agentic-bucket query parameter:

PUT /?x-oss-agentic-bucket=my-agentic-1234567890123456-cn-hangzhou-ab-apsr HTTP/1.1
Host: my-agent-sandbox-1234567890123456-cn-hangzhou-bs-apsr.oss-cn-hangzhou-internal.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

In the sample requests, Date is the time of the request in GMT format, and Authorization is the signature value that is calculated based on the OSS signature mechanism.

If the Bucket Space is created, 200 OK is returned. Common errors include InvalidBucketName (the name is invalid), AgenticBucketNotFound (the specified Agentic Bucket does not exist), and BucketAlreadyExists (a Bucket Space with the same name already exists).