a2a.server.request_handlers package

Submodules

• a2a.server.request_handlers.default_request_handler module
  • LegacyRequestHandler
    • LegacyRequestHandler.on_cancel_task()
    • LegacyRequestHandler.on_create_task_push_notification_config()
    • LegacyRequestHandler.on_delete_task_push_notification_config()
    • LegacyRequestHandler.on_get_extended_agent_card()
    • LegacyRequestHandler.on_get_task()
    • LegacyRequestHandler.on_get_task_push_notification_config()
    • LegacyRequestHandler.on_list_task_push_notification_configs()
    • LegacyRequestHandler.on_list_tasks()
    • LegacyRequestHandler.on_message_send()
    • LegacyRequestHandler.on_message_send_stream()
    • LegacyRequestHandler.on_subscribe_to_task()
• a2a.server.request_handlers.default_request_handler_v2 module
  • DefaultRequestHandlerV2
    • DefaultRequestHandlerV2.on_cancel_task()
    • DefaultRequestHandlerV2.on_create_task_push_notification_config()
    • DefaultRequestHandlerV2.on_delete_task_push_notification_config()
    • DefaultRequestHandlerV2.on_get_extended_agent_card()
    • DefaultRequestHandlerV2.on_get_task()
    • DefaultRequestHandlerV2.on_get_task_push_notification_config()
    • DefaultRequestHandlerV2.on_list_task_push_notification_configs()
    • DefaultRequestHandlerV2.on_list_tasks()
    • DefaultRequestHandlerV2.on_message_send()
    • DefaultRequestHandlerV2.on_message_send_stream()
    • DefaultRequestHandlerV2.on_subscribe_to_task()
• a2a.server.request_handlers.grpc_handler module
  • DefaultGrpcServerCallContextBuilder
    • DefaultGrpcServerCallContextBuilder.build()
    • DefaultGrpcServerCallContextBuilder.build_user()
  • GrpcHandler
    • GrpcHandler.CancelTask()
    • GrpcHandler.CreateTaskPushNotificationConfig()
    • GrpcHandler.DeleteTaskPushNotificationConfig()
    • GrpcHandler.GetExtendedAgentCard()
    • GrpcHandler.GetTask()
    • GrpcHandler.GetTaskPushNotificationConfig()
    • GrpcHandler.ListTaskPushNotificationConfigs()
    • GrpcHandler.ListTasks()
    • GrpcHandler.SendMessage()
    • GrpcHandler.SendStreamingMessage()
    • GrpcHandler.SubscribeToTask()
    • GrpcHandler.abort_context()
  • GrpcServerCallContextBuilder
    • GrpcServerCallContextBuilder.build()
• a2a.server.request_handlers.request_handler module
  • RequestHandler
    • RequestHandler.on_cancel_task()
    • RequestHandler.on_create_task_push_notification_config()
    • RequestHandler.on_delete_task_push_notification_config()
    • RequestHandler.on_get_extended_agent_card()
    • RequestHandler.on_get_task()
    • RequestHandler.on_get_task_push_notification_config()
    • RequestHandler.on_list_task_push_notification_configs()
    • RequestHandler.on_list_tasks()
    • RequestHandler.on_message_send()
    • RequestHandler.on_message_send_stream()
    • RequestHandler.on_subscribe_to_task()
  • validate()
  • validate_request_params()
• a2a.server.request_handlers.response_helpers module
  • EventTypes
  • agent_card_to_dict()
  • build_error_response()
  • prepare_response_object()

Module contents

Request handler components for the A2A server.

class a2a.server.request_handlers.DefaultGrpcServerCallContextBuilder

Bases: GrpcServerCallContextBuilder

Default implementation of GrpcServerCallContextBuilder.

build(context: ServicerContext) → ServerCallContext

Builds a ServerCallContext from a gRPC ServicerContext.

build_user(context: ServicerContext) → User

Builds a User from a gRPC ServicerContext.

a2a.server.request_handlers.DefaultRequestHandler

alias of DefaultRequestHandlerV2

class a2a.server.request_handlers.DefaultRequestHandlerV2(agent_executor: AgentExecutor, task_store: TaskStore, agent_card: AgentCard, queue_manager: Any | None = None, push_config_store: PushNotificationConfigStore | None = None, push_sender: PushNotificationSender | None = None, request_context_builder: RequestContextBuilder | None = None, extended_agent_card: AgentCard | None = None, extended_card_modifier: Callable[[AgentCard, ServerCallContext], Awaitable[AgentCard]] | None = None)

Bases: RequestHandler

Default request handler for all incoming requests.

async on_cancel_task(params: CancelTaskRequest, context: ServerCallContext) → 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.

async on_create_task_push_notification_config(params: TaskPushNotificationConfig, context: ServerCallContext) → TaskPushNotificationConfig

Handles the ‘tasks/pushNotificationConfig/create’ 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.

async on_delete_task_push_notification_config(params: DeleteTaskPushNotificationConfigRequest, context: ServerCallContext) → 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

async on_get_extended_agent_card(params: GetExtendedAgentCardRequest, context: ServerCallContext) → AgentCard

Default handler for ‘GetExtendedAgentCard’.

Requires capabilities.extended_agent_card to be true.

async on_get_task(params: GetTaskRequest, context: ServerCallContext) → 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.

async on_get_task_push_notification_config(params: GetTaskPushNotificationConfigRequest, context: ServerCallContext) → 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.

async on_list_task_push_notification_configs(params: ListTaskPushNotificationConfigsRequest, context: ServerCallContext) → ListTaskPushNotificationConfigsResponse

Handles the ‘ListTaskPushNotificationConfigs’ 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.

async on_list_tasks(params: ListTasksRequest, context: ServerCallContext) → ListTasksResponse

Handles the tasks/list method.

Retrieves all tasks for an agent. Supports filtering, pagination, ordering, limiting the history length, excluding artifacts, etc.

Parameters:

• params – Parameters with filtering criteria.

• context – Context provided by the server.

Returns:

The ListTasksResponse containing the tasks.

async on_message_send(params: SendMessageRequest, context: ServerCallContext) → Message | Task

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.

on_message_send_stream(params: SendMessageRequest, context: ServerCallContext) → AsyncGenerator[Event, None]

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.

on_subscribe_to_task(params: SubscribeToTaskRequest, context: ServerCallContext) → AsyncGenerator[Event, None]

Handles the ‘SubscribeToTask’ method.

Allows a client to 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.

class a2a.server.request_handlers.GrpcHandler(request_handler: RequestHandler, context_builder: GrpcServerCallContextBuilder | None = None)

Bases: A2AServiceServicer

Maps incoming gRPC requests to the appropriate request handler method.

async CancelTask(request: CancelTaskRequest, context: ServicerContext) → Task

Handles the ‘CancelTask’ gRPC method.

async CreateTaskPushNotificationConfig(request: TaskPushNotificationConfig, context: ServicerContext) → TaskPushNotificationConfig

Handles the ‘CreateTaskPushNotificationConfig’ gRPC method.

async DeleteTaskPushNotificationConfig(request: DeleteTaskPushNotificationConfigRequest, context: ServicerContext) → Empty

Handles the ‘DeleteTaskPushNotificationConfig’ gRPC method.

async GetExtendedAgentCard(request: GetExtendedAgentCardRequest, context: ServicerContext) → AgentCard

Get the extended agent card for the agent served.

async GetTask(request: GetTaskRequest, context: ServicerContext) → Task

Handles the ‘GetTask’ gRPC method.

async GetTaskPushNotificationConfig(request: GetTaskPushNotificationConfigRequest, context: ServicerContext) → TaskPushNotificationConfig

Handles the ‘GetTaskPushNotificationConfig’ gRPC method.

async ListTaskPushNotificationConfigs(request: ListTaskPushNotificationConfigsRequest, context: ServicerContext) → ListTaskPushNotificationConfigsResponse

Handles the ‘ListTaskPushNotificationConfig’ gRPC method.

async ListTasks(request: ListTasksRequest, context: ServicerContext) → ListTasksResponse

Handles the ‘ListTasks’ gRPC method.

async SendMessage(request: SendMessageRequest, context: ServicerContext) → SendMessageResponse

Handles the ‘SendMessage’ gRPC method.

async SendStreamingMessage(request: SendMessageRequest, context: ServicerContext) → AsyncIterable[StreamResponse]

Handles the ‘StreamMessage’ gRPC method.

async SubscribeToTask(request: SubscribeToTaskRequest, context: ServicerContext) → AsyncIterable[StreamResponse]

Handles the ‘SubscribeToTask’ gRPC method.

async abort_context(error: A2AError, context: ServicerContext) → None

Sets the grpc errors appropriately in the context.

class a2a.server.request_handlers.GrpcServerCallContextBuilder

Bases: ABC

Interface for building ServerCallContext from gRPC context.

abstractmethod build(context: ServicerContext) → ServerCallContext

Builds a ServerCallContext from a gRPC ServicerContext.

class a2a.server.request_handlers.LegacyRequestHandler(agent_executor: AgentExecutor, task_store: TaskStore, agent_card: AgentCard, queue_manager: QueueManager | None = None, push_config_store: PushNotificationConfigStore | None = None, push_sender: PushNotificationSender | None = None, request_context_builder: RequestContextBuilder | None = None, extended_agent_card: AgentCard | None = None, extended_card_modifier: Callable[[AgentCard, ServerCallContext], Awaitable[AgentCard]] | 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: CancelTaskRequest, context: ServerCallContext) → Task | None

Default handler for ‘tasks/cancel’.

Attempts to cancel the task managed by the AgentExecutor.

async on_create_task_push_notification_config(params: TaskPushNotificationConfig, context: ServerCallContext) → TaskPushNotificationConfig

Default handler for ‘tasks/pushNotificationConfig/create’.

Requires a PushNotifier to be configured.

async on_delete_task_push_notification_config(params: DeleteTaskPushNotificationConfigRequest, context: ServerCallContext) → None

Default handler for ‘tasks/pushNotificationConfig/delete’.

Requires a PushConfigStore to be configured.

async on_get_extended_agent_card(params: GetExtendedAgentCardRequest, context: ServerCallContext) → AgentCard

Default handler for ‘GetExtendedAgentCard’.

Requires capabilities.extended_agent_card to be true.

async on_get_task(params: GetTaskRequest, context: ServerCallContext) → Task | None

Default handler for ‘tasks/get’.

async on_get_task_push_notification_config(params: GetTaskPushNotificationConfigRequest, context: ServerCallContext) → TaskPushNotificationConfig

Default handler for ‘tasks/pushNotificationConfig/get’.

Requires a PushConfigStore to be configured.

async on_list_task_push_notification_configs(params: ListTaskPushNotificationConfigsRequest, context: ServerCallContext) → ListTaskPushNotificationConfigsResponse

Default handler for ‘ListTaskPushNotificationConfigs’.

Requires a PushConfigStore to be configured.

async on_list_tasks(params: ListTasksRequest, context: ServerCallContext) → ListTasksResponse

Default handler for ‘tasks/list’.

async on_message_send(params: SendMessageRequest, context: ServerCallContext) → 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: SendMessageRequest, context: ServerCallContext) → 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_subscribe_to_task(params: SubscribeToTaskRequest, context: ServerCallContext) → AsyncGenerator[Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent, None]

Default handler for ‘SubscribeToTask’.

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

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 A2A requests from any transport (gRPC, REST, JSON-RPC).

abstractmethod async on_cancel_task(params: CancelTaskRequest, context: ServerCallContext) → 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_create_task_push_notification_config(params: TaskPushNotificationConfig, context: ServerCallContext) → TaskPushNotificationConfig

Handles the ‘tasks/pushNotificationConfig/create’ 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.

abstractmethod async on_delete_task_push_notification_config(params: DeleteTaskPushNotificationConfigRequest, context: ServerCallContext) → 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_extended_agent_card(params: GetExtendedAgentCardRequest, context: ServerCallContext) → AgentCard

Handles the ‘GetExtendedAgentCard’ method.

Retrieves the extended agent card for the agent.

Parameters:

• params – Parameters for the request.

• context – Context provided by the server.

Returns:

The AgentCard object representing the extended properties of the agent.

abstractmethod async on_get_task(params: GetTaskRequest, context: ServerCallContext) → 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: GetTaskPushNotificationConfigRequest, context: ServerCallContext) → 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_configs(params: ListTaskPushNotificationConfigsRequest, context: ServerCallContext) → ListTaskPushNotificationConfigsResponse

Handles the ‘ListTaskPushNotificationConfigs’ 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_list_tasks(params: ListTasksRequest, context: ServerCallContext) → ListTasksResponse

Handles the tasks/list method.

Retrieves all tasks for an agent. Supports filtering, pagination, ordering, limiting the history length, excluding artifacts, etc.

Parameters:

• params – Parameters with filtering criteria.

• context – Context provided by the server.

Returns:

The ListTasksResponse containing the tasks.

abstractmethod async on_message_send(params: SendMessageRequest, context: ServerCallContext) → 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: SendMessageRequest, context: ServerCallContext) → 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.

abstractmethod async on_subscribe_to_task(params: SubscribeToTaskRequest, context: ServerCallContext) → AsyncGenerator[Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent]

Handles the ‘SubscribeToTask’ method.

Allows a client to 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.

a2a.server.request_handlers.build_error_response(request_id: str | int | None, error: A2AError | JSONRPCError) → dict[str, Any]

Build a JSON-RPC error response dict.

Parameters:

• request_id – The ID of the request that caused the error.

• error – The A2AError or JSONRPCError object.

Returns:

A dict representing the JSON-RPC error response.

a2a.server.request_handlers.prepare_response_object(request_id: str | int | None, response: Task | Message | TaskArtifactUpdateEvent | TaskStatusUpdateEvent | TaskPushNotificationConfig | StreamResponse | SendMessageResponse | A2AError | JSONRPCError | list[TaskPushNotificationConfig] | ListTasksResponse, success_response_types: tuple[type, ...]) → dict[str, Any]

Build a JSON-RPC response dict from handler output.

Based on the type of the response object received from the handler, it constructs either a success response 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 types for a successful result.

Returns:

A dict representing the JSON-RPC response (success or error).

a2a.server.request_handlers.validate_request_params(method: Callable) → Callable

Decorator for RequestHandler methods to validate required fields on incoming requests.