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次/秒。
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。
- Tencent Cloud SDK 3.0 for Python: CNB, GitHub, Gitee
- Tencent Cloud SDK 3.0 for Java: CNB, GitHub, Gitee
- Tencent Cloud SDK 3.0 for PHP: CNB, GitHub, Gitee
- Tencent Cloud SDK 3.0 for Go: CNB, GitHub, Gitee
- Tencent Cloud SDK 3.0 for Node.js: CNB, GitHub, Gitee
- Tencent Cloud SDK 3.0 for .NET: CNB, GitHub, Gitee
- Tencent Cloud SDK 3.0 for C++: CNB, GitHub, Gitee
- Tencent Cloud SDK 3.0 for Ruby: CNB, GitHub, Gitee
命令行工具
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 | 操作不支持。 |