帮你快速理解、总结文档立即下载

创建 Record

最近更新时间:2026-11-20 19:48:53
我的收藏

1. 接口描述

接口请求域名: ags.tencentcloudapi.com 。

统一创建 Registry Record(含 revision 1)。MCPSource / AgentSource / SkillSource / CustomDescriptors / FileSource 五选一,必须与 DescriptorType 对应。PLUGIN 使用 FileSource.Type=FILE 上传通用文件,Registry 不校验插件内容格式和语义,运行端负责解析和加载。SupportedHarnessVersions 为该版本支持的 HarnessVersionReference 对象列表,每项同时包含 HarnessEngine 和 HarnessEngineVersion,原样使用 DescribeHarnessEngineList 返回的选项;Metadata 为 Name/Value 字符串数组,Name 非空、小写且唯一,服务内部保存 map[string]string;两项属性省略时均保存空列表,不继承其他版本。不接受 RecordId 或 ChangeLog;同名 Record 返回冲突,不隐式追加 Version。追加 Version 请使用 UpdateRegistryRecord。

默认接口请求频率限制:20次/秒。

推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见 公共请求参数。

参数名称 必选 类型 描述
Action 是 String 公共参数,本接口取值:CreateRegistryRecord。
Version 是 String 公共参数,本接口取值:2025-09-20。
Region 是 String 公共参数,详见产品支持的 地域列表,本接口仅支持其中的: ap-beijing, ap-chongqing, ap-guangzhou, ap-shanghai 。
RegistryId 是 String

所属 Registry ID。


示例值:reg-0123abcd
Name 是 String

Record 名称,长度 1..255,同一租户、Registry 内按规范化 Name 唯一(大小写不敏感);软删除后允许复用。


示例值:example-plugin
DescriptorType 是 String

资产类型。取值包括 MCP、A2A、AGUI、CUSTOM、AGENT_SKILLS 和 PLUGIN。Record 创建后不可修改。PLUGIN 按通用文件资产保存,由运行端解析和加载。


示例值:PLUGIN
Description 否 String

Record 描述,最大 4096 字符,可选,默认空。


示例值:示例 Plugin 文件资产
VersionName 否 String

Revision 1 的展示名称,可选。


示例值:1.0.0
MCPSource 否 CloudMCPSourceInput

DescriptorType=MCP 时必填,其他类型禁止。

AgentSource 否 CloudAgentSourceInput

DescriptorType=A2A 或 AGUI 时必填,其他类型禁止。

SkillSource 否 CloudSkillSourceInput

DescriptorType=AGENT_SKILLS 时必填,其他类型禁止。

CustomDescriptors 否 String

DescriptorType=CUSTOM 时必填,其他类型禁止。内容必须是 JSON object 字符串;服务端解析后写入 CloudRecordVersion.Descriptors,Version 的 SourceType 固定为 MANUAL、SourceConfig 固定为空对象。


示例值:{"vendor":"example","capability":"order-query"}
FileSource 否 CloudFileSourceInput

Plugin 通用文件来源。DescriptorType=PLUGIN 时必填,其他类型禁止。

入参限制:Create 仅支持 Type=FILE;声明 SizeBytes 为 1..54525952 字节,可选 SHA256 为 64 位小写十六进制摘要。

Registry 保存原始文件,不校验插件内容格式或语义;由运行端解析和加载。Skill 继续使用原 SkillSource。

SupportedHarnessVersions.N 否 Array of HarnessVersionReference

本版本支持的 HarnessVersionReference 对象列表;每项包含 HarnessEngine 和 HarnessEngineVersion,原样使用 DescribeHarnessEngineList 返回的选项。

入参限制:两个字段均必填,各为 1 至 128 字符的精确值,区分大小写,不含空白、通配符或版本范围;最多 128 项,按引擎与版本二元组去重。不接受旧字符串数组、null、缺少字段或额外字段。

省略或空数组表示未声明,不继承前一版本,不代表支持所有 Harness。兼容性按同一对象的引擎与版本共同判断。修改兼容声明需创建新 Version,文件资产可通过 FileSource.Type=VERSION 复用制品。

Metadata.N 否 Array of MetadataEntry

版本元数据的 Name/Value 对象数组。

参数格式:每项仅包含必填的 Name、Value 两个字符串字段。Name 非空、小写且数组内唯一,不自动转换;重复 Name 即使 Value 相同也返回 InvalidParameter。Value 允许空字符串,保留大小写;不接受嵌套对象、数组或非字符串值。

默认值:空数组 []。创建新版本时省略或 [] 均为空,不继承;null、JSON 字符串和原生对象非法。响应按 Name 升序返回,旧 SQL NULL 归一为 []。服务内部使用 map[string]string,数据库 JSON 列保存对象。publisher 表示发布者展示名称;metadata.<key> 按完整小写名称精确筛选,规则不变。

3. 输出参数

参数名称 类型 描述
RecordId String

新 Record ID。


注意:此字段可能返回 null,表示取不到有效值。
示例值:rec-0123abcd
Record CloudRecord

新建的 Record 详情。

Version CloudRecordVersion

本次创建的 Revision 1 Version 详情。

UploadURL String

文件上传预签名 URL。使用文件上传方式创建 Skill 或 Plugin 版本时返回;Plugin 文件使用 application/octet-stream 上传。


注意:此字段可能返回 null,表示取不到有效值。
示例值:https://example.com/uploads/example-plugin.bin?signature=example
ExpireTime String

文件上传链接的过期时间,使用文件上传方式创建 Skill 或 Plugin 版本时返回。

参数格式:ISO 8601 UTC,例如 2026-10-21T15:30:08Z。


注意:此字段可能返回 null,表示取不到有效值。
示例值:2030-01-01T00:15:00Z
ContentStatus String

文件版本的内容状态,使用文件上传方式创建 Skill 或 Plugin 版本时返回。创建上传会话后通常为 UPLOADING;文件处理完成后为 READY,失败为 FAILED。


注意:此字段可能返回 null,表示取不到有效值。
示例值:UPLOADING
RequestId String 唯一请求 ID,由服务端生成,每次请求都会返回(若请求因其他原因未能抵达服务端,则该次请求不会获得 RequestId)。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 创建 MCP URL_IMPORT 版本

参数示意;资源 ID、账号、时间、摘要及 example.com URL 为示例,不对应真实资源,请替换后调用。

输入示例

POST / HTTP/1.1
Host: ags.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateRegistryRecord
<公共请求参数>

{
    "RegistryId": "reg-0123abcd",
    "Name": "example-mcp",
    "Description": "示例 MCP 服务",
    "DescriptorType": "MCP",
    "VersionName": "1.0.0",
    "MCPSource": {
        "Type": "URL_IMPORT",
        "EndpointURL": "https://example.com/mcp"
    },
    "Metadata": [
        {
            "Name": "publisher",
            "Value": "示例发布者"
        }
    ]
}

输出示例

{
    "Response": {
        "RequestId": "00000000-0000-4000-8000-000000000001",
        "RecordId": "rec-0123abcd",
        "Record": {
            "RecordId": "rec-0123abcd"
        },
        "Version": {
            "VersionId": "rv-0123abcd",
            "Revision": 1,
            "Status": "PENDING_APPROVAL",
            "SupportedHarnessVersions": [],
            "Metadata": [
                {
                    "Name": "publisher",
                    "Value": "示例发布者"
                }
            ]
        }
    }
}

示例2 创建 Plugin 文件版本

参数示意;资源 ID、账号、时间、摘要及 example.com URL 为示例,不对应真实资源,请替换后调用。

输入示例

POST / HTTP/1.1
Host: ags.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateRegistryRecord
<公共请求参数>

{
    "RegistryId": "reg-0123abcd",
    "Name": "example-plugin",
    "Description": "示例 Plugin 文件资产",
    "DescriptorType": "PLUGIN",
    "VersionName": "1.0.0",
    "FileSource": {
        "Type": "FILE",
        "SizeBytes": 1
    },
    "SupportedHarnessVersions": [
        {
            "HarnessEngine": "pi",
            "HarnessEngineVersion": "1.3.0"
        }
    ],
    "Metadata": [
        {
            "Name": "publisher",
            "Value": "示例发布者"
        }
    ]
}

输出示例

{
    "Response": {
        "RequestId": "00000000-0000-4000-8000-000000000001",
        "RecordId": "rec-0123abcd",
        "Record": {
            "RecordId": "rec-0123abcd",
            "RegistryId": "reg-0123abcd",
            "Name": "example-plugin",
            "Description": "示例 Plugin 文件资产",
            "DescriptorType": "PLUGIN",
            "LifecycleStatus": "ACTIVE",
            "AppId": 1250000000,
            "CreatorUin": "100000000001",
            "CreatorSubAccountUin": "100000000002",
            "VersionCount": 1,
            "LabelSet": [
                "latest"
            ],
            "CreateTime": "2030-01-01T00:00:00Z",
            "UpdateTime": "2030-01-01T00:00:00Z"
        },
        "Version": {
            "VersionId": "rv-0123abcd",
            "RecordId": "rec-0123abcd",
            "Revision": 1,
            "VersionName": "1.0.0",
            "ChangeLog": "首次发布",
            "Descriptors": "{\"name\": \"example-plugin\", \"description\": \"示例 Plugin 文件资产\"}",
            "SourceType": "FILE",
            "SourceConfig": "{\"Type\":\"FILE\",\"SizeBytes\":1}",
            "Status": "PREPARING",
            "ApprovalMode": "MANUAL",
            "ConfigSHA256": "",
            "LabelSet": [],
            "SupportedHarnessVersions": [
                {
                    "HarnessEngine": "pi",
                    "HarnessEngineVersion": "1.3.0"
                }
            ],
            "Metadata": [
                {
                    "Name": "publisher",
                    "Value": "示例发布者"
                }
            ],
            "AppId": 1250000000,
            "CreatorUin": "100000000001",
            "CreatorSubAccountUin": "100000000002",
            "CreateTime": "2030-01-01T00:00:00Z",
            "UpdateTime": "2030-01-01T00:00:00Z",
            "ContentStatus": "UPLOADING"
        },
        "ContentStatus": "UPLOADING",
        "UploadURL": "https://example.com/uploads/example-plugin.bin?signature=example",
        "ExpireTime": "2030-01-01T00:15:00Z"
    }
}

5. 开发者资源

腾讯云 API 平台

腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台,方便您从同一入口查询及使用腾讯云提供的所有 API 服务。

API Inspector

用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况,并自动生成各语言版本的 API 代码,也可前往 API Explorer 进行在线调试。

SDK

云 API 3.0 提供了配套的开发工具集(SDK),支持多种编程语言,能更方便的调用 API。

命令行工具

6. 错误码

以下仅列出了接口业务逻辑相关的错误码,其他错误码详见 公共错误码。

错误码 描述
AuthFailure CAM签名/鉴权错误。
FailedOperation 操作失败。
InternalError 内部错误。
InvalidParameter.AgentSource InvalidParameter.AgentSource
InvalidParameter.CustomDescriptors InvalidParameter.CustomDescriptors
InvalidParameter.Description InvalidParameter.Description
InvalidParameter.MCPSource InvalidParameter.MCPSource
InvalidParameter.RecordSource InvalidParameter.RecordSource
InvalidParameter.RegistryId InvalidParameter.RegistryId
InvalidParameter.SkillSource InvalidParameter.SkillSource
InvalidParameterValue 参数取值错误。
InvalidParameterValue.AgentSourceType InvalidParameterValue.AgentSourceType
InvalidParameterValue.DescriptorType InvalidParameterValue.DescriptorType
InvalidParameterValue.MCPSourceType InvalidParameterValue.MCPSourceType
InvalidParameterValue.SkillSourceType InvalidParameterValue.SkillSourceType
LimitExceeded 超过配额限制。
MissingParameter.AgentSourceEndpointURL MissingParameter.AgentSourceEndpointURL
MissingParameter.MCPSourceDescriptors MissingParameter.MCPSourceDescriptors
MissingParameter.RecordSource MissingParameter.RecordSource
MissingParameter.SkillSourceSkillMd MissingParameter.SkillSourceSkillMd
ResourceNotFound 资源不存在。
ResourceUnavailable 资源不可用。
UnauthorizedOperation 未授权操作。
UnknownParameter 未知参数错误。
UnsupportedOperation 操作不支持。