JSON 架构

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

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

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

智能体卡片架构

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

{
  "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"
  ]
}

字段定义

  • name：代理的直观易懂的名称。
  • description：对代理用途的高级总结。
  • version：代理的版本，例如 1.0.2。
  • protocolVersion：代理实现的 Agent2Agent protocol 的版本，例如 0.3.0。
  • url：代理可访问的端点网址。
  • capabilities：可选。一个对象，用于指定代理支持的操作功能，例如 streaming、pushNotifications 或 stateTransitionHistory。
  • defaultInputModes：可选。一个字符串数组，用于定义代理接受的默认 MIME 类型作为输入，例如 ["text/plain"]。
  • defaultOutputModes：可选。一个字符串数组，用于定义代理作为输出生成的默认 MIME 类型，例如 ["text/plain"]。

  • 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。