JSON 架构

使用 Services API 向 Agent Registry 显式注册代理或 Model Context Protocol (MCP) 服务器时，您必须提供描述其功能的配置文件。

Agent Registry 会根据外部开源规范验证您上传的文件，然后再对其编制索引，以发现智能体技能和工具。

本文档提供了一些示例，并提供了一些链接，用于说明代理卡片和 MCP 工具规范的预期 JSON 结构。

智能体卡片架构

注册符合 A2A 标准的代理时，您的 agent-card.json 载荷必须遵循官方 Agent2Agent (A2A) 规范。规范文件的大小上限为 10 KB。skills 数组字段支持关键字搜索索引。

代理注册表支持版本 0.3 和 1.0 的 A2A Agent Card。

版本 1.0 架构（推荐）

对于版本为 1.0 的 A2A 代理卡，载荷必须遵循官方 A2A v1.0 规范。在此规范中，您可以在 supportedInterfaces 数组中声明传输端点。

{
  "name": "string",
  "description": "string",
  "version": "string",
  "supportedInterfaces": [
    {
      "url": "string",
      "protocolBinding": "string",
      "protocolVersion": "string",
      "tenant": "string"
    }
  ],
  "capabilities": {
    "streaming": false,
    "pushNotifications": false,
    "extendedAgentCard": false
  },
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain"
  ],
  "skills": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "tags": [
        "string"
      ],
      "examples": [
        "string"
      ]
    }
  ]
}

字段定义（版本 1.0）

  • name：代理的直观易懂的名称。
  • description：对代理用途的高级总结。
  • version：代理的版本，例如 1.0.0。
  • supportedInterfaces：支持的传输和网址组合的数组。 每个接口均包含以下信息：
    • url：此接口的端点网址。
    • protocolBinding：相应网址支持的协议绑定，例如 HTTP+JSON、JSONRPC 或 GRPC。
    • protocolVersion：此接口公开的 A2A protocol 版本，例如 1.0.0。
    • tenant：可选。代理所有者的标识符。
  • capabilities：可选。指定支持的操作功能，例如：
    • extensions：可选。协议扩展程序数组。
    • streaming：可选。一个布尔值，用于指示代理是否支持流式响应。
    • pushNotifications：可选。一个布尔值，用于指示是否支持针对任务更新的推送通知。
    • extendedAgentCard：可选。一个布尔值，用于指示代理在通过身份验证后是否提供扩展的代理卡片。
  • defaultInputModes：可选。接受作为输入的 MIME 类型数组。
  • defaultOutputModes：可选。作为输出生成的一系列 MIME 类型。
  • skills：代理具备的功能的数组：
    • id：技能的唯一程序化标识符。
    • name：技能的直观易懂的名称。
    • description：技能的详细说明。
    • tags：用于对技能进行分类的关键字字符串数组。
    • examples：示例提示或场景的数组。

版本 0.3 架构

对于版本 0.3 的 A2A 代理卡，载荷必须遵循 v0.3.0 规范。在此规范中，主要推理网址和协议版本声明为顶级字段。

{
  "name": "string",
  "description": "string",
  "version": "string",
  "protocolVersion": "string",
  "url": "string",
  "skills": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "tags": [
        "string"
      ],
      "examples": [
        "string"
      ]
    }
  ],
  "capabilities": {
    "streaming": false,
    "pushNotifications": false,
    "stateTransitionHistory": false
  },
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain"
  ]
}

字段定义（版本 0.3）

  • name：代理的直观易懂的名称。
  • description：对代理用途的高级总结。
  • version：代理的版本，例如 1.0.2。
  • protocolVersion：代理实现的 A2A protocol 的版本。由于版本 1.0 已弃用此顶级字段，因此对于此架构，该值必须为 0.3 或任何 0.3 补丁版本，例如 0.3.1。
  • url：代理可访问的端点网址。
  • capabilities：可选。指定支持的操作功能，例如 streaming、pushNotifications 或 stateTransitionHistory。
  • defaultInputModes：可选。接受作为输入的 MIME 类型数组。
  • defaultOutputModes：可选。作为输出生成的一系列 MIME 类型。
  • skills：代理具备的功能的数组：
    • id：技能的唯一程序化标识符。
    • name：技能的直观易懂的名称。
    • description：技能的详细说明。
    • tags：用于对技能进行分类的关键字字符串数组。
    • examples：示例提示或场景的数组。

MCP 工具架构

注册 MCP 服务器时，您的 toolspec.json 载荷必须包含符合 MCP Tool 对象架构的工具列表。

预期载荷是一个包含单个 tools 字段的 JSON 对象，与标准 MCP 工具或列表请求返回的载荷完全相同。相应规范文件的大小上限为 10 KB。

{
  "tools": [
    {
      "name": "string",
      "description": "string",
      "inputSchema": {
        "type": "object",
        "properties": {}
      },
      "annotations": {
        "title": "string",
        "readOnlyHint": false,
        "destructiveHint": true,
        "idempotentHint": false,
        "openWorldHint": true
      }
    }
  ]
}

字段定义

  • tools：服务器提供的一系列工具：

    • name：工具的程序化标识符。
    • description：直观易懂的工具用途说明。
    • inputSchema：一个 JSON 架构对象，用于定义工具的预期参数。

    • annotations：用于指导编排器代理如何与工具互动的行为提示：

      • title：工具的人类可读标题。
      • readOnlyHint：如果为 true，则该工具仅检索数据，而不修改其环境。默认值为 false。
      • destructiveHint：如果为 true，则该工具会执行可能会导致永久性更改的操作。默认值为 true。
      • idempotentHint：如果为 true，则重复调用该工具不会产生额外效果。默认值为 false。
      • openWorldHint：如果为 true，则工具会与外部系统互动。默认值为 true。