7373 * manages the lifecycle of agent interactions including message sending, task
7474 * management, and push notification configurations.
7575 *
76- * <p>The handler supports both blocking and streaming operations, and validates
77- * protocol versions and required extensions before processing requests.
76+ * <h2>Request Flow</h2>
77+ * <p>HTTP REST requests flow through this handler to the underlying {@link RequestHandler},
78+ * which coordinates with the agent executor and event queue system:
79+ * <pre>
80+ * HTTP Request → RestHandler → RequestHandler → AgentExecutor
81+ * ↓ ↓
82+ * Validation EventQueue → Response
83+ * </pre>
84+ *
85+ * <h2>Supported Operations</h2>
86+ * <ul>
87+ * <li>Message sending (blocking and streaming)</li>
88+ * <li>Task management (get, list, cancel, subscribe)</li>
89+ * <li>Push notification configurations (create, get, list, delete)</li>
90+ * <li>Agent card retrieval (public and extended)</li>
91+ * </ul>
92+ *
93+ * <h2>Error Handling</h2>
94+ * <p>All A2A protocol errors are caught and converted to appropriate HTTP status codes
95+ * via {@link #mapErrorToHttpStatus(A2AError)}. Protocol version and required extensions
96+ * are validated before processing requests.
97+ *
98+ * <h2>CDI Integration</h2>
99+ * <p>This handler is an {@code @ApplicationScoped} CDI bean that requires:
100+ * <ul>
101+ * <li>{@link AgentCard} qualified with {@code @PublicAgentCard}</li>
102+ * <li>{@link RequestHandler} for processing A2A operations</li>
103+ * <li>{@link Executor} qualified with {@code @Internal} for async operations</li>
104+ * <li>Optional {@link AgentCard} qualified with {@code @ExtendedAgentCard}</li>
105+ * </ul>
106+ *
107+ * @see RequestHandler
108+ * @see io.a2a.server.requesthandlers.DefaultRequestHandler
109+ * @see io.a2a.spec.AgentCard
110+ * @see ServerCallContext
78111 */
79112@ ApplicationScoped
80113public class RestHandler {
@@ -137,10 +170,45 @@ public RestHandler(AgentCard agentCard, RequestHandler requestHandler, Executor
137170 /**
138171 * Handles a blocking message send request.
139172 *
173+ * <p>This method processes an HTTP POST request containing a message to be sent to the agent.
174+ * The request is validated for protocol version and required extensions before being forwarded
175+ * to the {@link RequestHandler}. The method blocks until the agent produces a terminal event
176+ * or requires authentication/input.
177+ *
178+ * <p><b>Example Request:</b></p>
179+ * <pre>{@code
180+ * POST /v1/tenants/{tenant}/messages
181+ * Content-Type: application/json
182+ *
183+ * {
184+ * "message": {
185+ * "parts": [
186+ * {"text": "What is the weather in San Francisco?"}
187+ * ]
188+ * }
189+ * }
190+ * }</pre>
191+ *
192+ * <p><b>Example Response:</b></p>
193+ * <pre>{@code
194+ * HTTP/1.1 200 OK
195+ * Content-Type: application/json
196+ *
197+ * {
198+ * "task": {
199+ * "id": "task-123",
200+ * "status": {"state": "COMPLETED"},
201+ * "artifacts": [...]
202+ * }
203+ * }
204+ * }</pre>
205+ *
140206 * @param context the server call context containing authentication and metadata
141207 * @param tenant the tenant identifier
142- * @param body the JSON request body
208+ * @param body the JSON request body containing the message to send
143209 * @return the HTTP response containing the task or message result
210+ * @see #sendStreamingMessage(ServerCallContext, String, String)
211+ * @see RequestHandler#onMessageSend(io.a2a.spec.MessageSendParams, ServerCallContext)
144212 */
145213 public HTTPRestResponse sendMessage (ServerCallContext context , String tenant , String body ) {
146214
@@ -162,10 +230,47 @@ public HTTPRestResponse sendMessage(ServerCallContext context, String tenant, St
162230 /**
163231 * Handles a streaming message send request.
164232 *
233+ * <p>This method processes an HTTP POST request for streaming responses from the agent.
234+ * The response is returned as Server-Sent Events (SSE) via {@link HTTPRestStreamingResponse},
235+ * allowing clients to receive task updates and artifacts as they are produced by the agent.
236+ *
237+ * <p>This method requires the agent card to have {@code capabilities.streaming = true}.
238+ *
239+ * <p><b>Example Request:</b></p>
240+ * <pre>{@code
241+ * POST /v1/tenants/{tenant}/messages/stream
242+ * Content-Type: application/json
243+ *
244+ * {
245+ * "message": {
246+ * "parts": [
247+ * {"text": "Generate a long story"}
248+ * ]
249+ * }
250+ * }
251+ * }</pre>
252+ *
253+ * <p><b>Example Streaming Response:</b></p>
254+ * <pre>{@code
255+ * HTTP/1.1 200 OK
256+ * Content-Type: text/event-stream
257+ *
258+ * data: {"taskStatusUpdate":{"task":{"id":"task-123","status":{"state":"WORKING"}}}}
259+ *
260+ * data: {"taskArtifactUpdate":{"taskId":"task-123","artifacts":[{"parts":[{"text":"Once upon"}]}]}}
261+ *
262+ * data: {"taskArtifactUpdate":{"taskId":"task-123","artifacts":[{"parts":[{"text":" a time..."}]}]}}
263+ *
264+ * data: {"taskStatusUpdate":{"task":{"id":"task-123","status":{"state":"COMPLETED"}}}}
265+ * }</pre>
266+ *
165267 * @param context the server call context containing authentication and metadata
166268 * @param tenant the tenant identifier
167- * @param body the JSON request body
269+ * @param body the JSON request body containing the message to send
168270 * @return the streaming HTTP response containing a publisher of events
271+ * @see #sendMessage(ServerCallContext, String, String)
272+ * @see RequestHandler#onMessageSendStream(io.a2a.spec.MessageSendParams, ServerCallContext)
273+ * @see HTTPRestStreamingResponse
169274 */
170275 public HTTPRestResponse sendStreamingMessage (ServerCallContext context , String tenant , String body ) {
171276 try {
@@ -189,11 +294,23 @@ public HTTPRestResponse sendStreamingMessage(ServerCallContext context, String t
189294 /**
190295 * Handles a task cancellation request.
191296 *
297+ * <p>Attempts to cancel a running task identified by the task ID. The cancellation
298+ * request is forwarded to the {@link RequestHandler}, which signals the agent executor
299+ * to stop processing. The agent should transition the task to {@code CANCELED} state.
300+ *
301+ * <p><b>Example Request:</b></p>
302+ * <pre>{@code
303+ * POST /v1/tenants/{tenant}/tasks/{taskId}/cancel
304+ * }</pre>
305+ *
192306 * @param context the server call context containing authentication and metadata
193307 * @param tenant the tenant identifier
194308 * @param body the JSON request body
195309 * @param taskId the ID of the task to cancel
196310 * @return the HTTP response containing the cancelled task
311+ * @throws InvalidParamsError if taskId is null or empty
312+ * @see RequestHandler#onCancelTask(TaskIdParams, ServerCallContext)
313+ * @see io.a2a.server.agentexecution.AgentExecutor#cancel
197314 */
198315 @ SuppressWarnings ("unchecked" )
199316 public HTTPRestResponse cancelTask (ServerCallContext context , String tenant , String body , String taskId ) {
@@ -244,10 +361,30 @@ public HTTPRestResponse createTaskPushNotificationConfiguration(ServerCallContex
244361 /**
245362 * Subscribes to task updates via a streaming connection.
246363 *
364+ * <p>Creates a Server-Sent Events (SSE) stream that delivers real-time updates for an
365+ * existing task. This allows clients to reconnect to ongoing or completed tasks and
366+ * receive their event history and future updates.
367+ *
368+ * <p>This method requires the agent card to have {@code capabilities.streaming = true}.
369+ *
370+ * <p><b>Example Request:</b></p>
371+ * <pre>{@code
372+ * GET /v1/tenants/{tenant}/tasks/{taskId}/subscribe
373+ * }</pre>
374+ *
375+ * <p><b>Use Cases:</b></p>
376+ * <ul>
377+ * <li>Reconnecting to a task after network interruption</li>
378+ * <li>Monitoring long-running tasks from multiple clients</li>
379+ * <li>Viewing historical events for completed tasks</li>
380+ * </ul>
381+ *
247382 * @param context the server call context containing authentication and metadata
248383 * @param tenant the tenant identifier
249384 * @param taskId the ID of the task to subscribe to
250385 * @return the streaming HTTP response containing task updates
386+ * @see RequestHandler#onSubscribeToTask(TaskIdParams, ServerCallContext)
387+ * @see #sendStreamingMessage(ServerCallContext, String, String)
251388 */
252389 public HTTPRestResponse subscribeToTask (ServerCallContext context , String tenant , String taskId ) {
253390 try {
@@ -291,16 +428,39 @@ public HTTPRestResponse getTask(ServerCallContext context, String tenant, String
291428 /**
292429 * Lists tasks with optional filtering and pagination.
293430 *
431+ * <p>Retrieves a list of tasks with support for filtering by context, status, and timestamp,
432+ * along with pagination controls. This method is useful for task management dashboards,
433+ * monitoring systems, and task history retrieval.
434+ *
435+ * <p><b>Example Request:</b></p>
436+ * <pre>{@code
437+ * GET /v1/tenants/{tenant}/tasks?status=COMPLETED&pageSize=10&includeArtifacts=true
438+ * }</pre>
439+ *
440+ * <p><b>Query Parameters:</b></p>
441+ * <ul>
442+ * <li>{@code contextId} - Filter tasks by conversation context</li>
443+ * <li>{@code status} - Filter by task state (SUBMITTED, WORKING, COMPLETED, etc.)</li>
444+ * <li>{@code pageSize} - Maximum tasks to return (for pagination)</li>
445+ * <li>{@code pageToken} - Token for retrieving next page of results</li>
446+ * <li>{@code historyLength} - Maximum history entries to include per task</li>
447+ * <li>{@code statusTimestampAfter} - ISO-8601 timestamp for filtering recent tasks</li>
448+ * <li>{@code includeArtifacts} - Whether to include task artifacts in response</li>
449+ * </ul>
450+ *
294451 * @param context the server call context containing authentication and metadata
295452 * @param tenant the tenant identifier
296453 * @param contextId optional context ID to filter by
297- * @param status optional task status to filter by
454+ * @param status optional task status to filter by (must be valid {@link TaskState} value)
298455 * @param pageSize optional maximum number of tasks to return
299456 * @param pageToken optional token for pagination
300457 * @param historyLength optional maximum number of history entries per task
301458 * @param statusTimestampAfter optional ISO-8601 timestamp to filter tasks updated after
302459 * @param includeArtifacts optional flag to include task artifacts
303460 * @return the HTTP response containing the list of tasks
461+ * @throws InvalidParamsError if status is not a valid TaskState or timestamp is malformed
462+ * @see RequestHandler#onListTasks(ListTasksParams, ServerCallContext)
463+ * @see TaskState
304464 */
305465 public HTTPRestResponse listTasks (ServerCallContext context , String tenant ,
306466 @ Nullable String contextId , @ Nullable String status ,
@@ -552,6 +712,24 @@ public void onComplete() {
552712 });
553713 }
554714
715+ /**
716+ * Maps A2A protocol errors to HTTP status codes.
717+ *
718+ * <p>This method ensures consistent HTTP status code mapping for all A2A errors:
719+ * <ul>
720+ * <li>400 - Invalid request, JSON parse errors, missing extensions</li>
721+ * <li>404 - Method not found, task not found</li>
722+ * <li>409 - Task not cancelable (conflict)</li>
723+ * <li>415 - Unsupported content type</li>
724+ * <li>422 - Invalid parameters (unprocessable entity)</li>
725+ * <li>500 - Internal errors</li>
726+ * <li>501 - Not implemented (unsupported operations, version)</li>
727+ * <li>502 - Bad gateway (invalid agent response)</li>
728+ * </ul>
729+ *
730+ * @param error the A2A error to map
731+ * @return the corresponding HTTP status code
732+ */
555733 private int mapErrorToHttpStatus (A2AError error ) {
556734 if (error instanceof InvalidRequestError || error instanceof JSONParseError ) {
557735 return 400 ;
@@ -589,9 +767,22 @@ private int mapErrorToHttpStatus(A2AError error) {
589767 /**
590768 * Retrieves the extended agent card if configured.
591769 *
770+ * <p>The extended agent card provides additional metadata beyond the public agent card,
771+ * such as tenant-specific configurations or private capabilities. This endpoint requires
772+ * the agent card to have {@code capabilities.extendedAgentCard = true} and a CDI-produced
773+ * {@code @ExtendedAgentCard} instance.
774+ *
775+ * <p><b>Example Request:</b></p>
776+ * <pre>{@code
777+ * GET /v1/tenants/{tenant}/extended-agent-card
778+ * }</pre>
779+ *
592780 * @param context the server call context containing authentication and metadata
593781 * @param tenant the tenant identifier
594782 * @return the HTTP response containing the extended agent card
783+ * @throws ExtendedAgentCardNotConfiguredError if extended agent card is not available
784+ * @see #getAgentCard()
785+ * @see AgentCard
595786 */
596787 public HTTPRestResponse getExtendedAgentCard (ServerCallContext context , String tenant ) {
597788 try {
@@ -609,7 +800,34 @@ public HTTPRestResponse getExtendedAgentCard(ServerCallContext context, String t
609800 /**
610801 * Retrieves the public agent card.
611802 *
803+ * <p>The agent card is a self-describing manifest that provides essential metadata about
804+ * the agent, including its capabilities, supported skills, communication methods, and
805+ * security requirements. This is the primary discovery endpoint for clients to understand
806+ * what the agent can do and how to interact with it.
807+ *
808+ * <p><b>Example Request:</b></p>
809+ * <pre>{@code
810+ * GET /v1/agent-card
811+ * }</pre>
812+ *
813+ * <p><b>Example Response:</b></p>
814+ * <pre>{@code
815+ * {
816+ * "name": "Weather Agent",
817+ * "description": "Provides weather information",
818+ * "version": "1.0.0",
819+ * "capabilities": {
820+ * "streaming": true,
821+ * "pushNotifications": false
822+ * },
823+ * "skills": [...],
824+ * "supportedInterfaces": [...]
825+ * }
826+ * }</pre>
827+ *
612828 * @return the HTTP response containing the agent card
829+ * @see AgentCard
830+ * @see #getExtendedAgentCard(ServerCallContext, String)
613831 */
614832 public HTTPRestResponse getAgentCard () {
615833 try {
0 commit comments