Package org.a2aproject.sdk.server.tasks

Interface PushNotificationSender

All Known Implementing Classes:
BasePushNotificationSender, OpenTelemetryPushNotificationSenderDecorator
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 boolean sendNotification(StreamingEventKind event, Task taskSnapshot) {
         String taskId = extractTaskId(event);
         producer.send("task-updates", taskId, event);
         return true;
     }
 }

Error Handling

Implementations should handle errors gracefully:
  • Return false on delivery failures (network errors, HTTP errors, unreachable endpoints) rather than throwing exceptions — notifications are best-effort
  • Throw IllegalArgumentException or IllegalStateException for precondition violations (e.g. an event without a task ID, or an unsupported event type) — these indicate caller bugs, not delivery problems
  • Don't block on network I/O - execute asynchronously if needed
  • Circuit breaker patterns for repeatedly failing endpoints
Exceptions thrown from this method will not fail the client request — callers catch and log them as errors.

Thread Safety

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

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final PushNotificationSender
    NOOP
    A no-op sender that always reports success.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    sendNotification(StreamingEventKind event, @Nullable Task taskSnapshot)
    Sends a push notification containing a streaming event.

  • Field Details

    • NOOP

      static final PushNotificationSender NOOP
      A no-op sender that always reports success. Useful in tests and configurations where push notifications are not needed.

  • Method Details

    • sendNotification

      boolean 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: Return false on delivery failures (network errors, HTTP errors). Throwing is reserved for precondition violations such as a missing task ID or an unsupported event type — these signal caller bugs. Callers catch all exceptions so neither case fails the client 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.
      Returns:
      true if all notifications were delivered successfully, false if one or more deliveries failed
      Throws:
      IllegalArgumentException - if the event does not contain a task ID
      IllegalStateException - if the event type is not recognized