fix: Move a2a global discovery path

Author: achetronic

server/a2a/handler.go

@@ -112,7 +112,27 @@ func (h *Handler) Rebuild(agents []store.AgentDefinition, flows []store.FlowDefi
 	h.mu.Unlock()
 }
 
-func (h *Handler) ServeAgentCard(w http.ResponseWriter, r *http.Request) {
+const a2aPrefix = "/api/v1/a2a/"
+const wellKnownSuffix = "/.well-known/agent-card.json"
+
+func (h *Handler) ServeA2A(w http.ResponseWriter, r *http.Request) {
+	path := r.URL.Path
+	rest := strings.TrimPrefix(path, a2aPrefix)
+
+	if rest == ".well-known/agent-card.json" {
+		h.serveGlobalCards(w, r)
+		return
+	}
+
+	if strings.HasSuffix(path, wellKnownSuffix) {
+		h.servePerAgentCard(w, r)
+		return
+	}
+
+	h.serveJSONRPC(w, r)
+}
+
+func (h *Handler) serveGlobalCards(w http.ResponseWriter, r *http.Request) {
 	agentID := r.URL.Query().Get("agent")
 
 	h.mu.RLock()
@@ -140,8 +160,8 @@ func (h *Handler) ServeAgentCard(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(cardList)
 }
 
-func (h *Handler) ServePerAgentCard(w http.ResponseWriter, r *http.Request) {
-	agentID := extractAgentID(r.URL.Path, "/api/v1/a2a/", "/.well-known/agent-card.json")
+func (h *Handler) servePerAgentCard(w http.ResponseWriter, r *http.Request) {
+	agentID := extractAgentID(r.URL.Path, a2aPrefix, wellKnownSuffix)
 
 	h.mu.RLock()
 	card, ok := h.cards[agentID]
@@ -157,13 +177,8 @@ func (h *Handler) ServePerAgentCard(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(card)
 }
 
-func (h *Handler) ServeJSONRPC(w http.ResponseWriter, r *http.Request) {
-	if strings.HasSuffix(r.URL.Path, "/.well-known/agent-card.json") {
-		h.ServePerAgentCard(w, r)
-		return
-	}
-
-	agentID := extractAgentID(r.URL.Path, "/api/v1/a2a/", "")
+func (h *Handler) serveJSONRPC(w http.ResponseWriter, r *http.Request) {
+	agentID := extractAgentID(r.URL.Path, a2aPrefix, "")
 
 	h.mu.RLock()
 	handler, ok := h.handlers[agentID]

server/api/user/a2a_swagger.go

@@ -56,7 +56,7 @@ type A2AJSONRPCResponse struct {
 // @Produce      json
 // @Param        agent  query     string  false  "Filter by agent ID. When provided, returns a single card object instead of an array."  example(home-assistant)
 // @Success      200    {array}   A2AAgentCard  "List of agent cards (or single card object when ?agent= is used)"
-// @Router       /.well-known/agent-card.json [get]
+// @Router       /a2a/.well-known/agent-card.json [get]
 func (h *Handler) A2AListCards() {}
 
 // A2APerAgentCard returns the agent card for a specific agent.

server/api/user/docs/userapi_docs.go

@@ -15,7 +15,7 @@ const docTemplateuserapi = `{
     "host": "{{.Host}}",
     "basePath": "{{.BasePath}}",
     "paths": {
-        "/.well-known/agent-card.json": {
+        "/a2a/.well-known/agent-card.json": {
             "get": {
                 "description": "Returns agent cards for all agents that have A2A enabled. Each card describes the agent's identity, capabilities, skills, and security requirements following the A2A protocol specification.",
                 "produces": [

server/api/user/docs/userapi_swagger.json

@@ -12,7 +12,7 @@
     "host": "localhost:8080",
     "basePath": "/api/v1",
     "paths": {
-        "/.well-known/agent-card.json": {
+        "/a2a/.well-known/agent-card.json": {
             "get": {
                 "description": "Returns agent cards for all agents that have A2A enabled. Each card describes the agent's identity, capabilities, skills, and security requirements following the A2A protocol specification.",
                 "produces": [

server/api/user/docs/userapi_swagger.yaml

@@ -167,7 +167,7 @@ info:
   title: Magec User API
   version: "1.0"
 paths:
-  /.well-known/agent-card.json:
+  /a2a/.well-known/agent-card.json:
     get:
       description: Returns agent cards for all agents that have A2A enabled. Each
         card describes the agent's identity, capabilities, skills, and security requirements

server/main.go

@@ -172,9 +172,8 @@ func main() {
 	httpMux.Handle("/api/v1/agent/", userRecorded)
 	httpMux.Handle("/api/v1/voice/", newVoiceHandler(dataStore, agentRouter))
 
-	// A2A protocol endpoints (per-agent card + JSON-RPC invoke)
-	httpMux.HandleFunc("/.well-known/agent-card.json", a2aHandler.ServeAgentCard)
-	httpMux.HandleFunc("/api/v1/a2a/", a2aHandler.ServeJSONRPC)
+	// A2A protocol endpoints (global discovery + per-agent card + JSON-RPC invoke)
+	httpMux.HandleFunc("/api/v1/a2a/", a2aHandler.ServeA2A)
 
 	userAPI := user.New(dataStore)
 	httpMux.HandleFunc("/api/v1/health", userAPI.Health)

server/middleware/middleware.go

@@ -45,7 +45,6 @@ func ClientAuth(next http.Handler, dataStore *store.Store) http.Handler {
 		if r.Method == http.MethodOptions ||
 			path == "/api/v1/health" ||
 			path == "/api/v1/voice/events" ||
-			path == "/.well-known/agent-card.json" ||
 			(strings.HasPrefix(path, "/api/v1/a2a/") && strings.HasSuffix(path, "/.well-known/agent-card.json")) ||
 			strings.HasPrefix(path, "/api/v1/webhooks/") ||
 			!strings.HasPrefix(path, "/api/") {

website/content/docs/a2a.md

@@ -38,7 +38,7 @@ That's it. The agent is now discoverable and invocable via A2A.
 
 | Endpoint | Auth | Description |
 |----------|------|-------------|
-| `/.well-known/agent-card.json` | No | Lists all A2A-enabled agents |
+| `/api/v1/a2a/.well-known/agent-card.json` | No | Lists all A2A-enabled agents |
 | `/api/v1/a2a/{agentId}/.well-known/agent-card.json` | No | Agent card for a specific agent |
 | `/api/v1/a2a/{agentId}` | Bearer token | JSON-RPC invocation endpoint |
 

website/public/docs/a2a/index.html

@@ -184,7 +184,7 @@ <h2 id="endpoints">Endpoints</h2>
   </thead>
   <tbody>
       <tr>
-          <td><code>/.well-known/agent-card.json</code></td>
+          <td><code>/api/v1/a2a/.well-known/agent-card.json</code></td>
           <td>No</td>
           <td>Lists all A2A-enabled agents</td>
       </tr>