JSON 結構定義

使用 Services API 向 Agent Registry 註冊代理或 Model Context Protocol (MCP) 伺服器時，您必須提供說明其功能的設定檔。

Agent Registry 會先根據外部開放原始碼規格驗證您上傳的檔案，再建立索引，以探索代理程式技能和工具。

本文提供範例，並連結至 Agent Card 和 MCP 工具規格的預期 JSON 結構。

代理資訊卡結構定義

註冊符合 A2A 規範的代理時，agent-card.json 酬載須符合官方 Agent2Agent (A2A) 規格。規格檔案大小上限為 10 KB。 skills 陣列欄位支援關鍵字搜尋索引。

Agent Registry 支援 A2A Agent Card 的 0.3 和 1.0 版本。

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 通訊協定版本，例如 1.0.0。
    • tenant：選用。代理程式擁有者的 ID。
  • capabilities：選用。指定支援的作業功能，例如：
    • extensions：選用。通訊協定擴充功能陣列。
    • streaming：選用。布林值，指出代理程式是否支援串流回應。
    • pushNotifications：選用。布林值，指出是否支援工作更新的推播通知。
    • extendedAgentCard：選用。布林值，指出代理程式是否會在通過驗證後提供擴充代理程式資訊卡。
  • defaultInputModes：選用。可做為輸入內容的 MIME 類型陣列。
  • defaultOutputModes：選用。以陣列形式列出產生的輸出內容 MIME 類型。
  • skills：代理程式具備的功能陣列：
    • id：技能的專屬程式化 ID。
    • name：技能的易讀名稱。
    • description：詳細說明技能的用途。
    • tags：用於分類技能的關鍵字字串陣列。
    • examples：範例提示或情境的陣列。

0.3 版結構定義

如果是 A2A 代理程式資訊卡的 0.3 版，酬載必須符合 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 通訊協定版本。 由於版本 1.0 會淘汰這個頂層欄位，因此這個架構的值必須為 0.3 或任何 0.3 修補程式版本，例如 0.3.1。
  • url：可連線至代理程式的端點網址。
  • capabilities：選用。指定支援的作業功能，例如 streaming、pushNotifications 或 stateTransitionHistory。
  • defaultInputModes：選用。可做為輸入內容的 MIME 類型陣列。
  • defaultOutputModes：選用。以陣列形式列出產生的輸出內容 MIME 類型。
  • skills：代理程式具備的功能陣列：
    • id：技能的專屬程式化 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：工具的程式輔助 ID。
    • description：工具用途的易讀說明。
    • inputSchema：定義工具預期參數的 JSON 結構定義物件。

    • annotations：行為提示，引導自動調度管理服務代理與工具互動：

      • title：工具的人類可讀標題。
      • readOnlyHint：如果 true，工具只會擷取資料，不會修改環境。預設值為 false。
      • destructiveHint：如果 true，工具會執行可能導致永久變更的作業。預設值為 true。
      • idempotentHint：如果為 true，重複呼叫工具不會產生額外效果。預設值為 false。
      • openWorldHint：如果為 true，工具會與外部系統互動。預設值為 true。