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；字段逐项读下一篇；发现怎么走读再下一篇。