A2A Agent Card JSON Schema 完整教程：如何定义 AI Agent 的名称、能力、Skills、接口与 Endpoint？

这张卡写给谁看

Agent Card 是 A2A Server 挂在 /.well-known/agent-card.json 上的公开名片。读它的人不是你自己的模型，是另一个编排者、网关、或组织里的目录。它要回答三句：你是谁、怎么连上你、你声称会办哪些事。第一句是 name / description / version。第二句是 supportedInterfaces。第三句是 skills[]。把 runbook 糊进 description，10KB 上限先到，发现面反而变瘦。

1.0 把「必填」写死了。规范表里：name、description、supportedInterfaces、version、capabilities、defaultInputModes、defaultOutputModes、skills 都是 Yes。少一项，客户端不该当合法 1.0 卡读。0.3 可以靠顶层 url 和 protocolVersion 过日子；1.0 客户端应忽略这两项，只认接口数组。混写两套字段，目录抽技能会静默变瘦，故障单上却写「搜不到」。

卡不是 Plugin Manifest，也不是 MCP tools/list。箱子怎么让同一个 Coding Agent 长技能，见站内 Plugin 文。调用 hop 怎么核 arguments，见 MCP 与 JSON Schema。今天只写横向同事怎么自述。签名、扩展卡、GetExtendedAgentCard 是认证之后的层，公开卡先把技能写清楚。

身份：name、description、version、provider

name 给人扫目录用，不要写成内部服务名。description 写范围和边界：会做什么，明确不做什么。退货专员可以写「分类退货申请，不处理退款入账」。编排者靠这段决定要不要发 Task，不是靠你仓库里的 README。

version 是这颗 Agent 的发行版，例如 1.0.3。协议版跟接口走，写在 supportedInterfaces[].protocolVersion。两处都写 1.0，以后改 Agent 实现却不改协议，客户端分不清谁变了。provider 可选，但一写就要成对：organization 加 url。documentationUrl 和 iconUrl 也是可选；长说明放到文档 URL，不要堆进名片。

身份段写完先停一下。没有接口，这张卡还不能被调用；没有 skills，目录搜不到你。先把三句里的第一句写短、写真，再填端点。

接口：supportedInterfaces 才是端点

1.0 的主端点不在顶层。supportedInterfaces 是有序数组，第一项是首选。每项必填 url、protocolBinding、protocolVersion。url 生产环境必须是绝对 HTTPS。protocolBinding 官方核心值是 JSONRPC、GRPC、HTTP+JSON，规范允许开放字符串以便扩展。tenant 可选，多租户才写。

同一颗 Agent 可以挂三条绑定，指向不同 URL。客户端按数组顺序挑自己会的第一种。不要三条都指向同一个会 404 的路径充数。0.3 的顶层 url 加 protocolVersion 是旧合同；v1.0 变更页写明它们不再当主字段。按 1.0 登记却把 URL 写在顶层，合法校验应失败，或主端点被忽略。

接口数组决定「怎么说话」，不决定「会办什么事」。只写 JSONRPC、不写 skills，编排者连得上，搜不到。只写 skills、不写接口，搜得到，发不出 Task。两段都要在。

capabilities 与默认 MIME

capabilities 在 1.0 是必填对象，里面的布尔值反而是可选：streaming、pushNotifications、extendedAgentCard，外加 extensions 数组。没写或写 false，客户端调用对应操作应收到能力错误，而不是默默重试。不要把 0.3 的 stateTransitionHistory 再当核心能力抄进来。规范 4.4.3 表里已经没有这一项。

defaultInputModes 和 defaultOutputModes 是媒体类型数组，对所有 skill 生效，单个 skill 可以用 inputModes / outputModes 覆盖。只接纯文本就写 text/plain；会吐 JSON 再加 application/json。空数组等于没声明，1.0 校验过不了。不要在这里写文件扩展名或内部枚举。

extendedAgentCard 为真，才表示认证后可以拉第二份更完整的卡。公开卡仍必须自洽：技能、接口、默认 MIME 都在。把关键 skill 只藏在扩展卡里，未认证的目录抽不到，编排者在搜索面就错过你。

skills[]：id、tags、examples

每个 skill 必填 id、name、description、tags。id 是程序标识，稳定、短、别空格。name 给人看。description 写清输入输出的边界，仍不是 arguments Schema。tags 在 1.0 是必填字符串数组，给目录和编排者做关键词。Google Registry 也靠 tags 建搜索索引。空数组或不写，卡可能 parse，但搜不到。

examples 可选，是给人看的提示或场景，不是 JSON Schema。1.0 不再把 inputSchema 当 skill 合同。有些旧实现还往技能上挂 Schema；当提示可以，当 tools/call 合同不行。对面是不透明 Agent，你发的是 Task。站内已有 0.3 风格片段把 inputSchema 写进 skill——那是旧合同，新卡不要抄。

技能不要按内部函数名切。一个 skill 对应编排者会委托的一类事。退货专员可以是 classify-return 和 check-window，不要把「读表」「写日志」「发邮件」拆成三个搜索词。下面是一份可进仓库的 1.0 卡。先让它 parse，再拿官方 Schema 核。

{
  "name": "Returns Specialist",
  "description": "Classifies return requests and checks the return window. Does not post refunds.",
  "version": "1.0.3",
  "provider": {
    "organization": "Example Commerce",
    "url": "https://commerce.example.com"
  },
  "documentationUrl": "https://docs.example.com/returns-agent",
  "supportedInterfaces": [
    {
      "url": "https://agents.example.com/returns/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    },
    {
      "url": "https://agents.example.com/returns/a2a/json",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0"
    }
  ],
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "extendedAgentCard": false
  },
  "defaultInputModes": ["text/plain", "application/json"],
  "defaultOutputModes": ["text/plain", "application/json"],
  "skills": [
    {
      "id": "classify-return",
      "name": "Classify a return",
      "description": "Decide whether a request is a return, exchange, or warranty claim.",
      "tags": ["returns", "classify", "commerce"],
      "examples": ["This jacket arrived damaged. Is it a return or a warranty claim?"]
    },
    {
      "id": "check-window",
      "name": "Check return window",
      "description": "Say whether the purchase is still inside the return window.",
      "tags": ["returns", "policy", "deadline"],
      "examples": ["Order 8841 was delivered on 2026-08-02. Can they still return it?"]
    }
  ]
}

不要写进 1.0 卡的东西

负例至少留一张：顶层仍写 url，技能不写 tags，再塞一份 MCP 式 inputSchema。按 1.0 校验应失败。CI 若把 0.3 和 1.0 揉成「通用 Agent 校验」，比客户端更乱。Registry 用你声明的版本选规则，加载时不会上网现拉 Schema。

{
  "name": "Returns Specialist",
  "description": "Classifies return requests.",
  "version": "1.0.3",
  "url": "https://agents.example.com/returns/a2a",
  "protocolVersion": "1.0",
  "supportedInterfaces": [
    {
      "url": "https://agents.example.com/returns/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "capabilities": {
    "streaming": true,
    "stateTransitionHistory": true
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "skills": [
    {
      "id": "classify-return",
      "name": "Classify a return",
      "description": "Decide the request type.",
      "inputSchema": {
        "type": "object",
        "required": ["orderId"],
        "properties": {
          "orderId": { "type": "string" }
        }
      }
    }
  ]
}

securitySchemes 和安全要求是可选层。公开卡可以先不写签名。signatures 是 JWS，校验步骤留给实战篇。今天只要记住：签名不替代 tags。没有技能的合法空壳，比一张「好看的」空卡更诚实——空 skills 仍是必填数组，可以是一项真实技能，不要提交零项充数除非你真的没有。

也不要把 plugin.json 的闭集字段、SKILL.md 路径、MCP tools[].name 抄进 Card。三份 JSON 都叫能力，失败处理不同。Card 坏了是发现失败。

浏览器里即可完成：JSON 格式化看卡能否 parse；JSON Schema 校验核 1.0 的 supportedInterfaces 与 skills[].tags；JSON Diff对比仓库卡和负例，抓顶层 url / 漏 tags。数据不离开本机。延伸阅读：Agent Registry 总览、A2A vs MCP。发现怎么走，读下一篇。

相关文章：Google Agent Registry、A2A vs MCP、MCP 与 JSON Schema。

常见问题 FAQ

总结与下一步

2026 年写 A2A Agent Card，可以收成一张必填表：身份三段、接口数组、能力对象、默认 MIME、带 tags 的 skills。编排者读的是这些字段，不是你的架构图。

落地顺序：按 1.0 写合法卡；接口第一项设成真端点；每个 skill 带非空 tags；用 JSONVue 核 parse 和 Schema。目录怎么收卡读上一篇；发现 hop 怎么走读下一篇；签名与校验清单读更后面一篇。