Google Agent Registry 2026 完整解析：Agent Card 是什麼？A2A Agent 如何使用 JSON 描述能力、Tools 與 Skills？

Registry 是目錄，不是第三種協議

很多人聽到 Agent Registry，會以爲 Google 又發明了一套對話協議。不是。A2A 仍規定 Agent 怎麼自述、怎麼接 Task。Registry 是 Google Cloud 上的可發現組件目錄：把已經存在的 Agent 登記成可檢索的資源。登記之後，同項目裏的編排者、Gemini Enterprise、Agent Gateway 才能按技能關鍵詞找到它。協議還是 A2A；變的是「誰替你記住那張 Card」。沒有目錄，你就得把 URL 寫死在編排器配置裏——那是 2025 年的通訊錄，不是 2026 年的發現。

登記分自動和手工。同項目的 Agent Runtime、帶 AI agent 標籤和 Card 註解的 GKE、帶功能類型的 Cloud Run，以及 Google 內置的 Workspace / Gemini 代理，可以自動進目錄。自動登記只掃本項目。跨項目、機房外、或不支持自動發現的運行時，必須手工建 Service，再生成只讀的 Agent 資源。中心治理項目要看見 spoke 裏的代理，走手工跨項目登記，不是靠魔法掃描整個組織。文檔寫在 Register agents，2026-09-22 剛更新過。

同一份目錄還能收 MCP Server。那份文件叫 toolspec.json，形狀等於 tools/list 的返回，上限也是 10KB。於是 Registry 裏會同時出現「橫向同事」和「向下的手」。不要把兩種條目當成一種資源去寫通用校驗。調用 hop 怎麼核 arguments，見 MCP 與 JSON Schema。今天只談目錄怎麼記住它們。

你在看的	它是什麼	源 JSON
A2A Agent	可委託的對等體	`agent-card.json`（0.3 或 1.0）
MCP Server	可調用的工具集	`toolspec.json`（`tools[]`）
NO_SPEC REST	只有端點，無自動技能	手工 `Service`，沒有 Card

Agent Card：被索引的源 JSON

Agent Card 是 A2A Server 的數字名片。規範路徑仍是 /.well-known/agent-card.json，見 A2A v1.0 變更。Registry 對 A2A 合規項會去拉這張卡，抽出 skills 做關鍵詞索引。卡本身必須過官方 A2A Schema。1.0 的推薦寫法：傳輸端點放進 supportedInterfaces，每項有 url、protocolBinding、protocolVersion。頂層 url 和 protocolVersion 是 0.3 的合同，1.0 客戶端不應再當主字段讀。

給人看的身份是 name、description、version——這裏的 version 是 Agent 自己的版本，不是協議版本。協議版本跟接口走。skills[] 每項要有 id、name、description；Registry 用 tags 做搜索。examples 是給人看的提示，不是驗參的 Schema。完整字段表留給下一篇。今天只要記住：沒有合法 Card，A2A 類型的自動抽取不會發生。卡超過 10KB，Registry 直接拒，編排者更搜不到。

下面是一份可進倉庫的 1.0 卡。先讓它 parse，再拿官方 Schema 核。把整本 runbook 糊進 description，會先撞上限。發現面靠短描述加 tags，不靠把說明書塞進名片。

{
  "name": "Invoice Specialist",
  "description": "Finds and summarizes invoices for finance. Does not post payments.",
  "version": "1.2.0",
  "supportedInterfaces": [
    {
      "url": "https://agents.example.com/invoice/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "extendedAgentCard": false
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "skills": [
    {
      "id": "search-invoices",
      "name": "Search invoices",
      "description": "Look up invoices by week, status, or counterparty.",
      "tags": ["invoices", "finance", "search"],
      "examples": ["Find overdue invoices for last week"]
    }
  ]
}

登記之後：目錄條目長什麼樣

規範不要求 Google 導出你本地那份「目錄快照」。評審需要看見登記之後索引了什麼。把結果收成一份夾具：displayName、specType（A2A_AGENT_CARD 或 NO_SPEC）、cardVersion、抽到的 skill id、interfaces、searchKeywords。這份快照不是 A2A Schema 的實例，不要拿 Card Schema 去套。它是你們 CI 的斷言：登記成功，不等於可被搜到。

{
  "registry": "google-cloud-agent-registry",
  "displayName": "Invoice Specialist",
  "specType": "A2A_AGENT_CARD",
  "cardVersion": "1.0",
  "skillsIndexed": ["search-invoices"],
  "searchKeywords": ["invoices", "finance", "search"],
  "interfaces": [
    {
      "url": "https://agents.example.com/invoice/a2a",
      "protocolBinding": "JSONRPC"
    }
  ]
}

自動抽取只發生在 A2A 合規項。Registry 會查詢 /.well-known/agent-card.json，把聲稱的技能寫進目錄。NO_SPEC 的 REST 端點會進目錄，但沒有技能可搜——編排者能看見有這麼一個 Agent，對不上「找會查發票的同事」。要可搜，補 Card，或走手工技能資源。Gemini Enterprise 還可以把獨立 Skill 登記成頂層 Skill 資源，那是另一條治理線，不要和 Card 裏的 skills[] 寫成同一個文件。

快照和倉庫裏的 Card 並排 diff：keywords 對不上，說明 tags 沒寫或索引滯後。url 對不上，說明登記的是舊端點。Card 合法但 skillsIndexed 爲空，去查 Registry 是否按 1.0 去讀了一張 0.3 的卡——supportedInterfaces 找不到時，抽取會靜默變瘦，故障單上卻寫「搜不到」。

Card 上的 skills 不是 MCP tools，也不是 Plugin 技能

同一個詞，三層東西。Card 上的 skill 是「這個 Agent 聲稱會辦的事」，給目錄搜索和編排者選型。MCP 的 tool 是確定性調用，合同是 inputSchema。Plugin / Agent Skills 的 SKILL.md 是給同一個 Agent 自己看的說明書。Registry 索引的是第一種。把 MCP 工具名抄進 Card.skills[].id，搜索也許碰巧能中；委託時對面仍是不透明 Agent，不是 tools/call。多輪澄清和異步回調會撐破函數調用的形狀。

有些 Card 實現會給技能帶 inputSchema。那是提示形狀，不是 MCP 的執行合同。不要拿 plugin.schema.json 去校驗 Card，也不要拿 Card 去校驗 tools/call。三份 JSON 都叫能力描述，失敗處理完全不同：Card 壞了是發現失敗；inputSchema 壞了是調用失敗。箱子怎麼讓同一個 Coding Agent 長出技能和手，見 Plugin Manifest 實戰。今天只談另一個 Agent 怎麼被目錄記住。

NO_SPEC 項沒有這層聲稱。它在目錄裏像一條只有主機名的通訊錄。編排者不能靠關鍵詞找到它，除非你另外登記獨立 Skill，或補一張 Card。先決定要不要被搜到，再決定要不要上 A2A。爲「目錄好看」貼一張空卡，索引出來的技能是空數組，比不登記更誤導。

這個詞	寫在哪	誰來讀
A2A skill	Agent Card `skills[]`	Registry 搜索 / 編排者
MCP tool	`tools/list` 或 `toolspec.json`	運行時 `tools/call`
Agent Skill	`skills/…/SKILL.md`	同一個 Agent 裏的模型

0.3 與 1.0：兩份合同不要混校驗

Registry 同時收 0.3 和 1.0，推薦新卡走 1.0。1.0 把協議版本和主 URL 趕進 supportedInterfaces；extendedAgentCard 進 capabilities；0.3 的 stateTransitionHistory 不再當核心能力。混用兩套字段，客戶端各讀各的，目錄索引會少一半。A2A 自己的 breaking list 寫在 v1.0 變更頁，不是 Google 私貨。

評審至少留兩份卡：上面的合法 1.0，以及一張把 url 寫在頂層、卻按 1.0 去登記的負例。後者按 1.0 校驗應失敗，或主端點被忽略。CI 如果把兩套 Schema 串成一份「通用 Agent 校驗」，比客戶端更亂。Registry 用你聲明的版本選規則，加載時不會上網現拉 Schema——和 Plugin Manifest 同一紀律。

簽名、擴展卡、GetExtendedAgentCard 是認證之後的安全層，不是目錄層的入門條件。公開卡先被抽到技能，編排者才能決定要不要做帶身份的二次拉取。今天不展開簽名。先讓 tags 能被搜到。

夾具留給 JSONVue

評審夾具至少三份：上面的 1.0 Card、目錄快照、一張 0.3/1.0 混用的負例。第一份過 A2A 1.0 Schema。第二份用你們自己的快照 Schema，或只斷言 skillsIndexed 與 tags。第三份必須失敗。有人把 plugin.json 的閉集字段抄進 Card，或把 MCP inputSchema 整表塞進 skills[]，diff 一眼就能看見。

再加一份 MCP 負對照：合法 toolspec.json，證明同一目錄裏的第二種源文件。不要拿 Card Schema 去套它。tools[].name 對運行時負責，skills[].tags 對搜索負責。密鑰不要出現在任何一份進倉庫的夾具裏。Card 是公開名片，默認按會被拉取來寫。

瀏覽器裏即可完成：JSON 格式化看 Card 與快照能否 parse；JSON Schema 校驗核 1.0 的 supportedInterfaces 與 skills；JSON Diff對比倉庫 Card 和目錄快照，抓 tags / URL drift；數據不離開本機。延伸閱讀：A2A vs MCP、MCP 校驗、以及 Plugin Manifest。

相關文章：A2A vs MCP、MCP 與 JSON Schema、Plugin Manifest 實戰。

常見問題 FAQ

有了 Registry，還要不要在 well-known 放 Card？

要。Registry 消費 Card，不替代 Card。自動抽取就是去拉 /.well-known/agent-card.json。目錄掛了，拿得到域名的客戶端仍應能讀名片。

沒有實現 A2A，能不能進 Registry？

能。類型是 NO_SPEC，手工登記端點。技能不會自動抽取。要被關鍵詞搜到，補 Card，或另外登記獨立 Skill 資源。

Card 上的 skill 等於 MCP tool 嗎？

不等於。前者是給目錄和編排者看的聲稱，後者是帶 inputSchema 的確定性調用。搜中不等於可以 tools/call。對面是不透明 Agent，走 Task。

10KB 不夠寫說明書怎麼辦？

不要把說明書寫進 Card。寫短 description 和能搜的 tags。流程正文留在 Agent 自己的 Skill 或文檔。名片超限，Registry 拒收，發現面變成零。

總結與下一步

2026 年說 Google Agent Registry，可以收成一句：它是目錄，Card 是被索引的源 JSON。編排者搜的是 tags 和技能名，不是你在幻燈片上畫的拓撲。

落地順序：先寫合法 1.0 Card；登記時看 specType 對不對；用快照斷言技能真的進了索引；MCP 另備 toolspec.json。用 JSONVue 核三份合同。分層讀 A2A vs MCP；字段逐項讀下一篇；發現怎麼走讀再下一篇。