探索工具 · A2A v1.0

檢測 A2A Agent Card 探索 URL

A2A 用戶端透過從 well-known URL 取得 JSON Agent Card 來探索智能體。在真實網域上同時檢測兩種命名慣例，看看用戶端實際會收到什麼。

以同一根網域建立兩個候選探索 URL。

取得回傳的 JSON，並回報狀態碼與內容類型。

盡可能將回應解析為 Agent Card JSON。

對介面、技能、提供者、模式、能力與安全性中繼資料執行就緒性檢查。

檢測一個公開的智能體網域

輸入一個根網域。檢測工具會取得兩個探索路徑、解析回傳的 JSON，並執行 Agent Card 就緒性檢查。

探索機制如何運作

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

在另一個智能體呼叫你的服務之前，它會先從你網域下的 well-known URI（RFC 8615）取得 Agent Card，評估技能與安全需求，然後呼叫首選介面。若 Agent Card 遺失、過期或被重新導向隱藏，整合在開始之前就已失敗。

本站以身作則：AgentCard.net 在兩個路徑上都發布了自己的 Agent Card，右側顯示的就是實際文件。

查看我們的即時 Agent Card

agentcard.net discovery

GET /.well-known/agent-card.json HTTP/1.1
Host: www.agentcard.net

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

{
  "name": "AgentCard.net Toolkit",
  "version": "1.0.0",
  "supportedInterfaces": [
    { "url": "https://www.agentcard.net/api/agent-card",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0" }
  ],
  "skills": [
    { "id": "generate-agent-card", ... },
    { "id": "validate-agent-card", ... },
    { "id": "check-well-known-discovery", ... }
  ]
}

探索路徑

兩種慣例，同一份 Agent Card。

開啟完整驗證器

A2A v1.0 標準

/.well-known/agent-card.json

A2A v1.0 規範註冊的 well-known URI。新用戶端會優先取得此路徑；請以 application/a2a+json 內容類型提供服務。

舊版（v1.0 之前）

/.well-known/agent.json

早期 A2A 實作與程式碼實驗範例使用此路徑。許多已部署的用戶端仍只檢測這個路徑，因此在此提供相同 Agent Card 是安全的過渡策略。

發布模式

讓 Agent Card 探索更具韌性。

探索失敗通常並不複雜：一次重新導向、一個被快取的錯誤頁面，或只部署了一個路徑而忘記另一個。這套發布流程能讓兩種慣例始終提供同一份最新 Agent Card。

1
在標準路徑上發布
在與 A2A 服務相同的網域上，透過 HTTPS 於 /.well-known/agent-card.json 提供經審核的 Agent Card，內容類型為 application/a2a+json。
2
鏡射舊版路徑
在舊版用戶端仍在使用期間，從 /.well-known/agent.json 回傳完全相同的文件——兩個路徑上的 Agent Card 不一致會擾亂路由。
3
保持 Agent Card 同步
每當端點、技能、能力或身分驗證發生變化時，更新 Agent Card、提升其 version 欄位，並同時重新部署兩個路徑。
4
每次變更後重新檢測
在部署、DNS 變更、閘道遷移或市集資料編輯之後執行此檢測工具。故障通常源於重新導向、HTML 錯誤頁面，或有一個路徑被遺忘。

常見問題

Well-known Agent JSON 常見問題

該發布什麼、發布在哪裡，以及如何讓兩種慣例的用戶端都能正常運作。

應該使用哪個 well-known Agent Card 路徑？

A2A v1.0 將 /.well-known/agent-card.json 註冊為標準探索路徑。舊版的 /.well-known/agent.json 早於 v1.0，但仍被許多已部署的用戶端檢測，因此在過渡期間於兩個路徑上發布同一份 Agent Card 是務實的選擇。

兩個路徑應該回傳完全相同的 JSON 嗎？

應該。從兩個路徑回傳同一份公開 Agent Card，可以讓只支援其中一種慣例的用戶端保持一致。文件不一致會讓智能體看起來因用戶端取得的路徑不同而不同。

Agent Card 應該以什麼內容類型提供服務？

規範為 Agent Card 註冊了 application/a2a+json。實務上普通的 application/json 也被廣泛接受，但若內容類型是 HTML，通常表示該路徑回傳的是錯誤頁面而非 Agent Card。

公開的 Agent Card 可以隱藏私有能力嗎？

可以。在公開 Agent Card 中只發布對探索安全的中繼資料，將 capabilities.extendedAgentCard 設為 true，並透過經過身分驗證的 GetExtendedAgentCard 操作公開敏感技能。

為什麼部署之後探索檢測會失敗？

常見原因包括重新導向到登入頁或行銷頁、以狀態碼 200 回傳的 HTML 404 頁面、CDN 快取的過期 JSON，或者兩個 well-known 路徑中只部署了一個。檢測工具會為每個路徑回報狀態碼與內容類型，因此問題會立即顯現。

發布之前

先驗證 Agent Card，再檢測 URL。

先讓 JSON 通過完整驗證器，在兩個 well-known 路徑上都發布它，再用本工具確認探索是否成功。

開啟驗證器產生 Agent Card

來自部落格

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

全部文章

Comparison

文章以英文發布。

檢測 A2A Agent Card 探索 URL

檢測一個公開的智能體網域

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

兩種慣例，同一份 Agent Card。

/.well-known/agent-card.json

/.well-known/agent.json

讓 Agent Card 探索更具韌性。

在標準路徑上發布

鏡射舊版路徑

保持 Agent Card 同步

每次變更後重新檢測