JSON 結構定義

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

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

本文提供範例，並連結至 Agent Card 和 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 通訊協定版本，例如 0.3.0。
  • url：可連線至代理程式的端點網址。
  • capabilities：選用。這個物件會指定代理程式支援的作業功能，例如 streaming、pushNotifications 或 stateTransitionHistory。
  • defaultInputModes：選用。字串陣列，定義代理程式接受的預設 MIME 類型做為輸入內容，例如 ["text/plain"]。
  • defaultOutputModes：選用。字串陣列，定義代理程式產生的預設 MIME 類型，例如 ["text/plain"]。

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