智能體的人類可讀名稱。
會顯示在市集列表與用戶端介面中。保持簡短且具體——用戶端會將其作為比較候選智能體時的主要標籤。
常見錯誤： 使用像「AI Assistant」這樣的通用名稱，讓路由系統無從區分。
"name": "地理空間路線規劃代理"
Schema 參考 · 14 fieldsA2A v1.0
A2A Agent Card schema，逐欄位詳解
Agent Card 是標準化的 JSON 文件，用來告知 A2A 用戶端：這個智能體是誰、去哪裡聯繫它、它能做什麼，以及存取如何受到保護。本參考涵蓋每一個 v1.0 欄位的類型、必要性、範例，以及驗證器最常抓到的錯誤。
探索機制如何運作
一個 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 輸出中被引用。
智能體做什麼，以及其他智能體何時應該呼叫它。
這是人類整合者與基於 LLM 的路由系統判斷你的智能體是否適合某項任務的主要自由文字訊號。請說明任務領域、關鍵能力與邊界。
常見錯誤： 少於 20 個字元的一行式描述。路由系統無法比對你沒有描述的內容。
"description": "提供先進的路線規劃、交通分析和自訂地圖生成服務。"
端點與協定綁定的有序清單。第一項為首選。
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" }
]誰在營運這個智能體：組織與網站。
面向市集與企業稽核的信任訊號。v1.0 將 name 欄位重新命名為 organization；當該物件存在時，其內部的 url 為必要。
常見錯誤： 仍在使用 provider.name（v1.0 之前的欄位）。讀取 v1.0 Agent Card 的驗證器將無法識別它。
"provider": {
"organization": "範例地理服務公司",
"url": "https://www.examplegeoservices.com"
}智能體本身的版本，而非協定版本。
讓用戶端能夠偵測到 Agent Card 何時發生實質變化，並重新評估相容性。請遵循你自己的發布方案，通常是 semver。
常見錯誤： 將它與 A2A 協定版本混淆——協定版本現在位於每個 supportedInterfaces 項目中。
"version": "1.2.0"
指向智能體人類可讀文件的連結。
為整合者提供一個閱讀完整 API 合約、速率限制以及不屬於探索文件內容的條款的地方。
常見錯誤： 指向行銷首頁，而非技術文件。
"documentationUrl": "https://docs.example.com/agent"
協定功能旗標：streaming、pushNotifications、extensions、extendedAgentCard。
用戶端不得呼叫你未宣告的功能——對未宣告的串流呼叫會回傳錯誤。extendedAgentCard: true 表示可透過 GetExtendedAgentCard 操作取得更豐富的已驗證 Agent Card。v1.0 移除了 stateTransitionHistory。
常見錯誤： 在伺服器沒有串流端點的情況下宣告 streaming: true。用戶端會呼叫它並失敗。
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": false
}命名的身分驗證方案：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"
}
}
}呼叫該智能體需要哪些已宣告的方案（及範圍）。
每一項都將 securitySchemes 中的一個方案名稱對應到它所需的範圍，與 OpenAPI 的安全需求模式類似。對於刻意公開的智能體，可完全省略這兩個欄位。
常見錯誤： 宣告了 securitySchemes 卻沒有 security 需求，讓用戶端只能猜測是否強制執行身分驗證。
"security": [{ "google": ["openid", "profile", "email"] }]智能體在所有技能中接受的媒體類型。
標準 MIME 類型，如 text/plain、application/json 或 image/png。各個技能可用自己的 inputModes 覆寫。
常見錯誤： 省略該欄位。它在 v1.0 中為必要——用戶端需要它來建構請求。
"defaultInputModes": ["application/json", "text/plain"]
智能體在所有技能中回傳的媒體類型。
告訴呼叫方應該預期文字、結構化 JSON、圖片還是檔案。技能可用 outputModes 依技能層級覆寫。
常見錯誤： 在智能體實際回傳結構化產物時，卻只列出 text/plain。
"defaultOutputModes": ["application/json", "image/png"]
該智能體很可能成功完成的具體能力。
每個技能都需要 id、name、description 與 tags；examples、依技能的模式以及依技能的安全設定皆為選填。技能是探索的基本單位——路由系統會將任務與它們比對，因此每個技能都應限定在單一任務邊界內。
常見錯誤： 沒有標籤的技能。標籤在 v1.0 中成為必要項目，並驅動技能層級的比對。
"skills": [{
"id": "route-optimizer-traffic",
"name": "流量感知路線優化器",
"description": "使用即時路況計算最佳駕駛路線...",
"tags": ["maps", "routing", "traffic"],
"examples": ["規劃從 A 到 B 的路線，避免通行費。"]
}]證明該 Agent Card 由提供者簽發的 JSON Web 簽章。
每個簽章都帶有一個 base64url 編碼的受保護 JWS 標頭與簽章值，計算基於經 RFC 8785（JCS）規範化後的 Agent Card。用戶端在信任從公開網路取得的 Agent Card 之前，應驗證至少一個簽章。
常見錯誤： 簽章之後又編輯了任意欄位——即便是空白字元層面無關緊要的值變更也會使 JWS 失效。
"signatures": [{
"protected": "eyJhbGciOiJFUzI1NiIs...",
"signature": "QFdkNLNszlGj3z3u0YQ..."
}]代表該智能體的圖示 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 替代方案 | 變更原因 |
|---|---|---|
| url | supportedInterfaces[0].url | 首選端點現在就是第一個介面項目。 |
| preferredTransport | supportedInterfaces[] ordering | 偏好透過陣列順序表達，而不再是單獨的欄位。 |
| additionalInterfaces | supportedInterfaces[] | 所有介面都存放在一個有序陣列中。 |
| protocolVersion (top level) | supportedInterfaces[].protocolVersion | 每個介面宣告自己的協定版本，從而支援多版本共存。 |
| supportsAuthenticatedExtendedCard | capabilities.extendedAgentCard | 移入了 capabilities 物件；對應的 RPC 被重新命名為 GetExtendedAgentCard。 |
| provider.name | provider.organization | 為了更清晰而重新命名。 |
| capabilities.stateTransitionHistory | — removed | 不屬於 v1.0；如有需要，可將等效行為建模為擴充功能。 |
樣板程式碼
v1.0 Agent Card 的 TypeScript 型別。
把這些介面放進用戶端、伺服端或 CI 檢查中，即可以型別安全的方式解析與產生 Agent Card。它們與官方規範儲存庫中的 protobuf 定義一致，採用 Agent Card 實際發布時的 camelCase JSON 形式。
更想手寫 Agent Card？產生器產出的正是這種確切結構。
// 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 貼到驗證器中，精確查看哪些欄位需要留意。