Package io.a2a.server.tasks

Interface PushNotificationSender

All Known Implementing Classes:
BasePushNotificationSender
public interface PushNotificationSender
Interface for delivering push notifications containing task state updates to external systems.

Push notifications enable asynchronous, out-of-band communication of task progress to configured webhook URLs or messaging systems. This allows clients to receive updates without maintaining persistent connections or polling.

Invocation Context

Called by DefaultRequestHandler after:
  • Task events are persisted to TaskStore
  • Events are returned/streamed to the requesting client
  • For streaming: after each event emission to the client
  • For blocking: after the initial response is returned

Push notifications are always sent AFTER the task state is persisted and the client has received the event, ensuring consistency.

Default Implementation

BasePushNotificationSender provides HTTP webhook delivery:
  • Retrieves webhook URLs from PushNotificationConfigStore
  • Wraps events in StreamResponse format (per A2A spec section 4.3.3)
  • Sends HTTP POST requests with StreamResponse JSON payload
  • Logs errors but doesn't fail the request

Alternative Implementations

Custom implementations can deliver notifications via:
  • Kafka topics for event streaming
  • AWS SNS/SQS for cloud messaging
  • WebSockets for real-time browser updates
  • Custom messaging protocols

CDI Extension Pattern


 @ApplicationScoped
 @Alternative
 @Priority(100)
 public class KafkaPushNotificationSender implements PushNotificationSender {
     @Inject
     KafkaProducer<String, StreamingEventKind> producer;

     @Override
     public void sendNotification(StreamingEventKind event) {
         String taskId = extractTaskId(event);
         producer.send("task-updates", taskId, event);
     }
 }

Error Handling

Implementations should handle errors gracefully:
  • Log failures but don't throw exceptions (notifications are best-effort)
  • Consider retry logic for transient failures
  • Don't block on network I/O - execute asynchronously if needed
  • Circuit breaker patterns for repeatedly failing endpoints
Throwing exceptions from this method will not fail the client request, but will be logged as errors.

Thread Safety

May be called from multiple threads concurrently for different tasks. Implementations must be thread-safe.
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    sendNotification(StreamingEventKind event)
    Sends a push notification containing a streaming event.

  • Method Details

    • sendNotification

      void sendNotification(StreamingEventKind event)
      Sends a push notification containing a streaming event.

      Called after the event has been persisted to TaskStore. The event is wrapped in a StreamResponse format (per A2A spec section 4.3.3) with the appropriate oneof field set (task, message, statusUpdate, or artifactUpdate).

      Retrieve push notification URLs or messaging configurations from PushNotificationConfigStore using the task ID extracted from the event.

      Supported event types:

      Error Handling: Log errors but don't throw exceptions. Notifications are best-effort and should not fail the primary request.

      Parameters:
      event - the streaming event to send (Task, Message, TaskStatusUpdateEvent, or TaskArtifactUpdateEvent)