公開智能體探索
用這些範例來塑造另一個 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。