Schema 參考 · 14 fieldsA2A v1.0

A2A Agent Card schema，逐欄位詳解

Agent Card 是標準化的 JSON 文件，用來告知 A2A 用戶端：這個智能體是誰、去哪裡聯繫它、它能做什麼，以及存取如何受到保護。本參考涵蓋每一個 v1.0 欄位的類型、必要性、範例，以及驗證器最常抓到的錯誤。

產生一張 Agent Card對照 v1.0 驗證

本頁內容

探索機制namedescriptionsupportedInterfacesproviderversiondocumentationUrlcapabilitiessecuritySchemessecuritydefaultInputModesdefaultOutputModesskillssignaturesiconUrlv0.x → v1.0 遷移TypeScript 型別完整範例 Agent Card常見問題

探索機制如何運作

一個 well-known URL，啟動每一次 A2A 整合。

A2A 用戶端從 well-known URI 取得 Agent Card，對照自己的任務評估技能、能力與安全需求，然後呼叫首選介面——即 supportedInterfaces 中的第一項。若 capabilities.extendedAgentCard 為 true，已驗證的用戶端可透過 GetExtendedAgentCard 操作請求更豐富的 Agent Card。

規範將 /.well-known/agent-card.json 註冊為標準位置。較舊的 v0.x 部署使用 /.well-known/agent.json，這也是我們的驗證器會同時檢查兩者的原因。

# Fetch a public Agent Card

GET /.well-known/agent-card.json HTTP/1.1
Host: agent.example.com

HTTP/1.1 200 OK
Content-Type: application/a2a+json

{
  "name": "GeoSpatial Route Planner Agent",
  "supportedInterfaces": [
    { "url": "https://georoute-agent.example.com/a2a/v1",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0" }
  ],
  ...
}

欄位參考

每一個 AgentCard 欄位，以及決定通過或失敗的細節。

必要標記遵循官方規範中的 v1.0 protobuf 定義。錨點連結讓每個欄位都能在 issue、審查與 CI 輸出中被引用。

name

string必要

智能體的人類可讀名稱。

會顯示在市集列表與用戶端介面中。保持簡短且具體——用戶端會將其作為比較候選智能體時的主要標籤。

常見錯誤： 使用像「AI Assistant」這樣的通用名稱，讓路由系統無從區分。

"name": "地理空間路線規劃代理"

description

string必要

智能體做什麼，以及其他智能體何時應該呼叫它。

這是人類整合者與基於 LLM 的路由系統判斷你的智能體是否適合某項任務的主要自由文字訊號。請說明任務領域、關鍵能力與邊界。

常見錯誤： 少於 20 個字元的一行式描述。路由系統無法比對你沒有描述的內容。

"description": "提供先進的路線規劃、交通分析和自訂地圖生成服務。"

supportedInterfaces

AgentInterface[]必要

端點與協定綁定的有序清單。第一項為首選。

v1.0 新增：取代了舊版頂層的 url、preferredTransport 與 additionalInterfaces 欄位。每一項都宣告自己的 url、protocolBinding（JSONRPC、GRPC、HTTP+JSON，或自訂綁定 URI）、protocolVersion，以及選填的租戶路由鍵——因此一個智能體可同時服務多個協定版本與傳輸方式。

常見錯誤： 宣告了伺服器實際上並未在該 URL 上提供的綁定——規範要求每一項都必須準確。

"supportedInterfaces": [
  { "url": "https://api.example.com/a2a/v1",
    "protocolBinding": "JSONRPC",
    "protocolVersion": "1.0" }
]

provider

AgentProvider選填

誰在營運這個智能體：組織與網站。

面向市集與企業稽核的信任訊號。v1.0 將 name 欄位重新命名為 organization；當該物件存在時，其內部的 url 為必要。

常見錯誤： 仍在使用 provider.name（v1.0 之前的欄位）。讀取 v1.0 Agent Card 的驗證器將無法識別它。

"provider": {
  "organization": "範例地理服務公司",
  "url": "https://www.examplegeoservices.com"
}

version

string必要

智能體本身的版本，而非協定版本。

讓用戶端能夠偵測到 Agent Card 何時發生實質變化，並重新評估相容性。請遵循你自己的發布方案，通常是 semver。

常見錯誤： 將它與 A2A 協定版本混淆——協定版本現在位於每個 supportedInterfaces 項目中。

"version": "1.2.0"

documentationUrl

string選填

指向智能體人類可讀文件的連結。

為整合者提供一個閱讀完整 API 合約、速率限制以及不屬於探索文件內容的條款的地方。

常見錯誤： 指向行銷首頁，而非技術文件。

"documentationUrl": "https://docs.example.com/agent"

capabilities

AgentCapabilities必要

協定功能旗標：streaming、pushNotifications、extensions、extendedAgentCard。

用戶端不得呼叫你未宣告的功能——對未宣告的串流呼叫會回傳錯誤。extendedAgentCard: true 表示可透過 GetExtendedAgentCard 操作取得更豐富的已驗證 Agent Card。v1.0 移除了 stateTransitionHistory。

常見錯誤： 在伺服器沒有串流端點的情況下宣告 streaming: true。用戶端會呼叫它並失敗。

"capabilities": {
  "streaming": true,
  "pushNotifications": true,
  "extendedAgentCard": false
}

securitySchemes

map<string, SecurityScheme>選填

命名的身分驗證方案：API 金鑰、HTTP 驗證、OAuth 2.0、OpenID Connect，或雙向 TLS。

每個命名方案包裹一個具體的方案物件（apiKeySecurityScheme、httpAuthSecurityScheme、oauth2SecurityScheme、openIdConnectSecurityScheme、mtlsSecurityScheme）。用戶端由此了解如何進行身分驗證——憑證本身總是透過頻外方式取得。

常見錯誤： 在 Agent Card 中嵌入實際的 API 金鑰或權杖。Agent Card 是一份公開文件。

"securitySchemes": {
  "google": {
    "openIdConnectSecurityScheme": {
      "openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration"
    }
  }
}

security

array選填

呼叫該智能體需要哪些已宣告的方案（及範圍）。

每一項都將 securitySchemes 中的一個方案名稱對應到它所需的範圍，與 OpenAPI 的安全需求模式類似。對於刻意公開的智能體，可完全省略這兩個欄位。

常見錯誤： 宣告了 securitySchemes 卻沒有 security 需求，讓用戶端只能猜測是否強制執行身分驗證。

"security": [{ "google": ["openid", "profile", "email"] }]

defaultInputModes

string[]必要

智能體在所有技能中接受的媒體類型。

標準 MIME 類型，如 text/plain、application/json 或 image/png。各個技能可用自己的 inputModes 覆寫。

常見錯誤： 省略該欄位。它在 v1.0 中為必要——用戶端需要它來建構請求。

"defaultInputModes": ["application/json", "text/plain"]

defaultOutputModes

string[]必要

智能體在所有技能中回傳的媒體類型。

告訴呼叫方應該預期文字、結構化 JSON、圖片還是檔案。技能可用 outputModes 依技能層級覆寫。

常見錯誤： 在智能體實際回傳結構化產物時，卻只列出 text/plain。

"defaultOutputModes": ["application/json", "image/png"]

skills

AgentSkill[]必要

該智能體很可能成功完成的具體能力。

每個技能都需要 id、name、description 與 tags；examples、依技能的模式以及依技能的安全設定皆為選填。技能是探索的基本單位——路由系統會將任務與它們比對，因此每個技能都應限定在單一任務邊界內。

常見錯誤： 沒有標籤的技能。標籤在 v1.0 中成為必要項目，並驅動技能層級的比對。

"skills": [{
  "id": "route-optimizer-traffic",
  "name": "流量感知路線優化器",
  "description": "使用即時路況計算最佳駕駛路線...",
  "tags": ["maps", "routing", "traffic"],
  "examples": ["規劃從 A 到 B 的路線，避免通行費。"]
}]

signatures

AgentCardSignature[]選填

證明該 Agent Card 由提供者簽發的 JSON Web 簽章。

每個簽章都帶有一個 base64url 編碼的受保護 JWS 標頭與簽章值，計算基於經 RFC 8785（JCS）規範化後的 Agent Card。用戶端在信任從公開網路取得的 Agent Card 之前，應驗證至少一個簽章。

常見錯誤： 簽章之後又編輯了任意欄位——即便是空白字元層面無關緊要的值變更也會使 JWS 失效。

"signatures": [{
  "protected": "eyJhbGciOiJFUzI1NiIs...",
  "signature": "QFdkNLNszlGj3z3u0YQ..."
}]

iconUrl

string選填

代表該智能體的圖示 URL。

供目錄與用戶端介面使用。請透過 HTTPS 從一個穩定的位置提供它。

常見錯誤： 連結到另一個不受信任網域上的圖示，該圖示可能在你的列表背後被悄悄更改。

"iconUrl": "https://agent.example.com/icon.png"

版本遷移

把 v0.x Agent Card 遷移到 A2A v1.0。

如果你的 Agent Card 仍帶有頂層的 url 或 preferredTransport，代表它早於 v1.0。驗證器會自動標記這兩者。

v0.x 欄位v1.0 替代方案變更原因
urlsupportedInterfaces[0].url首選端點現在就是第一個介面項目。
preferredTransportsupportedInterfaces[] ordering偏好透過陣列順序表達，而不再是單獨的欄位。
additionalInterfacessupportedInterfaces[]所有介面都存放在一個有序陣列中。
protocolVersion (top level)supportedInterfaces[].protocolVersion每個介面宣告自己的協定版本，從而支援多版本共存。
supportsAuthenticatedExtendedCardcapabilities.extendedAgentCard移入了 capabilities 物件；對應的 RPC 被重新命名為 GetExtendedAgentCard。
provider.nameprovider.organization為了更清晰而重新命名。
capabilities.stateTransitionHistory— removed不屬於 v1.0；如有需要，可將等效行為建模為擴充功能。

樣板程式碼

v1.0 Agent Card 的 TypeScript 型別。

把這些介面放進用戶端、伺服端或 CI 檢查中，即可以型別安全的方式解析與產生 Agent Card。它們與官方規範儲存庫中的 protobuf 定義一致，採用 Agent Card 實際發布時的 camelCase JSON 形式。

更想手寫 Agent Card？產生器產出的正是這種確切結構。

產生一張 Agent Card對照 v1.0 驗證
// A2A v1.0 Agent Card — TypeScript definitions
export interface AgentCard {
  name: string
  description: string
  supportedInterfaces: AgentInterface[]
  provider?: AgentProvider
  version: string
  documentationUrl?: string
  capabilities: AgentCapabilities
  securitySchemes?: Record<string, SecurityScheme>
  security?: Record<string, string[]>[]
  defaultInputModes: string[]
  defaultOutputModes: string[]
  skills: AgentSkill[]
  signatures?: AgentCardSignature[]
  iconUrl?: string
}

export interface AgentInterface {
  url: string
  protocolBinding: 'JSONRPC' | 'GRPC' | 'HTTP+JSON' | (string & {})
  protocolVersion: string
  tenant?: string
}

export interface AgentProvider {
  organization: string
  url: string
}

export interface AgentCapabilities {
  streaming?: boolean
  pushNotifications?: boolean
  extensions?: AgentExtension[]
  extendedAgentCard?: boolean
}

export interface AgentExtension {
  uri: string
  description?: string
  required?: boolean
  params?: Record<string, unknown>
}

export interface AgentSkill {
  id: string
  name: string
  description: string
  tags: string[]
  examples?: string[]
  inputModes?: string[]
  outputModes?: string[]
}

export interface AgentCardSignature {
  protected: string
  signature: string
  header?: Record<string, unknown>
}

export type SecurityScheme =
  | { apiKeySecurityScheme: { location: 'header' | 'query' | 'cookie'; name: string; description?: string } }
  | { httpAuthSecurityScheme: { scheme: string; bearerFormat?: string; description?: string } }
  | { oauth2SecurityScheme: { flows: Record<string, unknown>; oauth2MetadataUrl?: string; description?: string } }
  | { openIdConnectSecurityScheme: { openIdConnectUrl: string; description?: string } }
  | { mtlsSecurityScheme: Record<string, never> }

完整性

Agent Card 簽章，簡要說明。

由於 Agent Card 是從公開網路上取得的，v1.0 將簽章機制正式化：Agent Card（去除 signatures 欄位與預設值後）先按 RFC 8785 JSON 規範化處理，再以 JWS 形式簽章。用戶端在依據 Agent Card 採取行動之前，應透過 kid/jku 標頭或受信任的金鑰庫驗證至少一個簽章。多重簽章支援金鑰輪替。

發布前檢查清單

透過 HTTPS 在 /.well-known/agent-card.json 提供該 Agent Card。

每一個 supportedInterfaces 項目都可存取，並且確實使用了所宣告的綁定方式。

技能帶有必要標籤以及邊界清晰的描述。

宣告的能力與伺服器實際情況相符——未宣告的功能必須回傳錯誤，已宣告的功能必須真正可用。

securitySchemes 描述了如何進行身分驗證；Agent Card 中任何地方都不出現憑證。

每當 Agent Card 內容發生變化時，都提升 version。

一份完整的 v1.0 Agent Card。

一個具備 OAuth 2.0、串流傳輸與推播通知的客服智能體——所有必要欄位一應俱全。更多模式可在範例庫中找到。

瀏覽全部範例
{
  "name": "客服智能體",
  "description": "回答客戶支援問題，檢索訂單上下文，並將未解決的問題回報給人工團隊。",
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a/customer-support",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "範例公司",
    "url": "https://example.com"
  },
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "extendedAgentCard": false
  },
  "defaultInputModes": [
    "text/plain",
    "application/json"
  ],
  "defaultOutputModes": [
    "text/plain",
    "application/json"
  ],
  "skills": [
    {
      "id": "resolve-customer-support-request",
      "name": "解決客戶支援請求",
      "description": "對客戶支援請求進行分類，收集所需的背景信息，提出解決方案，並在信心不足時升級。",
      "tags": [
        "support",
        "orders",
        "returns"
      ],
      "examples": [
        "幫我退回訂單。"
      ]
    }
  ],
  "securitySchemes": {
    "oauth2": {
      "oauth2SecurityScheme": {
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://api.example.com/a2a/customer-support/oauth/token",
            "scopes": {
              "agent.invoke": "Invoke agent skills"
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "oauth2": [
        "agent.invoke"
      ]
    }
  ]
}

常見問題

Agent Card schema 常見問題

決定 Agent Card 能否通過審查的版本變更、探索欄位與發布細節。

A2A v1.0 的 Agent Card 有哪些變化？

v1.0 將 url、preferredTransport 與 additionalInterfaces 合併為一個有序的 supportedInterfaces 陣列，其中每一項都宣告自己的 url、protocolBinding 與 protocolVersion。supportsAuthenticatedExtendedCard 遷移到了 capabilities.extendedAgentCard，provider.name 變成了 provider.organization，技能標籤成為必要項目，並且透過 RFC 8785 規範化正式確立了 JWS Agent Card 簽章機制。

Agent Card 與 API schema 是同一回事嗎？

不是。Agent Card 是智能體的探索文件。它概述了身分、介面、能力、技能、模式、提供者與安全中繼資料，而完整的 API schema 描述的是詳細的請求與回應結構。它對一項服務所扮演的角色，相當於 README 或 OpenAPI 概覽：足以判斷是否要呼叫它，以及如何呼叫。

哪些欄位對探索最重要？

name、description、supportedInterfaces、skills（附標籤）、defaultInputModes、defaultOutputModes、capabilities、provider，以及安全中繼資料。路由系統會將任務與你的描述及技能標籤進行比對，然後使用介面與能力資訊來規劃實際呼叫。

私有技能應該出現在公開 Agent Card 中嗎？

只發布那些對未經身分驗證的探索來說是安全的技能。若需要更豐富的私有 Agent Card，將 capabilities.extendedAgentCard 設為 true，並透過已驗證的 GetExtendedAgentCard 操作揭露敏感技能。

Agent Card 發布在哪裡？

發布在 well-known URI https://your-domain/.well-known/agent-card.json，內容類型為 application/a2a+json（實務上 application/json 同樣可行）。早期實作使用 /.well-known/agent.json，因此在過渡期間同時發布兩者是務實的選擇。

讓 schema 派上用場

打造一份能一次通過驗證的 Agent Card。

根據你的服務細節產生一份符合 v1.0 結構的 Agent Card，或將現有 Agent Card 貼到驗證器中，精確查看哪些欄位需要留意。

開啟產生器驗證一份 Agent Card

來自部落格

針對 A2A 探索機制的實務指南，依據 v1.0 規範撰寫。

全部文章
Comparison

A2A vs MCP: two protocols solving two different problems

Compare A2A vs MCP: what each protocol connects, where they overlap, and why production AI agent systems often use both for tools and agent collaboration.

9 min read閱讀指南How-to

How to create an agent.json file for A2A v1.0

Learn how to create an agent.json file for A2A v1.0, including required Agent Card fields, the well-known URL, response headers, and common mistakes.

11 min read閱讀指南Integration

Publishing an Agent Card from ADK, LangGraph, CrewAI or Semantic Kernel

Learn how to publish an A2A Agent Card from Google ADK, LangGraph, CrewAI, or Semantic Kernel by mapping framework concepts to standard discovery fields.

10 min read閱讀指南

文章以英文發布。