JSON 結構定義

在 Agent Registry 建立 Service 資源，手動註冊代理或 Model Context Protocol (MCP) 伺服器時，您需要提供 JSON 設定檔，宣告其功能。Agent Registry 會先根據開放原始碼規格驗證這些檔案，再建立索引，讓使用者能找到代理 A2A 技能和 MCP 工具。請使用下列 JSON 結構和範例，設定 Agent Cards 和 MCP 工具規格的格式。

代理資訊卡結構定義

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

Agent Registry 支援 A2A 代理資訊卡的 1.0 和 0.3 版本。選取版本即可查看其 JSON 結構定義和欄位定義：

如果是 A2A 代理資訊卡 1.0 版，酬載必須符合官方 A2A 1.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"
      ]
    }
  ]
}

欄位定義

  • 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：代理具備的 A2A 技能說明陣列：
    • id：A2A 技能的專屬程式輔助 ID。
    • name：A2A 技能的人類可讀名稱。
    • description：詳細說明 A2A 技能的作用。
    • tags：關鍵字字串陣列，用於分類 A2A 技能。
    • examples：這個 A2A 技能處理的範例提示或情境陣列。

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

欄位定義

  • name：人類可讀的代理名稱。
  • description：代理用途的簡要摘要。
  • version：代理程式版本，例如 1.0.2。
  • protocolVersion：代理實作的 A2A 通訊協定版本。由於版本 1.0 淘汰了這個頂層欄位，因此這個結構定義的值必須是 0.3 或任何 0.3 修補程式版本，例如 0.3.1。
  • url：可連線至代理程式的端點網址。
  • capabilities (選用)：指定代理支援作業功能的物件，例如 streaming、pushNotifications 或 stateTransitionHistory。
  • defaultInputModes (選用)：字串陣列，定義代理預設接受的輸入 MIME 類型，例如 ["text/plain"]。
  • defaultOutputModes (選用)：字串陣列，定義代理預設輸出的 MIME 類型，例如 ["text/plain"]。
  • skills：代理具備的 A2A 技能說明陣列：
    • id：A2A 技能的專屬程式輔助 ID。
    • name：A2A 技能的人類可讀名稱。
    • description：詳細說明 A2A 技能的作用。
    • tags：關鍵字字串陣列，用於分類 A2A 技能。
    • examples：這個 A2A 技能處理的範例提示或情境陣列。

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。