Package org.a2aproject.sdk.server.rest.quarkus

Class A2AServerRoutes

java.lang.Object
org.a2aproject.sdk.server.rest.quarkus.A2AServerRoutes
@Singleton public class A2AServerRoutes extends Object
Vert.x Web Router routes for A2A protocol REST endpoints.

This class defines all HTTP routes for the A2A protocol using the Vert.x Web Router API (@Observes Router). Routes are registered programmatically to map HTTP requests to A2A operations, delegating to RestHandler for processing.

Route Mapping

Routes support optional tenant prefixing and use regex patterns for flexible matching: 

 POST   /{tenant}/message:send           → sendMessage()
 POST   /{tenant}/message:stream         → sendMessageStreaming()
 GET    /{tenant}/tasks                  → listTasks()
 GET    /{tenant}/tasks/{taskId}         → getTask()
 POST   /{tenant}/tasks/{taskId}:cancel  → cancelTask()
 POST   /{tenant}/tasks/{taskId}:subscribe → subscribeToTask()
 GET    /.well-known/agent-card.json     → getAgentCard()
 GET    /{tenant}/extendedAgentCard      → getExtendedAgentCard()

Authentication

Most endpoints require authentication via @Authenticated, except:

  • /.well-known/agent-card.json - Public agent discovery endpoint (@PermitAll)

Streaming Support

Streaming endpoints (message:stream, subscribe) use Server-Sent Events (SSE) via SseResponseWriter. SSE responses are handled by:

Error Handling

All errors are caught and converted to HTTP responses via RestHandler.createErrorResponse(A2AError), ensuring consistent error format and status codes across all endpoints.

Context Creation

Each request creates a ServerCallContext via createCallContext(RoutingContext, String), extracting:

  • User authentication from Quarkus Security
  • HTTP headers (including X-A2A-Version, X-A2A-Extensions)
  • Tenant ID from URL path
  • Transport protocol metadata

Custom context creation is supported via CDI-provided CallContextFactory.

See Also:

  • Constructor Details

    • A2AServerRoutes

      public A2AServerRoutes()

  • Method Details

    • sendMessage

      public void sendMessage(String body, io.vertx.ext.web.RoutingContext rc)
      Handles blocking message send requests.

      Maps POST /{tenant}/message:send to RestHandler.sendMessage(org.a2aproject.sdk.server.ServerCallContext, java.lang.String, java.lang.String). The request body must be JSON containing a message with parts.

      URL Pattern: /message:send or /{tenant}/message:send

      Example: 

      
 POST /message:send
 Content-Type: application/json

 {
   "message": {
     "parts": [{"text": "Hello"}]
   }
 }
      Parameters:
      body - the JSON request body
      rc - the Vert.x routing context

    • sendMessageStreaming

      public void sendMessageStreaming(String body, io.vertx.ext.web.RoutingContext rc)
      Handles streaming message send requests with Server-Sent Events.

      Maps POST /{tenant}/message:stream to RestHandler.sendStreamingMessage(org.a2aproject.sdk.server.ServerCallContext, java.lang.String, java.lang.String). Returns a stream of task updates and artifacts as SSE events.

      URL Pattern: /message:stream or /{tenant}/message:stream

      Response Format: text/event-stream with JSON events: 

      
 data: {"taskStatusUpdate":{"task":{"status":{"state":"WORKING"}}}}

 data: {"taskArtifactUpdate":{"artifacts":[...]}}

 data: {"taskStatusUpdate":{"task":{"status":{"state":"COMPLETED"}}}}
      Parameters:
      body - the JSON request body
      rc - the Vert.x routing context

    • listTasks

      public void listTasks(io.vertx.ext.web.RoutingContext rc)
      Lists tasks with optional filtering and pagination.

      Maps GET /{tenant}/tasks to RestHandler.listTasks(org.a2aproject.sdk.server.ServerCallContext, java.lang.String, java.lang.String, java.lang.String, java.lang.Integer, java.lang.String, java.lang.Integer, java.lang.String, java.lang.Boolean). Supports query parameters for filtering and pagination.

      URL Pattern: /tasks?status=COMPLETED&pageSize=10

      Query Parameters:

      • contextId - Filter by conversation context
      • status - Filter by task state (SUBMITTED, WORKING, COMPLETED, etc.)
      • pageSize - Maximum tasks to return
      • pageToken - Pagination token
      • historyLength - Max history entries per task
      • statusTimestampAfter - ISO-8601 timestamp filter
      • includeArtifacts - Include artifacts in response (boolean)
      Parameters:
      rc - the Vert.x routing context

    • getTask

      public void getTask(io.vertx.ext.web.RoutingContext rc)
      Retrieves a specific task by ID.

      Maps GET /{tenant}/tasks/{taskId} to RestHandler.getTask(org.a2aproject.sdk.server.ServerCallContext, java.lang.String, java.lang.String, java.lang.Integer). Optionally includes task history via query parameter.

      URL Pattern: /tasks/{taskId}?historyLength=10

      Parameters:
      rc - the Vert.x routing context (taskId extracted from path)

    • cancelTask

      public void cancelTask(String body, io.vertx.ext.web.RoutingContext rc)
      Cancels a running task.

      Maps POST /{tenant}/tasks/{taskId}:cancel to RestHandler.cancelTask(org.a2aproject.sdk.server.ServerCallContext, java.lang.String, java.lang.String, java.lang.String). Signals the agent executor to stop processing and transition to CANCELED state.

      URL Pattern: /tasks/{taskId}:cancel

      Parameters:
      rc - the Vert.x routing context (taskId extracted from path)

    • subscribeToTask

      public void subscribeToTask(io.vertx.ext.web.RoutingContext rc)
      Subscribes to task updates via Server-Sent Events.

      Maps POST /{tenant}/tasks/{taskId}:subscribe to RestHandler.subscribeToTask(org.a2aproject.sdk.server.ServerCallContext, java.lang.String, java.lang.String). Returns a stream of task events allowing clients to reconnect to ongoing tasks.

      URL Pattern: /tasks/{taskId}:subscribe

      Use Cases:

      • Reconnecting after network interruption
      • Monitoring long-running tasks
      • Multiple clients observing same task
      Parameters:
      rc - the Vert.x routing context (taskId extracted from path)

    • createTaskPushNotificationConfiguration

      public void createTaskPushNotificationConfiguration(String body, io.vertx.ext.web.RoutingContext rc)
      Creates a push notification configuration for a task.

      Maps POST /{tenant}/tasks/{taskId}/pushNotificationConfigs to RestHandler.createTaskPushNotificationConfiguration(org.a2aproject.sdk.server.ServerCallContext, java.lang.String, java.lang.String, java.lang.String).

      URL Pattern: /tasks/{taskId}/pushNotificationConfigs

      Request Body: JSON containing webhook URL and event filters

      Parameters:
      body - the JSON request body with notification configuration
      rc - the Vert.x routing context (taskId extracted from path)

    • getTaskPushNotificationConfiguration

      public void getTaskPushNotificationConfiguration(io.vertx.ext.web.RoutingContext rc)
      Retrieves a specific push notification configuration.

      Maps GET /{tenant}/tasks/{taskId}/pushNotificationConfigs/{configId} to RestHandler.getTaskPushNotificationConfiguration(org.a2aproject.sdk.server.ServerCallContext, java.lang.String, java.lang.String, java.lang.String).

      URL Pattern: /tasks/{taskId}/pushNotificationConfigs/{configId}

      Parameters:
      rc - the Vert.x routing context (taskId and configId extracted from path)

    • listTaskPushNotificationConfigurations

      public void listTaskPushNotificationConfigurations(io.vertx.ext.web.RoutingContext rc)
      Lists push notification configurations for a task.

      Maps GET /{tenant}/tasks/{taskId}/pushNotificationConfigs to RestHandler.listTaskPushNotificationConfigurations(org.a2aproject.sdk.server.ServerCallContext, java.lang.String, java.lang.String, int, java.lang.String). Supports pagination via query parameters.

      URL Pattern: /tasks/{taskId}/pushNotificationConfigs?pageSize=10

      Query Parameters:

      • pageSize - Maximum configurations to return
      • pageToken - Pagination token for next page
      Parameters:
      rc - the Vert.x routing context (taskId extracted from path)

    • deleteTaskPushNotificationConfiguration

      public void deleteTaskPushNotificationConfiguration(io.vertx.ext.web.RoutingContext rc)
      Deletes a push notification configuration.

      Maps DELETE /{tenant}/tasks/{taskId}/pushNotificationConfigs/{configId} to RestHandler.deleteTaskPushNotificationConfiguration(org.a2aproject.sdk.server.ServerCallContext, java.lang.String, java.lang.String, java.lang.String).

      URL Pattern: /tasks/{taskId}/pushNotificationConfigs/{configId}

      Response: HTTP 204 No Content on success

      Parameters:
      rc - the Vert.x routing context (taskId and configId extracted from path)

    • getAgentCard

      @PermitAll public void getAgentCard(io.vertx.ext.web.RoutingContext rc)
      Retrieves the public agent card for agent discovery.

      Maps GET /.well-known/agent-card.json to RestHandler.getAgentCard(). This is the primary discovery endpoint that clients use to understand agent capabilities, supported skills, and communication methods.

      URL Pattern: /.well-known/agent-card.json (well-known URI)

      Authentication: @PermitAll - Public endpoint requiring no authentication

      Response: JSON containing AgentCard with:

      • Agent name, description, version
      • Capabilities (streaming, push notifications)
      • Supported skills
      • Communication interfaces and protocols
      Parameters:
      rc - the Vert.x routing context

    • getExtendedAgentCard

      public void getExtendedAgentCard(io.vertx.ext.web.RoutingContext rc)
      Retrieves the extended agent card with additional metadata.

      Maps GET /{tenant}/extendedAgentCard to RestHandler.getExtendedAgentCard(org.a2aproject.sdk.server.ServerCallContext, java.lang.String). Provides tenant-specific or private capabilities beyond the public agent card.

      URL Pattern: /extendedAgentCard or /{tenant}/extendedAgentCard

      Authentication: Required (inherits @Authenticated from class)

      Parameters:
      rc - the Vert.x routing context

    • methodNotFoundMessage

      public void methodNotFoundMessage(io.vertx.ext.web.RoutingContext rc)
      Catch-all route for undefined endpoints.

      Handles all HTTP methods on unmatched paths with order=100 (lowest priority). Returns a MethodNotFoundError with HTTP 404 status.

      Purpose: Provides consistent error responses for invalid API calls instead of generic 404 HTML pages.

      Parameters:
      rc - the Vert.x routing context

    • setStreamingMultiSseSupportSubscribedRunnable

      public static void setStreamingMultiSseSupportSubscribedRunnable(Runnable runnable)