Package org.a2aproject.sdk.transport.rest.handler

Class RestHandler

java.lang.Object
org.a2aproject.sdk.transport.rest.handler.RestHandler
@ApplicationScoped public class RestHandler extends Object
REST transport handler for processing A2A protocol requests over HTTP.

This handler converts HTTP REST requests into A2A protocol operations and manages the lifecycle of agent interactions including message sending, task management, and push notification configurations.

Request Flow

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

 HTTP Request → RestHandler → RequestHandler → AgentExecutor
                    ↓              ↓
              Validation    EventQueue → Response

Supported Operations

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

Error Handling

All A2A protocol errors are caught and converted to appropriate HTTP status codes via mapErrorToHttpStatus(A2AError). Protocol version and required extensions are validated before processing requests.

CDI Integration

This handler is an @ApplicationScoped CDI bean that requires:

  • AgentCard qualified with @PublicAgentCard
  • RequestHandler for processing A2A operations
  • Executor qualified with @Internal for async operations
  • Optional AgentCard qualified with @ExtendedAgentCard
See Also:
  • RequestHandler
  • DefaultRequestHandler
  • AgentCard
  • ServerCallContext

  • Constructor Details

    • RestHandler

      protected RestHandler()
      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.

    • RestHandler

      @Inject public RestHandler(org.a2aproject.sdk.spec.AgentCard agentCard, jakarta.enterprise.inject.Instance<org.a2aproject.sdk.spec.AgentCard> extendedAgentCard, org.a2aproject.sdk.server.AgentCardCacheMetadata cacheMetadata, org.a2aproject.sdk.server.requesthandlers.RequestHandler requestHandler, Executor executor)
      Creates a REST handler with full CDI injection support.
      Parameters:
      agentCard - the public agent card containing agent capabilities
      extendedAgentCard - optional extended agent card instance
      cacheMetadata - the agent card caching metadata
      requestHandler - the handler for processing A2A requests
      executor - the executor for asynchronous operations

    • RestHandler

      public RestHandler(org.a2aproject.sdk.spec.AgentCard agentCard, org.a2aproject.sdk.server.AgentCardCacheMetadata cacheMetadata, org.a2aproject.sdk.server.requesthandlers.RequestHandler requestHandler, Executor executor)
      Creates a REST handler with basic dependencies.
      Parameters:
      agentCard - the agent card containing agent capabilities
      cacheMetadata - the agent card caching metadata
      requestHandler - the handler for processing A2A requests
      executor - the executor for asynchronous operations

  • Method Details

    • sendMessage

      public RestHandler.HTTPRestResponse sendMessage(org.a2aproject.sdk.server.ServerCallContext context, String tenant, String body)
      Handles a blocking message send request.

      This method processes an HTTP POST request containing a message to be sent to the agent. The request is validated for protocol version and required extensions before being forwarded to the RequestHandler. The method blocks until the agent produces a terminal event or requires authentication/input.

      Example Request:

      
 POST /v1/tenants/{tenant}/messages
 Content-Type: application/json

 {
   "message": {
     "parts": [
       {"text": "What is the weather in San Francisco?"}
     ]
   }
 }

      Example Response:

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

 {
   "task": {
     "id": "task-123",
     "status": {"state": "COMPLETED"},
     "artifacts": [...]
   }
 }
      Parameters:
      context - the server call context containing authentication and metadata
      tenant - the tenant identifier
      body - the JSON request body containing the message to send
      Returns:
      the HTTP response containing the task or message result
      See Also:

    • sendStreamingMessage

      public RestHandler.HTTPRestResponse sendStreamingMessage(org.a2aproject.sdk.server.ServerCallContext context, String tenant, String body)
      Handles a streaming message send request.

      This method processes an HTTP POST request for streaming responses from the agent. The response is returned as Server-Sent Events (SSE) via RestHandler.HTTPRestStreamingResponse, allowing clients to receive task updates and artifacts as they are produced by the agent.

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

      Example Request:

      
 POST /v1/tenants/{tenant}/messages/stream
 Content-Type: application/json

 {
   "message": {
     "parts": [
       {"text": "Generate a long story"}
     ]
   }
 }

      Example Streaming Response:

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

 data: {"taskStatusUpdate":{"task":{"id":"task-123","status":{"state":"WORKING"}}}}

 data: {"taskArtifactUpdate":{"taskId":"task-123","artifacts":[{"parts":[{"text":"Once upon"}]}]}}

 data: {"taskArtifactUpdate":{"taskId":"task-123","artifacts":[{"parts":[{"text":" a time..."}]}]}}

 data: {"taskStatusUpdate":{"task":{"id":"task-123","status":{"state":"COMPLETED"}}}}
      Parameters:
      context - the server call context containing authentication and metadata
      tenant - the tenant identifier
      body - the JSON request body containing the message to send
      Returns:
      the streaming HTTP response containing a publisher of events
      See Also:

    • cancelTask

      public RestHandler.HTTPRestResponse cancelTask(org.a2aproject.sdk.server.ServerCallContext context, String tenant, String body, String taskId)
      Handles a task cancellation request.

      Attempts to cancel a running task identified by the task ID. 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:

      
 POST /v1/tenants/{tenant}/tasks/{taskId}/cancel
      Parameters:
      context - the server call context containing authentication and metadata
      tenant - the tenant identifier
      body - the JSON request body
      taskId - the ID of the task to cancel
      Returns:
      the HTTP response containing the cancelled task
      Throws:
      org.a2aproject.sdk.spec.InvalidParamsError - if taskId is null or empty
      See Also:
      • RequestHandler.onCancelTask(CancelTaskParams, ServerCallContext)
      • AgentExecutor.cancel(org.a2aproject.sdk.server.agentexecution.RequestContext, org.a2aproject.sdk.server.tasks.AgentEmitter)

    • createTaskPushNotificationConfiguration

      public RestHandler.HTTPRestResponse createTaskPushNotificationConfiguration(org.a2aproject.sdk.server.ServerCallContext context, String tenant, String body, String taskId)
      Creates a push notification configuration for a task.
      Parameters:
      context - the server call context containing authentication and metadata
      tenant - the tenant identifier
      body - the JSON request body containing the configuration
      taskId - the ID of the task
      Returns:
      the HTTP response containing the created configuration

    • subscribeToTask

      public RestHandler.HTTPRestResponse subscribeToTask(org.a2aproject.sdk.server.ServerCallContext context, String tenant, String taskId)
      Subscribes to task updates via a streaming connection.

      Creates a Server-Sent Events (SSE) 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:

      
 GET /v1/tenants/{tenant}/tasks/{taskId}/subscribe

      Use Cases:

      • Reconnecting to a task after network interruption
      • Monitoring long-running tasks from multiple clients
      • Viewing historical events for completed tasks
      Parameters:
      context - the server call context containing authentication and metadata
      tenant - the tenant identifier
      taskId - the ID of the task to subscribe to
      Returns:
      the streaming HTTP response containing task updates
      See Also:

    • getTask

      public RestHandler.HTTPRestResponse getTask(org.a2aproject.sdk.server.ServerCallContext context, String tenant, String taskId, @Nullable Integer historyLength)
      Retrieves a task by ID.
      Parameters:
      context - the server call context containing authentication and metadata
      tenant - the tenant identifier
      taskId - the ID of the task to retrieve
      historyLength - the maximum number of history entries to include
      Returns:
      the HTTP response containing the task

    • listTasks

      public RestHandler.HTTPRestResponse listTasks(org.a2aproject.sdk.server.ServerCallContext context, String tenant, @Nullable String contextId, @Nullable String status, @Nullable Integer pageSize, @Nullable String pageToken, @Nullable Integer historyLength, @Nullable String statusTimestampAfter, @Nullable Boolean includeArtifacts)
      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. This method is useful for task management dashboards, monitoring systems, and task history retrieval.

      Example Request:

      
 GET /v1/tenants/{tenant}/tasks?status=COMPLETED&pageSize=10&includeArtifacts=true

      Query Parameters:

      • contextId - Filter tasks by conversation context
      • status - Filter by task state (SUBMITTED, WORKING, COMPLETED, etc.)
      • pageSize - Maximum tasks to return (for pagination)
      • pageToken - Token for retrieving next page of results
      • historyLength - Maximum history entries to include per task
      • statusTimestampAfter - ISO-8601 timestamp for filtering recent tasks
      • includeArtifacts - Whether to include task artifacts in response
      Parameters:
      context - the server call context containing authentication and metadata
      tenant - the tenant identifier
      contextId - optional context ID to filter by
      status - optional task status to filter by (must be valid TaskState value)
      pageSize - optional maximum number of tasks to return
      pageToken - optional token for pagination
      historyLength - optional maximum number of history entries per task
      statusTimestampAfter - optional ISO-8601 timestamp to filter tasks updated after
      includeArtifacts - optional flag to include task artifacts
      Returns:
      the HTTP response containing the list of tasks
      Throws:
      org.a2aproject.sdk.spec.InvalidParamsError - if status is not a valid TaskState or timestamp is malformed
      See Also:
      • RequestHandler.onListTasks(ListTasksParams, ServerCallContext)
      • TaskState

    • getTaskPushNotificationConfiguration

      public RestHandler.HTTPRestResponse getTaskPushNotificationConfiguration(org.a2aproject.sdk.server.ServerCallContext context, String tenant, String taskId, String configId)
      Retrieves a specific push notification configuration for a task.
      Parameters:
      context - the server call context containing authentication and metadata
      tenant - the tenant identifier
      taskId - the ID of the task
      configId - the ID of the configuration to retrieve
      Returns:
      the HTTP response containing the configuration

    • listTaskPushNotificationConfigurations

      public RestHandler.HTTPRestResponse listTaskPushNotificationConfigurations(org.a2aproject.sdk.server.ServerCallContext context, String tenant, String taskId, int pageSize, String pageToken)
      Lists push notification configurations for a task.
      Parameters:
      context - the server call context containing authentication and metadata
      tenant - the tenant identifier
      taskId - the ID of the task
      pageSize - the maximum number of configurations to return
      pageToken - the token for pagination
      Returns:
      the HTTP response containing the list of configurations

    • deleteTaskPushNotificationConfiguration

      public RestHandler.HTTPRestResponse deleteTaskPushNotificationConfiguration(org.a2aproject.sdk.server.ServerCallContext context, String tenant, String taskId, String configId)
      Deletes a push notification configuration for a task.
      Parameters:
      context - the server call context containing authentication and metadata
      tenant - the tenant identifier
      taskId - the ID of the task
      configId - the ID of the configuration to delete
      Returns:
      the HTTP response with no content on success

    • createErrorResponse

      public RestHandler.HTTPRestResponse createErrorResponse(org.a2aproject.sdk.spec.A2AError error)
      Creates an HTTP error response from an A2A error.
      Parameters:
      error - the A2A error to convert
      Returns:
      the HTTP response with appropriate status code and error details

    • getExtendedAgentCard

      public RestHandler.HTTPRestResponse getExtendedAgentCard(org.a2aproject.sdk.server.ServerCallContext context, String tenant)
      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:

      
 GET /v1/tenants/{tenant}/extended-agent-card
      Parameters:
      context - the server call context containing authentication and metadata
      tenant - the tenant identifier
      Returns:
      the HTTP response containing the extended agent card
      Throws:
      org.a2aproject.sdk.spec.ExtendedAgentCardNotConfiguredError - if extended agent card is not available
      See Also:

    • getAgentCard

      public RestHandler.HTTPRestResponse getAgentCard()
      Retrieves the public agent card.

      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. This is the primary discovery endpoint for clients to understand what the agent can do and how to interact with it.

      Example Request:

      
 GET /v1/agent-card

      Example Response:

      
 {
   "name": "Weather Agent",
   "description": "Provides weather information",
   "version": "1.0.0",
   "capabilities": {
     "streaming": true,
     "pushNotifications": false
   },
   "skills": [...],
   "supportedInterfaces": [...]
 }
      Returns:
      the HTTP response containing the agent card
      See Also: