公開智能體探索
用這些範例來塑造另一個 A2A 用戶端在決定你的智能體能否完成任務之前會取得的 JSON。
市集提交
改寫提供者、技能、標籤、能力和安全性中繼資料，讓審核人員理解這個智能體做什麼、由誰營運。
內部智能體目錄
在團隊將內部智能體整合到工作流程之前，統一它們描述端點、身分驗證和技能的方式。
JSON 範本
面向客服、預約、購物、程式設計、研究和工作流程智能體的範例 Agent Card。
篩選
客服智能體
處理產品諮詢、訂單查詢、退貨，以及升級轉接。
為什麼這樣設計
- OAuth 2.0 用戶端憑證保護訂單資料：Agent Card 聲明了權杖 URL 和範圍，讓用戶端無需頻外文件即可完成身分驗證。
- streaming 和 pushNotifications 都為 true，因為客服對話通常持續較長時間，且處理結果會非同步到達。
- 這個單一技能被限定在一個任務邊界內（分類、解決、升級），而不是模糊的「協助客戶」描述，因此路由系統可以精確比對它。
{
"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"
]
}
]
}預約智能體
尋找可用的預約時段，並準備預約確認。
為什麼這樣設計
- 這裡用請求標頭中的 API 金鑰就足夠：預約按租戶劃分範圍，但不涉及 OAuth 要解決的委派使用者同意問題。
- defaultOutputModes 僅為 application/json，表明呼叫方獲得的是結構化的預約提案而非散文文字。
- pushNotifications 為 true，這樣智能體可以在佔位後端確認之後通知預約結果，而無需用戶端輪詢。
{
"name": "預約智能體",
"description": "搜尋空房情況、提出預訂選項並準備預約以供批准。",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/booking",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "範例公司",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": false,
"pushNotifications": true,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain",
"application/json"
],
"defaultOutputModes": [
"application/json"
],
"skills": [
{
"id": "find-and-prepare-booking",
"name": "尋找並準備預訂",
"description": "檢查資源可用性、比較預訂視窗並返回結構化預訂建議。",
"tags": [
"booking",
"calendar",
"availability"
],
"examples": [
"明天下午找個 30 分鐘的約會。"
]
}
],
"securitySchemes": {
"apiKey": {
"apiKeySecurityScheme": {
"location": "header",
"name": "X-API-Key"
}
}
},
"security": [
{
"apiKey": []
}
]
}購物智能體
比較商品、庫存、價格和購買限制條件。
為什麼這樣設計
- 排名推薦結果在計算過程中串流傳出，因此 streaming 為 true，而 pushNotifications 保持 false——回應完成後不再發生任何事。
- 技能描述承諾回傳權衡取捨和理由，這告訴協作系統該智能體會解釋排名，而不僅僅是列出商品。
- OAuth 範圍限制了與購買相關的資料；一個公開的購物示範完全可以去掉安全性聲明，仍然是一份有效的 Agent Card。
{
"name": "購物智能體",
"description": "將產品與用戶限制進行比較，並傳回排名的購買選項和權衡。",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/shopping",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "範例公司",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": false,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain",
"application/json"
],
"defaultOutputModes": [
"application/json"
],
"skills": [
{
"id": "compare-shopping-options",
"name": "比較購物選擇",
"description": "評估候選產品，按約束條件進行過濾，並返回帶有理由的排名推薦。",
"tags": [
"shopping",
"commerce",
"recommendations"
],
"examples": [
"比較 1,200 美元以下的輕薄筆記型電腦。"
]
}
],
"securitySchemes": {
"oauth2": {
"oauth2SecurityScheme": {
"flows": {
"clientCredentials": {
"tokenUrl": "https://api.example.com/a2a/shopping/oauth/token",
"scopes": {
"agent.invoke": "Invoke agent skills"
}
}
}
}
}
},
"security": [
{
"oauth2": [
"agent.invoke"
]
}
]
}程式設計智能體
審閱程式碼任務，提出修補，並解釋實作決策。
為什麼這樣設計
- extendedAgentCard 為 true：公開 Agent Card 只列出通用的「實作程式碼變更」技能，而特定於儲存庫的技能只透過 GetExtendedAgentCard 向已驗證的用戶端展示。
- 同時聲明了 text/plain 和 application/json 兩種輸出，因為該智能體既回傳人類可讀的解釋，也回傳機器可套用的修補。
- 串流傳輸對於漫長的編譯-測試迴圈很重要；用戶端能看到中間進度，而不是一次沉默的多分鐘呼叫。
{
"name": "程式設計智能體",
"description": "透過分析程式碼、提出變更建議和返回實施說明來協助完成軟體工程任務。",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/coding",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "範例公司",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": true
},
"defaultInputModes": [
"text/plain",
"application/json"
],
"defaultOutputModes": [
"text/plain",
"application/json"
],
"skills": [
{
"id": "implement-code-change",
"name": "實施程式碼更改",
"description": "讀取編碼請求，檢查相關文件，返回補丁建議並總結驗證步驟。",
"tags": [
"coding",
"review",
"patches"
],
"examples": [
"向使用者 API 新增分頁。"
]
}
],
"securitySchemes": {
"apiKey": {
"apiKeySecurityScheme": {
"location": "header",
"name": "X-API-Key"
}
}
},
"security": [
{
"apiKey": []
}
]
}研究智能體
收集資料來源，擷取證據，並回傳結構化的研究筆記。
為什麼這樣設計
- 完全沒有 securitySchemes：該端點是刻意公開的，省略該欄位正是表達這一點的正確方式——一個空的方案對映反而會產生歧義。
- 輸入僅為 text/plain，因為研究簡報都是從自然語言問題開始的；結構化輸出以 application/json 筆記的形式到達。
- 這是一份最小可用的 v1.0 Agent Card：身分、一個介面、能力、模式，以及一個標好標籤的技能。
{
"name": "研究智能體",
"description": "收集來源資料、提取證據並產生帶有引文的結構化研究筆記。",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/research",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "範例公司",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": false,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain"
],
"defaultOutputModes": [
"text/plain",
"application/json"
],
"skills": [
{
"id": "prepare-research-brief",
"name": "準備研究簡介",
"description": "搜尋經批准的來源，提取主張和證據，並返回簡明的研究摘要。",
"tags": [
"research",
"evidence",
"citations"
],
"examples": [
"準備一份有關再生能源政策的引文簡介。"
]
}
]
}內部工作流程智能體
協調審批、狀態檢查，以及後台工作流程更新。
為什麼這樣設計
- application/json 是唯一的輸入輸出模式：這個智能體由其他系統呼叫，絕不會有人直接輸入散文文字。
- OAuth 2.0 加上 extendedAgentCard 很適合企業稽核——安全團隊可以公開看到身分驗證要求，而敏感的工作流程技能仍留在身分驗證之後。
- pushNotifications 至關重要，因為審批鏈可能耗時數小時甚至數天；webhook 取代輪詢來處理狀態變化。
{
"name": "內部工作流程智能體",
"description": "協調內部審批、檢查系統狀態並為營運團隊準備工作流程更新。",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/workflow",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "範例公司",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": false,
"pushNotifications": true,
"extendedAgentCard": true
},
"defaultInputModes": [
"application/json"
],
"defaultOutputModes": [
"application/json"
],
"skills": [
{
"id": "coordinate-internal-workflow",
"name": "協調內部工作流程",
"description": "接收工作流程意圖、檢查策略要求、收集批准並報告最終狀態。",
"tags": [
"workflow",
"operations",
"approval"
],
"examples": [
"請求批准部署工資更新。"
]
}
],
"securitySchemes": {
"oauth2": {
"oauth2SecurityScheme": {
"flows": {
"clientCredentials": {
"tokenUrl": "https://api.example.com/a2a/workflow/oauth/token",
"scopes": {
"agent.invoke": "Invoke agent skills"
}
}
}
}
}
},
"security": [
{
"oauth2": [
"agent.invoke"
]
}
]
}自信地改寫
如何改寫一個 Agent Card 範例
每個 Agent Card 範例都刻意做到足夠完整以便直接複製，但 Agent Card 不應原封不動地發布。把它當作你自己 A2A 伺服器的欄位對映表：用生產環境的值替換身分、端點、提供者、身分驗證、能力、模式和技能細節。
最出色的 Agent Card 會用通俗語言和機器可讀的中繼資料來解釋智能體的任務邊界。用戶端應該能夠判斷這個智能體能做什麼、不能做什麼、該呼叫哪個 URL，以及是否需要憑證。
發布前須知
把每一個 example.com URL 替換成你已部署的 A2A 端點和提供者網站。
針對實際的任務邊界重寫技能名稱、描述、標籤（v1.0 中為必要）和範例。
設定 provider.organization，並在 Agent Card 內容變化時提升頂層 version。
只有當端點是刻意公開時，才移除身分驗證欄位。
保持 defaultInputModes 和 defaultOutputModes 與你的伺服器實際接受和回傳的內容一致。
驗證最終的 JSON，並將其發布在你服務網域下的 /.well-known/agent-card.json。
來自部落格
針對 A2A 探索機制的實務指南，依據 v1.0 規範撰寫。
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閱讀指南IntegrationPublishing 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閱讀指南ComparisonA2A 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閱讀指南文章以英文發布。