Class JSONRPCHandler

java.lang.Object
org.a2aproject.sdk.transport.jsonrpc.handler.JSONRPCHandler
@ApplicationScoped public class JSONRPCHandler extends Object
JSON-RPC 2.0 transport handler for processing A2A protocol requests over HTTP.

This handler converts JSON-RPC 2.0 requests into A2A protocol operations and manages the lifecycle of agent interactions. It supports both blocking request/response and streaming responses via Server-Sent Events.

Request Flow

JSON-RPC requests flow through this handler to the underlying RequestHandler, which coordinates with the agent executor and event queue system: 

JSON-RPC Request → JSONRPCHandler → RequestHandler → AgentExecutor
                        ↓               ↓
                  Validation      EventQueue → Response

JSON-RPC 2.0 Format

Requests follow the JSON-RPC 2.0 specification: 

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

Responses include the request ID for correlation: 

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

Supported Operations

  • Message sending (blocking and streaming)
  • Task management (get, list, cancel, subscribe)
  • Push notification configurations (create, get, list, delete)

Error Handling

All A2A protocol errors are caught and converted to JSON-RPC error responses with the error object embedded in the response. Protocol version and required extensions are validated before processing requests.

Streaming Support

Streaming methods (sendStreamingMessage, subscribeToTask) return a Flow.Publisher of JSON-RPC responses, allowing Server-Sent Events delivery when used with Quarkus/Vert.x transport layers.

CDI Integration

This handler is an @ApplicationScoped CDI bean that requires:

See Also:

  • Constructor Details

    • JSONRPCHandler

      protected JSONRPCHandler()
      No-args constructor for CDI proxy creation. CDI requires a non-private constructor to create proxies for @ApplicationScoped beans. All fields are initialized by the @Inject constructor during actual bean creation.

    • JSONRPCHandler

      @Inject public JSONRPCHandler(jakarta.enterprise.inject.Instance<AgentCard> agentCardInstance, @Nullable jakarta.enterprise.inject.Instance<AgentCard> extendedAgentCard, RequestHandler requestHandler, Executor executor, @Any @Nullable jakarta.enterprise.inject.Instance<AgentCardRouter> agentCardRouterInstance)
      Creates a JSON-RPC handler with full CDI injection support.
      Parameters:
      agentCardInstance - the public agent card instance containing agent capabilities
      extendedAgentCard - optional extended agent card instance
      requestHandler - the handler for processing A2A requests
      executor - the executor for asynchronous operations
      agentCardRouterInstance - optional agent card router instance for multitenancy

    • JSONRPCHandler

      public JSONRPCHandler(@Nullable AgentCard agentCard, RequestHandler requestHandler, Executor executor)
      Creates a JSON-RPC handler with basic dependencies.
      Parameters:
      agentCard - the agent card containing agent capabilities, or null if no public card
      requestHandler - the handler for processing A2A requests
      executor - the executor for asynchronous operations

  • Method Details

    • onMessageSend

      public SendMessageResponse onMessageSend(SendMessageRequest request, ServerCallContext context)
      Handles a blocking message send request.

      This method processes a JSON-RPC sendMessage request containing a message to be sent to the agent. The method blocks until the agent produces a terminal event or requires authentication/input.

      Example Request: 

      {
  "jsonrpc": "2.0",
  "id": "msg-123",
  "method": "sendMessage",
  "params": {
    "message": {
      "parts": [{"text": "What is the weather?"}]
    }
  }
}

      Example Response: 

      {
  "jsonrpc": "2.0",
  "id": "msg-123",
  "result": {
    "task": {
      "id": "task-456",
      "status": {"state": "COMPLETED"},
      "artifacts": [...]
    }
  }
}
      Parameters:
      request - the JSON-RPC request containing message params
      context - the server call context containing authentication and metadata
      Returns:
      JSON-RPC response with task or message result
      See Also:

    • onMessageSendStream

      public Flow.Publisher<SendStreamingMessageResponse> onMessageSendStream(SendStreamingMessageRequest request, ServerCallContext context)
      Handles a streaming message send request.

      This method processes a JSON-RPC sendStreamingMessage request for streaming responses from the agent. The response is returned as a Flow.Publisher of JSON-RPC response objects, allowing Server-Sent Events delivery.

      This method requires the agent card to have capabilities.streaming = true.

      Example Request: 

      {
  "jsonrpc": "2.0",
  "id": "stream-123",
  "method": "sendStreamingMessage",
  "params": {
    "message": {
      "parts": [{"text": "Generate a story"}]
    }
  }
}

      Example Streaming Responses: 

      {"jsonrpc":"2.0","id":"stream-123","result":{"taskStatusUpdate":{...}}}
{"jsonrpc":"2.0","id":"stream-123","result":{"taskArtifactUpdate":{...}}}
{"jsonrpc":"2.0","id":"stream-123","result":{"taskStatusUpdate":{...}}}
      Parameters:
      request - the JSON-RPC request containing message params
      context - the server call context containing authentication and metadata
      Returns:
      publisher of JSON-RPC response objects containing streaming events
      See Also:

    • onCancelTask

      public CancelTaskResponse onCancelTask(CancelTaskRequest request, ServerCallContext context)
      Handles a task cancellation request.

      Attempts to cancel a running task identified by the task ID in the request params. The cancellation request is forwarded to the RequestHandler, which signals the agent executor to stop processing. The agent should transition the task to CANCELED state.

      Example Request: 

      {
  "jsonrpc": "2.0",
  "id": "cancel-123",
  "method": "cancelTask",
  "params": {
    "taskId": "task-456"
  }
}
      Parameters:
      request - the JSON-RPC request containing task ID params
      context - the server call context containing authentication and metadata
      Returns:
      JSON-RPC response with the cancelled task
      See Also:

    • onSubscribeToTask

      public Flow.Publisher<SendStreamingMessageResponse> onSubscribeToTask(SubscribeToTaskRequest request, ServerCallContext context) throws A2AError
      Subscribes to task updates via a streaming connection.

      Creates a stream that delivers real-time updates for an existing task. This allows clients to reconnect to ongoing or completed tasks and receive their event history and future updates.

      This method requires the agent card to have capabilities.streaming = true.

      Example Request: 

      {
  "jsonrpc": "2.0",
  "id": "subscribe-123",
  "method": "subscribeToTask",
  "params": {
    "taskId": "task-456"
  }
}

      Use Cases:

      • Reconnecting to a task after network interruption
      • Monitoring long-running tasks from multiple clients
      • Viewing historical events for completed tasks
      Parameters:
      request - the JSON-RPC request containing task ID params
      context - the server call context containing authentication and metadata
      Returns:
      publisher of JSON-RPC response objects containing task updates
      Throws:
      A2AError
      See Also:

    • getPushNotificationConfig

      public GetTaskPushNotificationConfigResponse getPushNotificationConfig(GetTaskPushNotificationConfigRequest request, ServerCallContext context)
      Retrieves a specific push notification configuration.

      Returns the push notification configuration for a task by config ID. This method requires the agent card to have capabilities.pushNotifications = true.

      Example Request: 

      {
  "jsonrpc": "2.0",
  "id": "get-config-123",
  "method": "getTaskPushNotificationConfig",
  "params": {
    "taskId": "task-456",
    "configId": "config-789"
  }
}
      Parameters:
      request - the JSON-RPC request containing task and config ID params
      context - the server call context containing authentication and metadata
      Returns:
      JSON-RPC response with the configuration
      See Also:

    • setPushNotificationConfig

      public CreateTaskPushNotificationConfigResponse setPushNotificationConfig(CreateTaskPushNotificationConfigRequest request, ServerCallContext context)
      Creates a push notification configuration for a task.

      Creates a new push notification configuration specifying webhook URL and event filters. This method requires the agent card to have capabilities.pushNotifications = true.

      Example Request: 

      {
  "jsonrpc": "2.0",
  "id": "create-config-123",
  "method": "setTaskPushNotificationConfig",
  "params": {
    "taskId": "task-456",
    "url": "https://webhook.example.com/notify",
    "events": ["taskStatusUpdate", "taskArtifactUpdate"]
  }
}
      Parameters:
      request - the JSON-RPC request containing push notification config params
      context - the server call context containing authentication and metadata
      Returns:
      JSON-RPC response with the created configuration
      See Also:

    • onGetTask

      public GetTaskResponse onGetTask(GetTaskRequest request, ServerCallContext context)
      Retrieves a specific task by ID.

      Returns the complete task object including status, artifacts, and optionally task history based on the historyLength parameter.

      Example Request: 

      {
  "jsonrpc": "2.0",
  "id": "get-123",
  "method": "getTask",
  "params": {
    "taskId": "task-456",
    "historyLength": 10
  }
}
      Parameters:
      request - the JSON-RPC request containing task query params
      context - the server call context containing authentication and metadata
      Returns:
      JSON-RPC response with the task object
      See Also:

    • onListTasks

      public ListTasksResponse onListTasks(ListTasksRequest request, ServerCallContext context)
      Lists tasks with optional filtering and pagination.

      Retrieves a list of tasks with support for filtering by context, status, and timestamp, along with pagination controls.

      Example Request: 

      {
  "jsonrpc": "2.0",
  "id": "list-123",
  "method": "listTasks",
  "params": {
    "status": "COMPLETED",
    "pageSize": 10,
    "includeArtifacts": true
  }
}

      Query Parameters:

      • contextId - Filter tasks by conversation context
      • status - Filter by task state
      • pageSize - Maximum tasks to return
      • pageToken - Token for pagination
      • historyLength - Max history entries per task
      • statusTimestampAfter - ISO-8601 timestamp filter
      • includeArtifacts - Include task artifacts
      Parameters:
      request - the JSON-RPC request containing list tasks params
      context - the server call context containing authentication and metadata
      Returns:
      JSON-RPC response with list of tasks
      See Also:

    • listPushNotificationConfigs

      public ListTaskPushNotificationConfigsResponse listPushNotificationConfigs(ListTaskPushNotificationConfigsRequest request, ServerCallContext context)
      Lists push notification configurations for a task.

      Returns a paginated list of push notification configurations associated with a task. This method requires the agent card to have capabilities.pushNotifications = true.

      Example Request: 

      {
  "jsonrpc": "2.0",
  "id": "list-config-123",
  "method": "listTaskPushNotificationConfigs",
  "params": {
    "taskId": "task-456",
    "pageSize": 10
  }
}
      Parameters:
      request - the JSON-RPC request containing task ID and pagination params
      context - the server call context containing authentication and metadata
      Returns:
      JSON-RPC response with list of configurations
      See Also:

    • deletePushNotificationConfig

      public DeleteTaskPushNotificationConfigResponse deletePushNotificationConfig(DeleteTaskPushNotificationConfigRequest request, ServerCallContext context)
      Deletes a push notification configuration.

      Removes a push notification configuration by config ID, stopping notifications for the associated task. This method requires the agent card to have capabilities.pushNotifications = true.

      Example Request: 

      {
  "jsonrpc": "2.0",
  "id": "delete-config-123",
  "method": "deleteTaskPushNotificationConfig",
  "params": {
    "taskId": "task-456",
    "configId": "config-789"
  }
}
      Parameters:
      request - the JSON-RPC request containing task and config ID params
      context - the server call context containing authentication and metadata
      Returns:
      JSON-RPC response confirming deletion
      See Also:

    • onGetExtendedCardRequest

      public GetExtendedAgentCardResponse onGetExtendedCardRequest(GetExtendedAgentCardRequest request, ServerCallContext context)
      Retrieves the extended agent card if configured.

      The extended agent card provides additional metadata beyond the public agent card, such as tenant-specific configurations or private capabilities. This endpoint requires the agent card to have capabilities.extendedAgentCard = true and a CDI-produced @ExtendedAgentCard instance.

      Example Request: 

      {
  "jsonrpc": "2.0",
  "id": "ext-card-123",
  "method": "getExtendedAgentCard",
  "params": {}
}
      Parameters:
      request - the JSON-RPC request for extended agent card
      context - the server call context containing authentication and metadata
      Returns:
      JSON-RPC response with the extended agent card
      See Also:

    • getAgentCard

      public @Nullable AgentCard getAgentCard()
      Returns the public agent card, or null if no @PublicAgentCard bean is configured.

      The agent card is a self-describing manifest that provides essential metadata about the agent, including its capabilities, supported skills, communication methods, and security requirements.

      Returns:
      the public agent card, or null if not configured
      See Also:

    • getAgentCard

      public @Nullable AgentCard getAgentCard(@Nullable String tenant)
      Returns the public agent card, optionally for a specific tenant.

      When a tenant is specified and an AgentCardRouter is available, the router resolves the card. If the router returns null the tenant is unknown and a TenantNotFoundException is thrown (callers should map this to HTTP 404).

      When no router is configured, any non-blank tenant is logged and the default card is returned (single-tenant server, tenant segment is ignored).

      Parameters:
      tenant - the tenant identifier, may be null
      Returns:
      the public agent card, or null if no @PublicAgentCard bean is configured
      Throws:
      TenantNotFoundException - if a router is configured but the tenant is not registered

    • authorizeTaskAccess

      public void authorizeTaskAccess(String requestedTaskId, ServerCallContext context, TaskOperation operation)