Package org.a2aproject.sdk.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
  • Formats payloads according to the protocol version stored with each configuration (v1.0 StreamResponse by default; version-specific formatters via PushNotificationPayloadFormatter SPI)
  • Sends HTTP POST requests with the formatted 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, Task taskSnapshot) {
         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)
  • 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, @Nullable Task taskSnapshot)
    Sends a push notification containing a streaming event.

  • Method Details

    • sendNotification

      void sendNotification(StreamingEventKind event, @Nullable Task taskSnapshot)
      Sends a push notification containing a streaming event.

      Called after the event has been persisted to TaskStore. The payload format depends on the protocol version used to register the push notification configuration.

      • v1.0 (default): 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).
      • v0.3: The payload is a v0.3 Task JSON object, using the provided taskSnapshot. Message events are skipped.

      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.
      taskSnapshot - the current state of the task after the event has been applied. Used by formatters for older protocol versions that require the full task state in notifications.