a2a.server.request_handlers package¶

Submodules¶

a2a.server.request_handlers.default_request_handler module¶

class a2a.server.request_handlers.default_request_handler.DefaultRequestHandler(agent_executor: AgentExecutor, task_store: TaskStore, queue_manager: QueueManager | None = None, push_config_store: PushNotificationConfigStore | None = None, push_sender: PushNotificationSender | None = None, request_context_builder: RequestContextBuilder | None = None)¶

Bases: RequestHandler

Default request handler for all incoming requests.

This handler provides default implementations for all A2A JSON-RPC methods, coordinating between the AgentExecutor, TaskStore, QueueManager, and optional PushNotifier.

async on_cancel_task(params: TaskIdParams, context: ServerCallContext | None = None) → Task | None¶

Default handler for ‘tasks/cancel’.

Attempts to cancel the task managed by the AgentExecutor.

async on_delete_task_push_notification_config(params: DeleteTaskPushNotificationConfigParams, context: ServerCallContext | None = None) → None¶

Default handler for ‘tasks/pushNotificationConfig/delete’.

Requires a PushConfigStore to be configured.

async on_get_task(params: TaskQueryParams, context: ServerCallContext | None = None) → Task | None¶: Default handler for ‘tasks/get’.

async on_get_task_push_notification_config(params: TaskIdParams | GetTaskPushNotificationConfigParams, context: ServerCallContext | None = None) → TaskPushNotificationConfig¶

Default handler for ‘tasks/pushNotificationConfig/get’.

Requires a PushConfigStore to be configured.

async on_list_task_push_notification_config(params: ListTaskPushNotificationConfigParams, context: ServerCallContext | None = None) → list[TaskPushNotificationConfig]¶

Default handler for ‘tasks/pushNotificationConfig/list’.

Requires a PushConfigStore to be configured.

async on_message_send(params: MessageSendParams, context: ServerCallContext | None = None) → Message | Task¶

Default handler for ‘message/send’ interface (non-streaming).

Starts the agent execution for the message and waits for the final result (Task or Message).

on_message_send_stream(params: MessageSendParams, context: ServerCallContext | None = None) → AsyncGenerator[Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent]¶

Default handler for ‘message/stream’ (streaming).

Starts the agent execution and yields events as they are produced by the agent.

on_resubscribe_to_task(params: TaskIdParams, context: ServerCallContext | None = None) → AsyncGenerator[Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent]¶

Default handler for ‘tasks/resubscribe’.

Allows a client to re-attach to a running streaming task’s event stream. Requires the task and its queue to still be active.

async on_set_task_push_notification_config(params: TaskPushNotificationConfig, context: ServerCallContext | None = None) → TaskPushNotificationConfig¶

Default handler for ‘tasks/pushNotificationConfig/set’.

Requires a PushNotifier to be configured.

a2a.server.request_handlers.grpc_handler module¶

a2a.server.request_handlers.jsonrpc_handler module¶

class a2a.server.request_handlers.jsonrpc_handler.JSONRPCHandler(agent_card: AgentCard, request_handler: RequestHandler, extended_agent_card: AgentCard | None = None, extended_card_modifier: Callable[[AgentCard, ServerCallContext], AgentCard] | None = None)¶

Bases: object

Maps incoming JSON-RPC requests to the appropriate request handler method and formats responses.

async delete_push_notification_config(request: DeleteTaskPushNotificationConfigRequest, context: ServerCallContext | None = None) → DeleteTaskPushNotificationConfigResponse¶

Handles the ‘tasks/pushNotificationConfig/list’ JSON-RPC method.

Parameters:

request – The incoming DeleteTaskPushNotificationConfigRequest object.
context – Context provided by the server.

Returns:

A DeleteTaskPushNotificationConfigResponse object containing the config or a JSON-RPC error.

async get_authenticated_extended_card(request: GetAuthenticatedExtendedCardRequest, context: ServerCallContext | None = None) → GetAuthenticatedExtendedCardResponse¶

Handles the ‘agent/authenticatedExtendedCard’ JSON-RPC method.

Parameters:

request – The incoming GetAuthenticatedExtendedCardRequest object.
context – Context provided by the server.

Returns:

A GetAuthenticatedExtendedCardResponse object containing the config or a JSON-RPC error.

async get_push_notification_config(request: GetTaskPushNotificationConfigRequest, context: ServerCallContext | None = None) → GetTaskPushNotificationConfigResponse¶

Handles the ‘tasks/pushNotificationConfig/get’ JSON-RPC method.

Parameters:

request – The incoming GetTaskPushNotificationConfigRequest object.
context – Context provided by the server.

Returns:

A GetTaskPushNotificationConfigResponse object containing the config or a JSON-RPC error.

async list_push_notification_config(request: ListTaskPushNotificationConfigRequest, context: ServerCallContext | None = None) → ListTaskPushNotificationConfigResponse¶

Handles the ‘tasks/pushNotificationConfig/list’ JSON-RPC method.

Parameters:

request – The incoming ListTaskPushNotificationConfigRequest object.
context – Context provided by the server.

Returns:

A ListTaskPushNotificationConfigResponse object containing the config or a JSON-RPC error.

async on_cancel_task(request: CancelTaskRequest, context: ServerCallContext | None = None) → CancelTaskResponse¶

Handles the ‘tasks/cancel’ JSON-RPC method.

Parameters:

request – The incoming CancelTaskRequest object.
context – Context provided by the server.

Returns:

A CancelTaskResponse object containing the updated Task or a JSON-RPC error.

async on_get_task(request: GetTaskRequest, context: ServerCallContext | None = None) → GetTaskResponse¶

Handles the ‘tasks/get’ JSON-RPC method.

Parameters:

request – The incoming GetTaskRequest object.
context – Context provided by the server.

Returns:

A GetTaskResponse object containing the Task or a JSON-RPC error.

async on_message_send(request: SendMessageRequest, context: ServerCallContext | None = None) → SendMessageResponse¶

Handles the ‘message/send’ JSON-RPC method.

Parameters:

request – The incoming SendMessageRequest object.
context – Context provided by the server.

Returns:

A SendMessageResponse object containing the result (Task or Message) or a JSON-RPC error response if a ServerError is raised by the handler.

on_message_send_stream(request: SendStreamingMessageRequest, context: ServerCallContext | None = None) → AsyncIterable[SendStreamingMessageResponse]¶

Handles the ‘message/stream’ JSON-RPC method.

Yields response objects as they are produced by the underlying handler’s stream.

Parameters:

request – The incoming SendStreamingMessageRequest object.
context – Context provided by the server.

Yields:

SendStreamingMessageResponse objects containing streaming events (Task, Message, TaskStatusUpdateEvent, TaskArtifactUpdateEvent) or JSON-RPC error responses if a ServerError is raised.

on_resubscribe_to_task(request: TaskResubscriptionRequest, context: ServerCallContext | None = None) → AsyncIterable[SendStreamingMessageResponse]¶

Handles the ‘tasks/resubscribe’ JSON-RPC method.

Yields response objects as they are produced by the underlying handler’s stream.

Parameters:

request – The incoming TaskResubscriptionRequest object.
context – Context provided by the server.

Yields:

SendStreamingMessageResponse objects containing streaming events or JSON-RPC error responses if a ServerError is raised.

async set_push_notification_config(request: SetTaskPushNotificationConfigRequest, context: ServerCallContext | None = None) → SetTaskPushNotificationConfigResponse¶

Handles the ‘tasks/pushNotificationConfig/set’ JSON-RPC method.

Requires the agent to support push notifications.

Parameters:

request – The incoming SetTaskPushNotificationConfigRequest object.
context – Context provided by the server.

Returns:

A SetTaskPushNotificationConfigResponse object containing the config or a JSON-RPC error.

Raises:

ServerError – If push notifications are not supported by the agent (due to the @validate decorator).

a2a.server.request_handlers.request_handler module¶

class a2a.server.request_handlers.request_handler.RequestHandler¶

Bases: ABC

A2A request handler interface.

This interface defines the methods that an A2A server implementation must provide to handle incoming JSON-RPC requests.

abstractmethod async on_cancel_task(params: TaskIdParams, context: ServerCallContext | None = None) → Task | None¶

Handles the ‘tasks/cancel’ method.

Requests the agent to cancel an ongoing task.

Parameters:

params – Parameters specifying the task ID.
context – Context provided by the server.

Returns:

The Task object with its status updated to canceled, or None if the task was not found.

abstractmethod async on_delete_task_push_notification_config(params: DeleteTaskPushNotificationConfigParams, context: ServerCallContext | None = None) → None¶

Handles the ‘tasks/pushNotificationConfig/delete’ method.

Deletes a push notification configuration associated with a task.

Parameters:

params – Parameters including the task ID.
context – Context provided by the server.

Returns:

None

abstractmethod async on_get_task(params: TaskQueryParams, context: ServerCallContext | None = None) → Task | None¶

Handles the ‘tasks/get’ method.

Retrieves the state and history of a specific task.

Parameters:

params – Parameters specifying the task ID and optionally history length.
context – Context provided by the server.

Returns:

The Task object if found, otherwise None.

abstractmethod async on_get_task_push_notification_config(params: TaskIdParams | GetTaskPushNotificationConfigParams, context: ServerCallContext | None = None) → TaskPushNotificationConfig¶

Handles the ‘tasks/pushNotificationConfig/get’ method.

Retrieves the current push notification configuration for a task.

Parameters:

params – Parameters including the task ID.
context – Context provided by the server.

Returns:

The TaskPushNotificationConfig for the task.

abstractmethod async on_list_task_push_notification_config(params: ListTaskPushNotificationConfigParams, context: ServerCallContext | None = None) → list[TaskPushNotificationConfig]¶

Handles the ‘tasks/pushNotificationConfig/list’ method.

Retrieves the current push notification configurations for a task.

Parameters:

params – Parameters including the task ID.
context – Context provided by the server.

Returns:

The list[TaskPushNotificationConfig] for the task.

abstractmethod async on_message_send(params: MessageSendParams, context: ServerCallContext | None = None) → Task | Message¶

Handles the ‘message/send’ method (non-streaming).

Sends a message to the agent to create, continue, or restart a task, and waits for the final result (Task or Message).

Parameters:

params – Parameters including the message and configuration.
context – Context provided by the server.

Returns:

The final Task object or a final Message object.

abstractmethod async on_message_send_stream(params: MessageSendParams, context: ServerCallContext | None = None) → AsyncGenerator[Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent]¶

Handles the ‘message/stream’ method (streaming).

Sends a message to the agent and yields stream events as they are produced (Task updates, Message chunks, Artifact updates).

Parameters:

params – Parameters including the message and configuration.
context – Context provided by the server.

Yields:

Event objects from the agent’s execution.

Raises:

ServerError(UnsupportedOperationError) – By default, if not implemented.

abstractmethod async on_resubscribe_to_task(params: TaskIdParams, context: ServerCallContext | None = None) → AsyncGenerator[Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent]¶

Handles the ‘tasks/resubscribe’ method.

Allows a client to re-subscribe to a running streaming task’s event stream.

Parameters:

params – Parameters including the task ID.
context – Context provided by the server.

Yields:

Event objects from the agent’s ongoing execution for the specified task.

Raises:

ServerError(UnsupportedOperationError) – By default, if not implemented.

abstractmethod async on_set_task_push_notification_config(params: TaskPushNotificationConfig, context: ServerCallContext | None = None) → TaskPushNotificationConfig¶

Handles the ‘tasks/pushNotificationConfig/set’ method.

Sets or updates the push notification configuration for a task.

Parameters:

params – Parameters including the task ID and push notification configuration.
context – Context provided by the server.

Returns:

The provided TaskPushNotificationConfig upon success.

a2a.server.request_handlers.response_helpers module¶

Helper functions for building A2A JSON-RPC responses.

a2a.server.request_handlers.response_helpers.EventTypes = a2a.types.Task | a2a.types.Message | a2a.types.TaskArtifactUpdateEvent | a2a.types.TaskStatusUpdateEvent | a2a.types.TaskPushNotificationConfig | a2a.types.A2AError | a2a.types.JSONRPCError | list[a2a.types.TaskPushNotificationConfig]¶: Type alias for possible event types produced by handlers.

class a2a.server.request_handlers.response_helpers.RT¶

Type variable for RootModel response types.

alias of TypeVar(‘RT’, ~a2a.types.GetTaskResponse, ~a2a.types.CancelTaskResponse, ~a2a.types.SendMessageResponse, ~a2a.types.SetTaskPushNotificationConfigResponse, ~a2a.types.GetTaskPushNotificationConfigResponse, ~a2a.types.SendStreamingMessageResponse, ~a2a.types.ListTaskPushNotificationConfigResponse, ~a2a.types.DeleteTaskPushNotificationConfigResponse)

class a2a.server.request_handlers.response_helpers.SPT¶

Type variable for SuccessResponse types.

alias of TypeVar(‘SPT’, ~a2a.types.GetTaskSuccessResponse, ~a2a.types.CancelTaskSuccessResponse, ~a2a.types.SendMessageSuccessResponse, ~a2a.types.SetTaskPushNotificationConfigSuccessResponse, ~a2a.types.GetTaskPushNotificationConfigSuccessResponse, ~a2a.types.SendStreamingMessageSuccessResponse, ~a2a.types.ListTaskPushNotificationConfigSuccessResponse, ~a2a.types.DeleteTaskPushNotificationConfigSuccessResponse)

a2a.server.request_handlers.response_helpers.build_error_response(request_id: str | int | None, error: A2AError | JSONRPCError, response_wrapper_type: type[RT]) → RT¶

Helper method to build a JSONRPCErrorResponse wrapped in the appropriate response type.

Parameters:

request_id – The ID of the request that caused the error.
error – The A2AError or JSONRPCError object.
response_wrapper_type – The Pydantic RootModel type that wraps the response for the specific RPC method (e.g., SendMessageResponse).

Returns:

A Pydantic model representing the JSON-RPC error response, wrapped in the specified response type.

Helper method to build appropriate JSONRPCResponse object for RPC methods.

Based on the type of the response object received from the handler, it constructs either a success response wrapped in the appropriate payload type or an error response.

Parameters:

request_id – The ID of the request.
response – The object received from the request handler.
success_response_types – A tuple of expected Pydantic model types for a successful result.
success_payload_type – The Pydantic model type for the success payload (e.g., SendMessageSuccessResponse).
response_type – The Pydantic RootModel type that wraps the final response (e.g., SendMessageResponse).

Returns:

A Pydantic model representing the final JSON-RPC response (success or error).

a2a.server.request_handlers.rest_handler module¶

class a2a.server.request_handlers.rest_handler.RESTHandler(agent_card: AgentCard, request_handler: RequestHandler)¶

Bases: object

Maps incoming REST-like (JSON+HTTP) requests to the appropriate request handler method and formats responses.

This uses the protobuf definitions of the gRPC service as the source of truth. By doing this, it ensures that this implementation and the gRPC transcoding (via Envoy) are equivalent. This handler should be used if using the gRPC handler with Envoy is not feasible for a given deployment solution. Use this handler and a related application if you desire to ONLY server the RESTful API.

async get_push_notification(request: Request, context: ServerCallContext) → dict[str, Any]¶

Handles the ‘tasks/pushNotificationConfig/get’ REST method.

Parameters:

request – The incoming Request object.
context – Context provided by the server.

Returns:

A dict containing the config

async list_push_notifications(request: Request, context: ServerCallContext) → dict[str, Any]¶

Handles the ‘tasks/pushNotificationConfig/list’ REST method.

This method is currently not implemented.

Parameters:

request – The incoming Request object.
context – Context provided by the server.

Returns:

A list of dict representing the TaskPushNotificationConfig objects.

Raises:

NotImplementedError – This method is not yet implemented.

async list_tasks(request: Request, context: ServerCallContext) → dict[str, Any]¶

Handles the ‘tasks/list’ REST method.

This method is currently not implemented.

Parameters:

request – The incoming Request object.
context – Context provided by the server.

Returns:

A list of dict representing the`Task` objects.

Raises:

NotImplementedError – This method is not yet implemented.

async on_cancel_task(request: Request, context: ServerCallContext) → dict[str, Any]¶

Handles the ‘tasks/cancel’ REST method.

Parameters:

request – The incoming Request object.
context – Context provided by the server.

Returns:

A dict containing the updated Task

async on_get_task(request: Request, context: ServerCallContext) → dict[str, Any]¶

Handles the ‘v1/tasks/{id}’ REST method.

Parameters:

request – The incoming Request object.
context – Context provided by the server.

Returns:

A Task object containing the Task.

async on_message_send(request: Request, context: ServerCallContext) → dict[str, Any]¶

Handles the ‘message/send’ REST method.

Parameters:

request – The incoming Request object.
context – Context provided by the server.

Returns:

A dict containing the result (Task or Message)

on_message_send_stream(request: Request, context: ServerCallContext) → AsyncIterator[str]¶

Handles the ‘message/stream’ REST method.

Yields response objects as they are produced by the underlying handler’s stream.

Parameters:

request – The incoming Request object.
context – Context provided by the server.

Yields:

JSON serialized objects containing streaming events (Task, Message, TaskStatusUpdateEvent, TaskArtifactUpdateEvent) as JSON

on_resubscribe_to_task(request: Request, context: ServerCallContext) → AsyncIterable[str]¶

Handles the ‘tasks/resubscribe’ REST method.

Yields response objects as they are produced by the underlying handler’s stream.

Parameters:

request – The incoming Request object.
context – Context provided by the server.

Yields:

JSON serialized objects containing streaming events

async set_push_notification(request: Request, context: ServerCallContext) → dict[str, Any]¶

Handles the ‘tasks/pushNotificationConfig/set’ REST method.

Requires the agent to support push notifications.

Parameters:

request – The incoming TaskPushNotificationConfig object.
context – Context provided by the server.

Returns:

A dict containing the config object.

Raises:

ServerError – If push notifications are not supported by the agent (due to the @validate decorator), A2AError if processing error is found.

Module contents¶

Request handler components for the A2A server.

class a2a.server.request_handlers.DefaultRequestHandler(agent_executor: AgentExecutor, task_store: TaskStore, queue_manager: QueueManager | None = None, push_config_store: PushNotificationConfigStore | None = None, push_sender: PushNotificationSender | None = None, request_context_builder: RequestContextBuilder | None = None)¶

Bases: RequestHandler

Default request handler for all incoming requests.

This handler provides default implementations for all A2A JSON-RPC methods, coordinating between the AgentExecutor, TaskStore, QueueManager, and optional PushNotifier.

async on_cancel_task(params: TaskIdParams, context: ServerCallContext | None = None) → Task | None¶

Default handler for ‘tasks/cancel’.

Attempts to cancel the task managed by the AgentExecutor.

async on_delete_task_push_notification_config(params: DeleteTaskPushNotificationConfigParams, context: ServerCallContext | None = None) → None¶

Default handler for ‘tasks/pushNotificationConfig/delete’.

Requires a PushConfigStore to be configured.

async on_get_task(params: TaskQueryParams, context: ServerCallContext | None = None) → Task | None¶: Default handler for ‘tasks/get’.

async on_get_task_push_notification_config(params: TaskIdParams | GetTaskPushNotificationConfigParams, context: ServerCallContext | None = None) → TaskPushNotificationConfig¶

Default handler for ‘tasks/pushNotificationConfig/get’.

Requires a PushConfigStore to be configured.

async on_list_task_push_notification_config(params: ListTaskPushNotificationConfigParams, context: ServerCallContext | None = None) → list[TaskPushNotificationConfig]¶

Default handler for ‘tasks/pushNotificationConfig/list’.

Requires a PushConfigStore to be configured.

async on_message_send(params: MessageSendParams, context: ServerCallContext | None = None) → Message | Task¶

Default handler for ‘message/send’ interface (non-streaming).

Starts the agent execution for the message and waits for the final result (Task or Message).

on_message_send_stream(params: MessageSendParams, context: ServerCallContext | None = None) → AsyncGenerator[Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent]¶

Default handler for ‘message/stream’ (streaming).

Starts the agent execution and yields events as they are produced by the agent.

on_resubscribe_to_task(params: TaskIdParams, context: ServerCallContext | None = None) → AsyncGenerator[Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent]¶

Default handler for ‘tasks/resubscribe’.

Allows a client to re-attach to a running streaming task’s event stream. Requires the task and its queue to still be active.

async on_set_task_push_notification_config(params: TaskPushNotificationConfig, context: ServerCallContext | None = None) → TaskPushNotificationConfig¶

Default handler for ‘tasks/pushNotificationConfig/set’.

Requires a PushNotifier to be configured.

class a2a.server.request_handlers.GrpcHandler(*args, **kwargs)¶

Bases: object

Placeholder for GrpcHandler when dependencies are not installed.

class a2a.server.request_handlers.JSONRPCHandler(agent_card: AgentCard, request_handler: RequestHandler, extended_agent_card: AgentCard | None = None, extended_card_modifier: Callable[[AgentCard, ServerCallContext], AgentCard] | None = None)¶

Bases: object

Maps incoming JSON-RPC requests to the appropriate request handler method and formats responses.

async delete_push_notification_config(request: DeleteTaskPushNotificationConfigRequest, context: ServerCallContext | None = None) → DeleteTaskPushNotificationConfigResponse¶

Handles the ‘tasks/pushNotificationConfig/list’ JSON-RPC method.

Parameters:

request – The incoming DeleteTaskPushNotificationConfigRequest object.
context – Context provided by the server.

Returns:

A DeleteTaskPushNotificationConfigResponse object containing the config or a JSON-RPC error.

async get_authenticated_extended_card(request: GetAuthenticatedExtendedCardRequest, context: ServerCallContext | None = None) → GetAuthenticatedExtendedCardResponse¶

Handles the ‘agent/authenticatedExtendedCard’ JSON-RPC method.

Parameters:

request – The incoming GetAuthenticatedExtendedCardRequest object.
context – Context provided by the server.

Returns:

A GetAuthenticatedExtendedCardResponse object containing the config or a JSON-RPC error.

async get_push_notification_config(request: GetTaskPushNotificationConfigRequest, context: ServerCallContext | None = None) → GetTaskPushNotificationConfigResponse¶

Handles the ‘tasks/pushNotificationConfig/get’ JSON-RPC method.

Parameters:

request – The incoming GetTaskPushNotificationConfigRequest object.
context – Context provided by the server.

Returns:

A GetTaskPushNotificationConfigResponse object containing the config or a JSON-RPC error.

async list_push_notification_config(request: ListTaskPushNotificationConfigRequest, context: ServerCallContext | None = None) → ListTaskPushNotificationConfigResponse¶

Handles the ‘tasks/pushNotificationConfig/list’ JSON-RPC method.

Parameters:

request – The incoming ListTaskPushNotificationConfigRequest object.
context – Context provided by the server.

Returns:

A ListTaskPushNotificationConfigResponse object containing the config or a JSON-RPC error.

async on_cancel_task(request: CancelTaskRequest, context: ServerCallContext | None = None) → CancelTaskResponse¶

Handles the ‘tasks/cancel’ JSON-RPC method.

Parameters:

request – The incoming CancelTaskRequest object.
context – Context provided by the server.

Returns:

A CancelTaskResponse object containing the updated Task or a JSON-RPC error.

async on_get_task(request: GetTaskRequest, context: ServerCallContext | None = None) → GetTaskResponse¶

Handles the ‘tasks/get’ JSON-RPC method.

Parameters:

request – The incoming GetTaskRequest object.
context – Context provided by the server.

Returns:

A GetTaskResponse object containing the Task or a JSON-RPC error.

async on_message_send(request: SendMessageRequest, context: ServerCallContext | None = None) → SendMessageResponse¶

Handles the ‘message/send’ JSON-RPC method.

Parameters:

request – The incoming SendMessageRequest object.
context – Context provided by the server.

Returns:

A SendMessageResponse object containing the result (Task or Message) or a JSON-RPC error response if a ServerError is raised by the handler.

on_message_send_stream(request: SendStreamingMessageRequest, context: ServerCallContext | None = None) → AsyncIterable[SendStreamingMessageResponse]¶

Handles the ‘message/stream’ JSON-RPC method.

Yields response objects as they are produced by the underlying handler’s stream.

Parameters:

request – The incoming SendStreamingMessageRequest object.
context – Context provided by the server.

Yields:

SendStreamingMessageResponse objects containing streaming events (Task, Message, TaskStatusUpdateEvent, TaskArtifactUpdateEvent) or JSON-RPC error responses if a ServerError is raised.

on_resubscribe_to_task(request: TaskResubscriptionRequest, context: ServerCallContext | None = None) → AsyncIterable[SendStreamingMessageResponse]¶

Handles the ‘tasks/resubscribe’ JSON-RPC method.

Yields response objects as they are produced by the underlying handler’s stream.

Parameters:

request – The incoming TaskResubscriptionRequest object.
context – Context provided by the server.

Yields:

SendStreamingMessageResponse objects containing streaming events or JSON-RPC error responses if a ServerError is raised.

async set_push_notification_config(request: SetTaskPushNotificationConfigRequest, context: ServerCallContext | None = None) → SetTaskPushNotificationConfigResponse¶

Handles the ‘tasks/pushNotificationConfig/set’ JSON-RPC method.

Requires the agent to support push notifications.

Parameters:

request – The incoming SetTaskPushNotificationConfigRequest object.
context – Context provided by the server.

Returns:

A SetTaskPushNotificationConfigResponse object containing the config or a JSON-RPC error.

Raises:

ServerError – If push notifications are not supported by the agent (due to the @validate decorator).

class a2a.server.request_handlers.RESTHandler(agent_card: AgentCard, request_handler: RequestHandler)¶

Bases: object

Maps incoming REST-like (JSON+HTTP) requests to the appropriate request handler method and formats responses.

async get_push_notification(request: Request, context: ServerCallContext) → dict[str, Any]¶

Handles the ‘tasks/pushNotificationConfig/get’ REST method.

Parameters:

request – The incoming Request object.
context – Context provided by the server.

Returns:

A dict containing the config

async list_push_notifications(request: Request, context: ServerCallContext) → dict[str, Any]¶

Handles the ‘tasks/pushNotificationConfig/list’ REST method.

This method is currently not implemented.

Parameters:

request – The incoming Request object.
context – Context provided by the server.

Returns:

A list of dict representing the TaskPushNotificationConfig objects.

Raises:

NotImplementedError – This method is not yet implemented.

async list_tasks(request: Request, context: ServerCallContext) → dict[str, Any]¶

Handles the ‘tasks/list’ REST method.

This method is currently not implemented.

Parameters:

request – The incoming Request object.
context – Context provided by the server.

Returns:

A list of dict representing the`Task` objects.

Raises:

NotImplementedError – This method is not yet implemented.

async on_cancel_task(request: Request, context: ServerCallContext) → dict[str, Any]¶

Handles the ‘tasks/cancel’ REST method.

Parameters:

request – The incoming Request object.
context – Context provided by the server.

Returns:

A dict containing the updated Task

async on_get_task(request: Request, context: ServerCallContext) → dict[str, Any]¶

Handles the ‘v1/tasks/{id}’ REST method.

Parameters:

request – The incoming Request object.
context – Context provided by the server.

Returns:

A Task object containing the Task.

async on_message_send(request: Request, context: ServerCallContext) → dict[str, Any]¶

Handles the ‘message/send’ REST method.

Parameters:

request – The incoming Request object.
context – Context provided by the server.

Returns:

A dict containing the result (Task or Message)

on_message_send_stream(request: Request, context: ServerCallContext) → AsyncIterator[str]¶

Handles the ‘message/stream’ REST method.

Yields response objects as they are produced by the underlying handler’s stream.

Parameters:

request – The incoming Request object.
context – Context provided by the server.

Yields:

JSON serialized objects containing streaming events (Task, Message, TaskStatusUpdateEvent, TaskArtifactUpdateEvent) as JSON

on_resubscribe_to_task(request: Request, context: ServerCallContext) → AsyncIterable[str]¶

Handles the ‘tasks/resubscribe’ REST method.

Yields response objects as they are produced by the underlying handler’s stream.

Parameters:

request – The incoming Request object.
context – Context provided by the server.

Yields:

JSON serialized objects containing streaming events

async set_push_notification(request: Request, context: ServerCallContext) → dict[str, Any]¶

Handles the ‘tasks/pushNotificationConfig/set’ REST method.

Requires the agent to support push notifications.

Parameters:

request – The incoming TaskPushNotificationConfig object.
context – Context provided by the server.

Returns:

A dict containing the config object.

Raises:

ServerError – If push notifications are not supported by the agent (due to the @validate decorator), A2AError if processing error is found.

class a2a.server.request_handlers.RequestHandler¶

Bases: ABC

A2A request handler interface.

This interface defines the methods that an A2A server implementation must provide to handle incoming JSON-RPC requests.

abstractmethod async on_cancel_task(params: TaskIdParams, context: ServerCallContext | None = None) → Task | None¶

Handles the ‘tasks/cancel’ method.

Requests the agent to cancel an ongoing task.

Parameters:

params – Parameters specifying the task ID.
context – Context provided by the server.

Returns:

The Task object with its status updated to canceled, or None if the task was not found.

abstractmethod async on_delete_task_push_notification_config(params: DeleteTaskPushNotificationConfigParams, context: ServerCallContext | None = None) → None¶

Handles the ‘tasks/pushNotificationConfig/delete’ method.

Deletes a push notification configuration associated with a task.

Parameters:

params – Parameters including the task ID.
context – Context provided by the server.

Returns:

None

abstractmethod async on_get_task(params: TaskQueryParams, context: ServerCallContext | None = None) → Task | None¶

Handles the ‘tasks/get’ method.

Retrieves the state and history of a specific task.

Parameters:

params – Parameters specifying the task ID and optionally history length.
context – Context provided by the server.

Returns:

The Task object if found, otherwise None.

Handles the ‘tasks/pushNotificationConfig/get’ method.

Retrieves the current push notification configuration for a task.

Parameters:

params – Parameters including the task ID.
context – Context provided by the server.

Returns:

The TaskPushNotificationConfig for the task.

abstractmethod async on_list_task_push_notification_config(params: ListTaskPushNotificationConfigParams, context: ServerCallContext | None = None) → list[TaskPushNotificationConfig]¶

Handles the ‘tasks/pushNotificationConfig/list’ method.

Retrieves the current push notification configurations for a task.

Parameters:

params – Parameters including the task ID.
context – Context provided by the server.

Returns:

The list[TaskPushNotificationConfig] for the task.

abstractmethod async on_message_send(params: MessageSendParams, context: ServerCallContext | None = None) → Task | Message¶

Handles the ‘message/send’ method (non-streaming).

Sends a message to the agent to create, continue, or restart a task, and waits for the final result (Task or Message).

Parameters:

params – Parameters including the message and configuration.
context – Context provided by the server.

Returns:

The final Task object or a final Message object.

Handles the ‘message/stream’ method (streaming).

Sends a message to the agent and yields stream events as they are produced (Task updates, Message chunks, Artifact updates).

Parameters:

params – Parameters including the message and configuration.
context – Context provided by the server.

Yields:

Event objects from the agent’s execution.

Raises:

ServerError(UnsupportedOperationError) – By default, if not implemented.

Handles the ‘tasks/resubscribe’ method.

Allows a client to re-subscribe to a running streaming task’s event stream.

Parameters:

params – Parameters including the task ID.
context – Context provided by the server.

Yields:

Event objects from the agent’s ongoing execution for the specified task.

Raises:

ServerError(UnsupportedOperationError) – By default, if not implemented.

abstractmethod async on_set_task_push_notification_config(params: TaskPushNotificationConfig, context: ServerCallContext | None = None) → TaskPushNotificationConfig¶

Handles the ‘tasks/pushNotificationConfig/set’ method.

Sets or updates the push notification configuration for a task.

Parameters:

params – Parameters including the task ID and push notification configuration.
context – Context provided by the server.

Returns:

The provided TaskPushNotificationConfig upon success.

a2a.server.request_handlers.build_error_response(request_id: str | int | None, error: A2AError | JSONRPCError, response_wrapper_type: type[RT]) → RT¶

Helper method to build a JSONRPCErrorResponse wrapped in the appropriate response type.

Parameters:

request_id – The ID of the request that caused the error.
error – The A2AError or JSONRPCError object.
response_wrapper_type – The Pydantic RootModel type that wraps the response for the specific RPC method (e.g., SendMessageResponse).

Returns:

A Pydantic model representing the JSON-RPC error response, wrapped in the specified response type.

Helper method to build appropriate JSONRPCResponse object for RPC methods.

Based on the type of the response object received from the handler, it constructs either a success response wrapped in the appropriate payload type or an error response.

Parameters:

request_id – The ID of the request.
response – The object received from the request handler.
success_response_types – A tuple of expected Pydantic model types for a successful result.
success_payload_type – The Pydantic model type for the success payload (e.g., SendMessageSuccessResponse).
response_type – The Pydantic RootModel type that wraps the final response (e.g., SendMessageResponse).

Returns:

A Pydantic model representing the final JSON-RPC response (success or error).