Agent Card 產生器為你的 AI 智能體建立了什麼

Agent Card 是 A2A 智能體的公開介面說明。在另一個智能體決定是否呼叫你的服務之前，它需要的不只是一個 URL：它需要一份關於該智能體用途、技術合約、技能與存取需求的可靠說明。

這個 Agent Card 產生器把這些實作細節轉化為可讀、符合 A2A v1.0 結構的 JSON，同時讓決策始終貼近表單。請在完成智能體核心邏輯之後、部署或上架之前使用它——這正是手寫 JSON 檔案通常會出錯的環節。

讓你的智能體可被探索

一份清晰的 Agent Card 為 A2A 用戶端提供了可靠的起點：智能體歸屬於誰、部署在哪裡，以及它支援哪些協定綁定與版本。

描述一個可用的介面

記錄另一個智能體在發起呼叫之前需要知道的首選介面、內容模式、串流行為以及推播通知支援情況。

設定存取預期

說明該服務是公開的、使用 API 金鑰，還是需要 OAuth 2.0，讓整合方能夠選擇正確的身分驗證流程——同時絕不在 Agent Card 中放入任何憑證。

把技能變成清晰的合約

為智能體能完成的工作命名，加入 v1.0 要求的標籤與有用的範例，讓其邊界對人類、市集與 AI 用戶端都清晰易懂。

Agent Card 產生器如何運作

從服務細節到可發布的 Agent Card

Agent Card 產生器將服務細節轉化為清晰、可發布的 JSON 文件。在把 Agent Card 投入生產之前，請遵循這個簡短的工作流程。

  1. 1

    從真實服務開始

    加入公開的 A2A 端點、協定綁定、提供者資訊、智能體版本，以及你的伺服器接受與回傳的內容類型。

  2. 2

    定義能力與技能邊界

    只選擇你的實作所支援的能力，然後用簡明、具體的語言描述一個具有代表性的技能。

  3. 3

    審查產生的 JSON

    使用即時預覽發現缺少的欄位、佔位符 URL，或與實際部署服務不符的描述。

  4. 4

    驗證並發布

    讓 Agent Card 通過驗證器檢查，然後將審核後的文件放在你服務網域下的 /.well-known/agent-card.json。

誰在使用 Agent Card 產生器

為每一位建立、發布或審核 Agent Card 的人而生

Agent Card 產生器協助建構者、平台團隊與審核人員，在不從空白 JSON 檔案開始的情況下，建立一致的 A2A 智能體中繼資料。

改為從範例開始

AI 與獨立開發者

在發布相容 A2A 的智能體時，用一個完整、符合規範的起點取代手寫的 agent-card.json。

提示工程師與產品經理

無需接觸 JSON 語法，即可從服務描述草擬一份可信的探索文件，然後交給工程團隊審核。

平台與 DevOps 團隊

在內部智能體進入公司智能體目錄或 CI 流程之前，統一它們描述端點、身分驗證與技能的方式。

市集發布方

準備好審核方與排名系統能夠真正解析的提供者中繼資料、技能標籤與安全性聲明。

常見問題

Agent Card 產生器常見問題

在 A2A 用戶端找到你的端點之前，先把要點做對。

什麼是 A2A Agent Card？

A2A Agent Card 是一份面向 AI 智能體的 JSON 探索文件。它向潛在用戶端傳達身分、提供者資訊、支援的介面、能力、技能、可接受的內容模式以及安全需求——相當於智能體對智能體版本的 README 加 API 概覽。

為什麼要用 Agent Card 產生器而不是手寫 JSON？

手寫的 Agent Card 經常會遺漏必填欄位、使用 v1.0 之前的欄位名稱，或存在語法錯誤。產生器產出目前的 A2A v1.0 結構——supportedInterfaces、provider.organization、必填的技能標籤——並在你輸入時即時驗證，因此結構性錯誤永遠不會進入生產環境。

產生的 Agent Card 針對哪個 A2A 版本？

產生器輸出 A2A v1.0 結構：一個有序的 supportedInterfaces 陣列，每個介面都有自己的 protocolBinding 與 protocolVersion，一個頂層的智能體 version，以及包含 extendedAgentCard 的能力宣告。帶有頂層 url 或 preferredTransport 欄位的 Agent Card 屬於 v1.0 之前的版本。

產生的 JSON 在投入生產前需要審查嗎？

需要。產生器建立的是一份實用的起始文件，而不是你已部署合約的替代品。請確認端點、協定綁定、技能與身分驗證與使用者實際會存取的服務相符。

我應該在哪裡發布 Agent Card？

在與你的 A2A 服務相同的網域下，將審核後的 JSON 發布到 https://your-domain/.well-known/agent-card.json，這是 A2A 規範註冊的 well-known 路徑。許多較舊的整合也會檢查 /.well-known/agent.json，因此同時提供兩者是一種安全的過渡策略。

準備發布

在發布之前，回到 Agent Card 產生器。

完善細節，審查產生的 JSON，並在發布 Agent Card 之前使用即時驗證。

開啟 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閱讀指南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閱讀指南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閱讀指南

文章以英文發布。