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 怎麼走讀下一篇；簽名與校驗清單讀更後面一篇。