Package org.a2aproject.sdk.server.apps.quarkus

Class A2AServerRoutes

java.lang.Object
org.a2aproject.sdk.server.apps.quarkus.A2AServerRoutes
@Singleton public class A2AServerRoutes extends Object
Quarkus routing configuration for JSON-RPC A2A protocol requests.

This class defines Vert.x Web routes for handling JSON-RPC 2.0 requests over HTTP, processing them through the JSONRPCHandler, and returning responses in either standard JSON or Server-Sent Events (SSE) format for streaming operations.

Request Flow

 HTTP POST / → invokeJSONRPCHandler()
     ↓
 Parse JSON-RPC request body
     ↓
 Route to handler method (blocking or streaming)
     ↓
 JSONRPCHandler → RequestHandler → AgentExecutor
     ↓
 Response (JSON or SSE stream)

Supported Operations

Non-Streaming (JSON responses):

  • sendMessage - Send message and wait for completion
  • getTask - Retrieve task by ID
  • cancelTask - Cancel task execution
  • listTasks - List tasks with filtering
  • setTaskPushNotificationConfig - Configure push notifications
  • getTaskPushNotificationConfig - Get push notification config
  • listTaskPushNotificationConfigs - List push notification configs
  • deleteTaskPushNotificationConfig - Delete push notification config
  • getExtendedAgentCard - Get extended agent capabilities

Streaming (SSE responses):

  • sendStreamingMessage - Send message with streaming response
  • subscribeToTask - Subscribe to task events

JSON-RPC Request Format


 POST /
 Content-Type: application/json

 {
   "jsonrpc": "2.0",
   "id": "req-123",
   "method": "sendMessage",
   "params": {
     "message": {
       "parts": [{"text": "Hello"}]
     }
   }
 }

Error Handling

Errors are mapped to JSON-RPC 2.0 error responses:

CDI Integration

This class is a CDI @Singleton that automatically wires:

Multi-Tenancy Support

Tenant identification is extracted from the request path:

  • POST / → empty tenant
  • POST /tenant1 → tenant "tenant1"
  • POST /tenant1/ → tenant "tenant1" (trailing slash stripped)
See Also:

  • Constructor Details

    • A2AServerRoutes

      public A2AServerRoutes()

  • Method Details

    • invokeJSONRPCHandler

      public void invokeJSONRPCHandler(String body, io.vertx.ext.web.RoutingContext rc)
      Main entry point for all JSON-RPC requests.

      This route handler processes JSON-RPC 2.0 requests, dispatches them to the appropriate handler method based on the request type (streaming vs non-streaming), and returns either a JSON response or an SSE stream.

      Request Format: 

      
 POST /[tenant]
 Content-Type: application/json

 {
   "jsonrpc": "2.0",
   "id": "req-123",
   "method": "sendMessage",
   "params": { ... }
 }

      Non-Streaming Response: 

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

 {
   "jsonrpc": "2.0",
   "id": "req-123",
   "result": { ... }
 }

      Streaming Response (SSE): 

      
 HTTP/1.1 200 OK
 Content-Type: text/event-stream

 id: 0
 data: {"jsonrpc":"2.0","id":"req-123","result":{...}}

 id: 1
 data: {"jsonrpc":"2.0","id":"req-123","result":{...}}

      Error Response: 

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

 {
   "jsonrpc": "2.0",
   "id": "req-123",
   "error": {
     "code": -32602,
     "message": "Invalid params"
   }
 }

      Processing Flow:

      1. Parse JSON-RPC request body using JSONRPCUtils.parseRequestBody(String, String)
      2. Create ServerCallContext from routing context
      3. Route to streaming or non-streaming handler
      4. Handle errors with appropriate JSON-RPC error codes
      5. Return JSON response or start SSE stream
      Parameters:
      body - the raw JSON-RPC request body
      rc - the Vert.x routing context containing HTTP request/response
      Throws:
      A2AError - if request processing fails

    • getAgentCard

      public String getAgentCard(io.vertx.ext.web.RoutingContext rc) throws JsonProcessingException
      Handles GET requests to the agent card endpoint.

      Returns the agent's capabilities and metadata in JSON format according to the A2A protocol specification. This endpoint is publicly accessible (no authentication).

      Includes HTTP caching headers per A2A specification section 8.6:

      • Cache-Control - with max-age directive
      • ETag - content hash for validation
      • Last-Modified - timestamp when agent card was initialized

      Request: 

      
 GET /.well-known/agent-card.json

      Response: 

      
 HTTP/1.1 200 OK
 Content-Type: application/json
 Cache-Control: public, max-age=3600
 ETag: "a1b2c3d4..."
 Last-Modified: Mon, 17 Mar 2025 10:00:00 GMT

 {
   "name": "My Agent",
   "description": "Agent description",
   "capabilities": {
     "streaming": true,
     "pushNotifications": false
   },
   ...
 }
      Parameters:
      rc - the Vert.x routing context
      Returns:
      the agent card as a JSON string
      Throws:
      JsonProcessingException - if serialization fails
      See Also:

    • setStreamingMultiSseSupportSubscribedRunnable

      public static void setStreamingMultiSseSupportSubscribedRunnable(Runnable runnable)
      Sets a callback to be invoked when SSE streaming subscription starts.

      This is a testing hook used to synchronize test execution with streaming setup. In production, this remains null.

      Parameters:
      runnable - the callback to invoke on subscription