fix: address A2A review findings

Author: omeraplak

examples/with-a2a-server/README.md

@@ -93,7 +93,7 @@ The returned card advertises the JSON-RPC endpoint via its `url` field:
 Send a JSON-RPC request to the agent:
 
 ```bash
-curl -X POST http://localhost:3141/a2a/support \
+curl -X POST http://localhost:3141/a2a/supportagent \
   -H "Content-Type: application/json" \
   -d '{
         "jsonrpc": "2.0",

packages/a2a-server/src/server.spec.ts

@@ -194,6 +194,25 @@ describe("A2AServer", () => {
     ).toBe("https://agents.example/a2a/support-agent");
   });
 
+  it("encodes reserved characters in A2A endpoint URLs without removing spaces", () => {
+    const agentId = "support agent/ops?";
+    const agent: StubAgent = {
+      id: agentId,
+      purpose: "Answer support questions",
+      generateText: vi.fn(),
+      streamText: vi.fn(),
+    };
+
+    const server = createServer(agent);
+
+    expect(server.getAgentCard(agentId).url).toBe("/a2a/support%20agent%2Fops%3F");
+    expect(
+      server.getAgentCard(agentId, {
+        requestUrl: "https://agents.example/.well-known/support%20agent%2Fops%3F/agent-card.json",
+      }).url,
+    ).toBe("https://agents.example/a2a/support%20agent%2Fops%3F");
+  });
+
   it("streams incremental updates and completes the task", async () => {
     const streamText = vi.fn().mockImplementation(async () => ({
       text: Promise.resolve("Final response"),

packages/a2a-server/src/server.ts

@@ -34,7 +34,7 @@ import { VoltA2AError } from "./types";
 const DEFAULT_A2A_ROUTE_PREFIX = "/a2a";
 
 function sanitizeSegment(segment: string): string {
-  return segment.replace(/^\/+|\/+$|\s+/g, "");
+  return encodeURIComponent(segment.replace(/^\/+|\/+$/g, ""));
 }
 
 function buildA2AEndpointPath(serverId: string): string {

packages/server-core/src/a2a/routes.spec.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from "vitest";
+import { buildA2AEndpointPath, buildAgentCardPath } from "./routes";
+
+describe("A2A route helpers", () => {
+  it("encodes reserved characters without removing internal spaces", () => {
+    expect(buildA2AEndpointPath("support agent/ops?")).toBe("/a2a/support%20agent%2Fops%3F");
+    expect(buildAgentCardPath("support agent/ops?")).toBe(
+      "/.well-known/support%20agent%2Fops%3F/agent-card.json",
+    );
+  });
+});

packages/server-core/src/a2a/routes.ts

@@ -10,5 +10,5 @@ export function buildA2AEndpointPath(serverId: string): string {
 }
 
 function sanitizeSegment(segment: string): string {
-  return segment.replace(/^\/+|\/+$|\s+/g, "");
+  return encodeURIComponent(segment.replace(/^\/+|\/+$/g, ""));
 }

packages/server-hono/src/routes/a2a.routes.spec.ts

@@ -1,3 +1,5 @@
+import { A2AServerRegistry, type ServerProviderDeps, TriggerRegistry } from "@voltagent/core";
+import type { Logger } from "@voltagent/internal";
 import * as serverCore from "@voltagent/server-core";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { OpenAPIHono } from "../zod-openapi-compat";
@@ -26,45 +28,136 @@ vi.mock("@voltagent/a2a-server", async () => {
   };
 });
 
-describe("A2A Routes", () => {
-  let app: OpenAPIHono;
-  const mockDeps = {
-    a2a: {
-      registry: {
-        list: vi.fn().mockReturnValue([{ id: "server1" }]),
+function createMockA2ARegistry() {
+  const registry = new A2AServerRegistry();
+  registry.register(
+    {
+      getMetadata() {
+        return {
+          id: "server1",
+          name: "server1",
+          version: "1.0.0",
+        };
+      },
+    },
+    {
+      agentRegistry: {
+        getAgent() {
+          return undefined;
+        },
+        getAllAgents() {
+          return [];
+        },
+      },
+    },
+  );
+  return registry;
+}
+
+function createMockDeps(): ServerProviderDeps {
+  return {
+    agentRegistry: {
+      getAgent() {
+        return undefined;
+      },
+      getAllAgents() {
+        return [];
+      },
+      getAgentCount() {
+        return 0;
+      },
+      removeAgent() {
+        return false;
+      },
+      registerAgent() {},
+      getGlobalVoltOpsClient() {
+        return undefined;
+      },
+      getGlobalLogger() {
+        return undefined;
       },
     },
-  } as any;
-  const mockLogger = {
+    workflowRegistry: {
+      getWorkflow() {
+        return undefined;
+      },
+      getWorkflowsForApi() {
+        return [];
+      },
+      getWorkflowDetailForApi() {
+        return undefined;
+      },
+      getWorkflowCount() {
+        return 0;
+      },
+      getAllWorkflowIds() {
+        return [];
+      },
+      on() {},
+      off() {},
+      activeExecutions: new Map(),
+      async resumeSuspendedWorkflow() {
+        return undefined;
+      },
+    },
+    triggerRegistry: new TriggerRegistry(),
+    a2a: {
+      registry: createMockA2ARegistry(),
+    },
+  };
+}
+
+function createMockLogger(): Logger {
+  const logger: Logger = {
     trace: vi.fn(),
     debug: vi.fn(),
     info: vi.fn(),
     warn: vi.fn(),
     error: vi.fn(),
-  } as any;
+    fatal: vi.fn(),
+    child: vi.fn(() => logger),
+  };
+
+  return logger;
+}
+
+describe("A2A Routes", () => {
+  let app: InstanceType<typeof OpenAPIHono>;
+  let mockDeps: ServerProviderDeps;
+  let mockLogger: Logger;
 
   beforeEach(() => {
     app = new OpenAPIHono();
-    registerA2ARoutes(app as any, mockDeps, mockLogger);
+    mockDeps = createMockDeps();
+    mockLogger = createMockLogger();
+    registerA2ARoutes(app, mockDeps, mockLogger);
     vi.clearAllMocks();
   });
 
   it("passes the request URL when resolving the agent card", async () => {
-    vi.mocked(serverCore.resolveAgentCard).mockReturnValue({
+    const card = {
       name: "agent",
       description: "desc",
-    } as any);
+      url: "https://agents.example/a2a/server1",
+      version: "1.0.0",
+      capabilities: {
+        streaming: true,
+        pushNotifications: false,
+        stateTransitionHistory: false,
+      },
+      defaultInputModes: ["text"],
+      defaultOutputModes: ["text"],
+      skills: [],
+    };
+    vi.mocked(serverCore.resolveAgentCard).mockReturnValue(card);
 
     const requestUrl = "http://agents.example/.well-known/server1/agent-card.json";
     const response = await app.request(requestUrl);
 
     expect(response.status).toBe(200);
-    expect(await response.json()).toEqual({
-      name: "agent",
-      description: "desc",
-    });
+    expect(await response.json()).toEqual(card);
     expect(serverCore.resolveAgentCard).toHaveBeenCalledWith(
-      mockDeps.a2a.registry,
+      mockDeps.a2a?.registry,
       "server1",
       "server1",
       { requestUrl },

website/docs/agents/a2a/a2a-server.md

@@ -223,6 +223,6 @@ The test sends a `message/send`, streams a `message/stream`, and exercises `task
 
 ## Troubleshooting checklist
 
-- **404 for discovery card**: ensure the agent ID you request matches the key inside `VoltAgent({ agents: { ... } })`.
+- **404 for discovery card**: ensure the `serverId` in `/.well-known/{serverId}/agent-card.json` matches `A2AServer({ id })`, or the normalized `name` when `id` is omitted. It does not come from `VoltAgent({ agents: { ... } })` or the `a2aServers` map key.
 - **Unexpected JSON in SSE**: confirm you are stripping the `\x1E` prefix before parsing the JSON payload.
 - **Cancellation not propagating**: verify you call `tasks/cancel` with the task ID from the stream and that your TaskStore preserves the `activeCancellations` set.