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

更新 Record 可变元数据

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

1. 接口描述

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

更新 Registry Record。两种互斥模式:①Record 更新模式:不提交任何 Source / CustomDescriptors,可通过 Description、LabelMutations 修改元数据与 Label(至少提交一项);②Version 创建模式:提交且仅提交一种与现有 DescriptorType 匹配的内容输入,可选 VersionName / ChangeLog / SupportedHarnessVersions / Metadata,禁止 Description / LabelMutations,服务端创建下一个 Revision。PLUGIN 使用 FileSource.Type=FILE 上传原始文件;FileSource.Type=VERSION 可为 Skill 或 Plugin 复用同一 Record 下未删除且 READY 的文件版本,填写 SourceVersionId,不复制来源版本的 Metadata 或 SupportedHarnessVersions。Metadata 以 Name/Value 字符串数组传输,所有层级 key 必须小写;两项版本属性省略时分别为空对象和空列表,不继承上一版本。取代原 ChangeRegistryRecordStableVersion / RollbackRegistryRecordVersion / Create*RegistryRecordVersion。

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

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

2. 输入参数

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

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

Registry ID。


示例值:reg-0123abcd
RecordId 是 String

Record ID。


示例值:rec-0123abcd
Description 否 String

Record 描述,可选。Record 更新模式下允许,允许空字符串清空;Version 创建模式禁止。


示例值:更新后的描述
VersionName 否 String

新 Version 的展示名,可选。仅 Version 创建模式允许。


示例值:1.1.0
ChangeLog 否 String

新 Version 的变更原因,最大 4096 字符,可选。仅 Version 创建模式允许。


示例值:更新兼容声明并复用文件
MCPSource 否 CloudMCPSourceInput

Version 创建模式:现有 Record 的 DescriptorType=MCP 时可提交。

AgentSource 否 CloudAgentSourceInput

Version 创建模式:现有 Record 的 DescriptorType=A2A 或 AGUI 时可提交。

SkillSource 否 CloudSkillSourceInput

Version 创建模式:现有 Record 的 DescriptorType=AGENT_SKILLS 时可提交。

CustomDescriptors 否 String

Version 创建模式:现有 Record 的 DescriptorType=CUSTOM 时可提交,必须是 JSON object 字符串。


示例值:{"vendor":"example","capability":"order-query"}
LabelMutations.N 否 Array of CloudRecordLabelMutation

Record 更新模式:Label 变更列表,最多 32 条,同一次请求中 Label Name 不可重复。

FileSource 否 CloudFileSourceInput

Skill 或 Plugin 后续版本的文件来源。PLUGIN 可使用 FILE 上传新文件,或使用 VERSION 复用同一 Record 的 READY 制品;Skill 仅通过 VERSION 复用现有文件。与其他内容来源互斥。

VERSION 只提交 Type、SourceVersionId;Metadata 和 SupportedHarnessVersions 由本次请求单独声明,不继承来源版本。

SupportedHarnessVersions.N 否 Array of HarnessVersionReference

资产版本支持的 Harness 引擎与具体版本列表。每个元素同时包含 HarnessEngine 和 HarnessEngineVersion,取值原样使用 DescribeHarnessEngineList 返回的选项。

入参限制:最多 128 个元素;两个字段均必填,长度 1~128,区分大小写,不允许空白、通配符或版本范围。按完整配对去重;不接受字符串数组或 null。

省略或空数组表示未声明兼容性,不表示兼容全部。仅随新 Version 写入,后续修改需创建新 Version。筛选时 supported_harness_engine 与 supported_harness_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. 输出参数

参数名称 类型 描述
Record CloudRecord

更新后的 Record。

Version CloudRecordVersion

Version 创建模式返回:本次创建的新 Version。

UploadURL String

Version 创建模式且 SkillSource.Type=TAR_PACKAGE 时返回。


注意:此字段可能返回 null,表示取不到有效值。
示例值:https://cos.example/upload
ExpireTime String

Version 创建模式且 SkillSource.Type=TAR_PACKAGE 时返回。


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

Version 创建模式且 SkillSource.Type=TAR_PACKAGE 时返回。


注意:此字段可能返回 null,表示取不到有效值。
示例值:READY
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: UpdateRegistryRecord
<公共请求参数>

{
    "RegistryId": "reg-0123abcd",
    "RecordId": "rec-0123abcd",
    "VersionName": "1.1.0",
    "ChangeLog": "更新 MCP 接入地址",
    "MCPSource": {
        "Type": "URL_IMPORT",
        "EndpointURL": "https://example.com/mcp-v2"
    },
    "Metadata": [
        {
            "Name": "publisher",
            "Value": "示例发布者"
        }
    ]
}

输出示例

{
    "Response": {
        "RequestId": "00000000-0000-4000-8000-000000000001",
        "Record": {
            "RecordId": "rec-0123abcd"
        },
        "Version": {
            "VersionId": "rv-89abcdef",
            "Revision": 2,
            "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: UpdateRegistryRecord
<公共请求参数>

{
    "RegistryId": "reg-0123abcd",
    "RecordId": "rec-0123abcd",
    "VersionName": "1.1.0",
    "ChangeLog": "更新兼容声明并复用文件",
    "FileSource": {
        "Type": "VERSION",
        "SourceVersionId": "rv-0123abcd"
    },
    "SupportedHarnessVersions": [
        {
            "HarnessEngine": "pi",
            "HarnessEngineVersion": "1.3.0"
        }
    ],
    "Metadata": [
        {
            "Name": "publisher",
            "Value": "示例发布者"
        }
    ]
}

输出示例

{
    "Response": {
        "RequestId": "00000000-0000-4000-8000-000000000001",
        "Record": {
            "RecordId": "rec-0123abcd",
            "RegistryId": "reg-0123abcd",
            "Name": "example-plugin",
            "Description": "示例 Plugin 文件资产",
            "DescriptorType": "PLUGIN",
            "LifecycleStatus": "ACTIVE",
            "AppId": 1250000000,
            "CreatorUin": "100000000001",
            "CreatorSubAccountUin": "100000000002",
            "VersionCount": 2,
            "LabelSet": [
                "latest"
            ],
            "CreateTime": "2030-01-01T00:00:00Z",
            "UpdateTime": "2030-01-01T00:00:00Z"
        },
        "Version": {
            "VersionId": "rv-89abcdef",
            "RecordId": "rec-0123abcd",
            "Revision": 2,
            "VersionName": "1.1.0",
            "ChangeLog": "更新兼容声明并复用文件",
            "Descriptors": "{\"name\": \"example-plugin\", \"description\": \"示例 Plugin 文件资产\"}",
            "SourceType": "FILE",
            "SourceConfig": "{\"Type\":\"FILE\",\"SizeBytes\":1}",
            "Status": "PENDING_APPROVAL",
            "ApprovalMode": "MANUAL",
            "ConfigSHA256": "8eb0ce58a4b47f2d9f4154cfe67815d4977b99abdfd35d735219b1d5a5436526",
            "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": "READY",
            "ContentSHA256": "2d711642b726b04401627ca9fbac32f5c8530fb1903cc4db02258717921a4881",
            "ContentSizeBytes": 1,
            "ContentReadyTime": "2030-01-01T00:00:00Z"
        },
        "ContentStatus": "READY"
    }
}

示例3 移动 stable Label

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

输入示例

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

{
    "RegistryId": "reg-0123abcd",
    "RecordId": "rec-0123abcd",
    "LabelMutations": [
        {
            "Operation": "SET",
            "Name": "stable",
            "VersionId": "rv-0123abcd",
            "Reason": "发布已验证版本"
        }
    ]
}

输出示例

{
    "Response": {
        "RequestId": "00000000-0000-4000-8000-000000000001",
        "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",
                "stable"
            ],
            "CreateTime": "2030-01-01T00:00:00Z",
            "UpdateTime": "2030-01-01T00:00: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.MCPSource InvalidParameter.MCPSource
InvalidParameter.RecordId InvalidParameter.RecordId
InvalidParameter.RecordSource InvalidParameter.RecordSource
InvalidParameter.RegistryId InvalidParameter.RegistryId
InvalidParameter.SkillSource InvalidParameter.SkillSource
InvalidParameter.VersionId InvalidParameter.VersionId
InvalidParameterValue 参数取值错误。
InvalidParameterValue.AgentSourceType InvalidParameterValue.AgentSourceType
InvalidParameterValue.MCPSourceType InvalidParameterValue.MCPSourceType
InvalidParameterValue.SkillSourceType InvalidParameterValue.SkillSourceType
LimitExceeded 超过配额限制。
LimitExceeded.RecordLabelCount LimitExceeded.RecordLabelCount
MissingParameter.AgentSourceEndpointURL MissingParameter.AgentSourceEndpointURL
MissingParameter.MCPSourceDescriptors MissingParameter.MCPSourceDescriptors
MissingParameter.RecordSource MissingParameter.RecordSource
MissingParameter.SkillSourceSkillMd MissingParameter.SkillSourceSkillMd
ResourceNotFound 资源不存在。
ResourceNotFound.RegistryRecord ResourceNotFound.RegistryRecord
ResourceUnavailable 资源不可用。
UnauthorizedOperation 未授权操作。
UnknownParameter 未知参数错误。
UnsupportedOperation 操作不支持。