/.well-known/agent-card.json
A2A v1.0 規範註冊的 well-known URI。新用戶端會優先取得此路徑；請以 application/a2a+json 內容類型提供服務。
探索工具 · 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 Cardagentcard.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。
/.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 路徑中只部署了一個。檢測工具會為每個路徑回報狀態碼與內容類型，因此問題會立即顯現。