Interface PushNotificationConfigStore

All Known Implementing Classes:
InMemoryPushNotificationConfigStore, JpaDatabasePushNotificationConfigStore
public interface PushNotificationConfigStore
Interface for storing and retrieving push notification configurations for tasks.

Push notification configurations specify where and how to deliver task state updates to external systems (webhook URLs, authentication headers, etc.). A task can have multiple push notification configurations for different endpoints or use cases.

Configuration ID Semantics

Each push notification config has an ID:
  • If not provided in TaskPushNotificationConfig, defaults to the task ID
  • Multiple configs per task require unique IDs (e.g., "webhook-1", "webhook-2")
  • Used for retrieval and deletion of specific configurations

Per-task Limit

Implementations MUST reject registering more than a2a.push-notification-config.max-per-task (default 100) distinct configs for a single task, throwing InvalidParamsError. Re-registering an already-registered config ID does not count against the limit. See maxPushConfigsPerTask(A2AConfigProvider).

Pagination Support

getInfo(ListTaskPushNotificationConfigsParams) supports pagination for tasks with many push notification configurations:
  • pageSize: Maximum number of configs to return (0 = unlimited)
  • pageToken: Continuation token from previous response
  • Returns ListTaskPushNotificationConfigsResult with configs and next page token

Default Implementation

InMemoryPushNotificationConfigStore:
  • Stores configs in ConcurrentHashMap
  • Thread-safe for concurrent operations
  • Configs lost on application restart

Alternative Implementations

  • extras/push-notification-config-store-database-jpa: Database persistence with JPA
Database implementations survive restarts and enable config sharing across server instances.

CDI Extension Pattern

@ApplicationScoped
@Alternative
@Priority(50)
public class JpaDatabasePushNotificationConfigStore implements PushNotificationConfigStore {
    @PersistenceContext
    EntityManager em;

    @Transactional
    public TaskPushNotificationConfig setInfo(TaskPushNotificationConfig config) {
        // JPA persistence logic
    }
}

Thread Safety

Implementations must be thread-safe. Multiple threads may call methods concurrently for the same or different tasks.
See Also:

  • Field Details

    • DEFAULT_MAX_PUSH_CONFIGS_PER_TASK

      static final int DEFAULT_MAX_PUSH_CONFIGS_PER_TASK
      Default maximum number of push notification configs allowed per task, used when a2a.push-notification-config.max-per-task is not configured. See META-INF/a2a-defaults.properties.
      See Also:

  • Method Details

    • setInfo

      TaskPushNotificationConfig setInfo(TaskPushNotificationConfig notificationConfig)
      Sets or updates the push notification configuration for a task.

      If notificationConfig.id() is null or empty, the store creates the default config with the task ID. Omitting the ID is a create-only shorthand: if the default config already exists, the store rejects the request instead of silently replacing it. To update the default config, provide the task ID explicitly. Configurations beyond the default one must always provide an ID. The v0.3 compatibility path keeps its historical single-config update behavior.

      Parameters:
      notificationConfig - the task push notification configuration
      Returns:
      the potentially updated configuration (with ID set if it was null)

    • setInfo

      default TaskPushNotificationConfig setInfo(TaskPushNotificationConfig notificationConfig, @Nullable String protocolVersion)
      Sets or updates the push notification configuration for a task, along with the protocol version that registered it.

      This merged method ensures the protocol version is stored using the normalized config ID (after setInfo(TaskPushNotificationConfig) applies defaults).

      Parameters:
      notificationConfig - the task push notification configuration
      protocolVersion - the protocol version string, or null to use AgentInterface.CURRENT_PROTOCOL_VERSION
      Returns:
      the potentially updated configuration (with ID set if it was null)

    • resolveProtocolVersion

      static String resolveProtocolVersion(@Nullable String protocolVersion)
      Resolves the protocol version, defaulting null to the current protocol version.

    • maxPushConfigsPerTask

      static int maxPushConfigsPerTask(@Nullable A2AConfigProvider config)
      Maximum number of push notification configs allowed per task.

      Reads the a2a.push-notification-config.max-per-task configuration value; a null provider, or a missing, non-numeric, or non-positive value, falls back to 100. See META-INF/a2a-defaults.properties.

      Parameters:
      config - the configuration provider, or null when the store is used without CDI injection (e.g., in tests)
      Returns:
      the per-task limit (always positive)

    • getInfo

      ListTaskPushNotificationConfigsResult getInfo(ListTaskPushNotificationConfigsParams params)
      Retrieves push notification configurations for a task with pagination support.

      Returns all configs if params.pageSize() is 0. Otherwise, returns up to pageSize configs and a continuation token for the next page.

      Pagination Example: 

      // First page
ListTaskPushNotificationConfigsParams params =
    new ListTaskPushNotificationConfigsParams(taskId, 10, null, tenant);
ListTaskPushNotificationConfigsResult result = store.getInfo(params);

// Next page
if (result.nextPageToken() != null) {
    params = new ListTaskPushNotificationConfigsParams(
        taskId, 10, result.nextPageToken(), tenant);
    result = store.getInfo(params);
}
      Parameters:
      params - the query parameters including task ID, page size, and page token
      Returns:
      the configurations for this task (empty list if none found)

    • deleteInfo

      void deleteInfo(String taskId, String configId)
      Deletes a push notification configuration for a task.

      If configId is null, it defaults to the task ID (deletes the default config). If no config exists with the given ID, this method returns normally (idempotent).

      Parameters:
      taskId - the task ID
      configId - the push notification configuration ID (null = use task ID)

    • getProtocolVersion

      default String getProtocolVersion(String taskId, String configId)
      Gets the protocol version associated with a push notification configuration.
      Parameters:
      taskId - the task ID
      configId - the push notification configuration ID
      Returns:
      the protocol version string, defaults to the current protocol version if not set

    • getProtocolVersions

      default Map<String,String> getProtocolVersions(String taskId)
      Gets all protocol versions for a task's push notification configurations in a single call.
      Parameters:
      taskId - the task ID
      Returns:
      a map of config ID to protocol version (only includes configs with a version set)