feat!: Remove hard dependency on MicroProfile Config from the core SDK (a2aproject#468)

Default values will now be used by default. You can supply your own by
providing a CDI bean with a higher priority.
Also, there is a new 2a-java-sdk-microprofile-config with the previous
MicroProfile Config capabilities. If used, this will allow MicroProfile
Config configurations of the properties. The reference implementations
use this new module

Fixes a2aproject#467 🦕

Author: kabir

README.md

@@ -232,11 +232,22 @@ public class WeatherAgentExecutorProducer {
 }
 ```
 
-### 4. Configure Executor Settings (Optional)
+### 4. Configuration System
 
-The A2A Java SDK uses a dedicated executor for handling asynchronous operations like streaming subscriptions. By default, this executor is configured with a core pool size of 5 threads and a maximum pool size of 50 threads, optimized for I/O-bound operations.
+The A2A Java SDK uses a flexible configuration system that works across different frameworks.
 
-You can customize the executor settings in your `application.properties`:
+**Default behavior:** Configuration values come from `META-INF/a2a-defaults.properties` files on the classpath (provided by core modules and extras). These defaults work out of the box without any additional setup.
+
+**Customizing configuration:**
+- **Quarkus/MicroProfile Config users**: Add the [`microprofile-config`](integrations/microprofile-config/README.md) integration to override defaults via `application.properties`, environment variables, or system properties
+- **Spring/other frameworks**: See the [integration module README](integrations/microprofile-config/README.md#custom-config-providers) for how to implement a custom `A2AConfigProvider`
+- **Reference implementations**: Already include the MicroProfile Config integration
+
+#### Configuration Properties
+
+**Executor Settings** (Optional)
+
+The SDK uses a dedicated executor for async operations like streaming. Default: 5 core threads, 50 max threads.
 
 ```properties
 # Core thread pool size for the @Internal executor (default: 5)
@@ -249,20 +260,23 @@ a2a.executor.max-pool-size=50
 a2a.executor.keep-alive-seconds=60
 ```
 
-**Why this matters:**
-- **Streaming Performance**: The executor handles streaming subscriptions. Too few threads can cause timeouts under concurrent load.
-- **Resource Management**: The dedicated executor prevents streaming operations from competing with the ForkJoinPool used by other async tasks.
-- **Concurrency**: In production environments with high concurrent streaming requests, increase the pool sizes accordingly.
+**Blocking Call Timeouts** (Optional)
 
-**Default Configuration:**
 ```properties
-# These are the defaults - no need to set unless you want different values
-a2a.executor.core-pool-size=5
-a2a.executor.max-pool-size=50
-a2a.executor.keep-alive-seconds=60
+# Timeout for agent execution in blocking calls (default: 30 seconds)
+a2a.blocking.agent.timeout.seconds=30
+
+# Timeout for event consumption in blocking calls (default: 5 seconds)
+a2a.blocking.consumption.timeout.seconds=5
 ```
 
-**Note:** The reference server implementations automatically configure this executor. If you're creating a custom server integration, ensure you provide an `@Internal Executor` bean for optimal streaming performance.
+**Why this matters:**
+- **Streaming Performance**: The executor handles streaming subscriptions. Too few threads can cause timeouts under concurrent load.
+- **Resource Management**: The dedicated executor prevents streaming operations from competing with the ForkJoinPool.
+- **Concurrency**: In production with high concurrent streaming, increase pool sizes accordingly.
+- **Agent Timeouts**: LLM-based agents may need longer timeouts (60-120s) compared to simple agents.
+
+**Note:** The reference server implementations (Quarkus-based) automatically include the MicroProfile Config integration, so properties work out of the box in `application.properties`.
 
 ## A2A Client
 

boms/extras/src/it/extras-usage-test/pom.xml

@@ -74,6 +74,10 @@
             <groupId>io.github.a2asdk</groupId>
             <artifactId>a2a-java-sdk-server-common</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.github.a2asdk</groupId>
+            <artifactId>a2a-java-sdk-microprofile-config</artifactId>
+        </dependency>
         <dependency>
             <groupId>io.github.a2asdk</groupId>
             <artifactId>a2a-java-sdk-client</artifactId>
@@ -102,6 +106,12 @@
             <groupId>io.github.a2asdk</groupId>
             <artifactId>a2a-java-sdk-transport-rest</artifactId>
         </dependency>
+
+        <!-- Third-party dependencies needed for integration classes -->
+        <dependency>
+            <groupId>org.eclipse.microprofile.config</groupId>
+            <artifactId>microprofile-config-api</artifactId>
+        </dependency>
     </dependencies>
 
     <build>

boms/reference/src/it/reference-usage-test/pom.xml

@@ -69,6 +69,10 @@
             <groupId>io.github.a2asdk</groupId>
             <artifactId>a2a-java-sdk-server-common</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.github.a2asdk</groupId>
+            <artifactId>a2a-java-sdk-microprofile-config</artifactId>
+        </dependency>
         <dependency>
             <groupId>io.github.a2asdk</groupId>
             <artifactId>a2a-java-sdk-client</artifactId>
@@ -86,6 +90,12 @@
             <artifactId>a2a-java-sdk-transport-jsonrpc</artifactId>
         </dependency>
 
+        <!-- Third-party dependencies needed for integration classes -->
+        <dependency>
+            <groupId>org.eclipse.microprofile.config</groupId>
+            <artifactId>microprofile-config-api</artifactId>
+        </dependency>
+
         <!-- Quarkus modules - should come from imported Quarkus BOM -->
         <dependency>
             <groupId>io.quarkus</groupId>

boms/sdk/pom.xml

@@ -52,6 +52,13 @@
                 <version>${project.version}</version>
             </dependency>
 
+            <!-- Integration modules -->
+            <dependency>
+                <groupId>${project.groupId}</groupId>
+                <artifactId>a2a-java-sdk-microprofile-config</artifactId>
+                <version>${project.version}</version>
+            </dependency>
+
             <!-- Client modules -->
             <dependency>
                 <groupId>${project.groupId}</groupId>

boms/sdk/src/it/sdk-usage-test/pom.xml

@@ -61,6 +61,12 @@
             <artifactId>a2a-java-sdk-server-common</artifactId>
         </dependency>
 
+        <!-- Integration modules -->
+        <dependency>
+            <groupId>io.github.a2asdk</groupId>
+            <artifactId>a2a-java-sdk-microprofile-config</artifactId>
+        </dependency>
+
         <!-- Client modules -->
         <dependency>
             <groupId>io.github.a2asdk</groupId>
@@ -122,6 +128,10 @@
             <groupId>io.grpc</groupId>
             <artifactId>grpc-stub</artifactId>
         </dependency>
+        <dependency>
+            <groupId>org.eclipse.microprofile.config</groupId>
+            <artifactId>microprofile-config-api</artifactId>
+        </dependency>
     </dependencies>
 
     <build>

extras/task-store-database-jpa/src/main/java/io/a2a/extras/taskstore/database/jpa/JpaDatabaseTaskStore.java

@@ -7,6 +7,7 @@
 import java.util.List;
 import java.util.stream.Stream;
 
+import jakarta.annotation.PostConstruct;
 import jakarta.annotation.Priority;
 import jakarta.enterprise.context.ApplicationScoped;
 import jakarta.enterprise.event.Event;
@@ -19,14 +20,14 @@
 
 import com.fasterxml.jackson.core.JsonProcessingException;
 import io.a2a.extras.common.events.TaskFinalizedEvent;
+import io.a2a.server.config.A2AConfigProvider;
 import io.a2a.server.tasks.TaskStateProvider;
 import io.a2a.server.tasks.TaskStore;
 import io.a2a.spec.Artifact;
 import io.a2a.spec.ListTasksParams;
 import io.a2a.spec.ListTasksResult;
 import io.a2a.spec.Message;
 import io.a2a.spec.Task;
-import org.eclipse.microprofile.config.inject.ConfigProperty;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -44,9 +45,24 @@ public class JpaDatabaseTaskStore implements TaskStore, TaskStateProvider {
     Event<TaskFinalizedEvent> taskFinalizedEvent;
 
     @Inject
-    @ConfigProperty(name = "a2a.replication.grace-period-seconds", defaultValue = "15")
+    A2AConfigProvider configProvider;
+
+    /**
+     * Grace period for task finalization in replicated scenarios (seconds).
+     * After a task reaches a final state, this is the minimum time to wait before cleanup
+     * to allow replicated events to arrive and be processed.
+     * <p>
+     * Property: {@code a2a.replication.grace-period-seconds}<br>
+     * Default: 15<br>
+     * Note: Property override requires a configurable {@link A2AConfigProvider} on the classpath.
+     */
     long gracePeriodSeconds;
 
+    @PostConstruct
+    void initConfig() {
+        gracePeriodSeconds = Long.parseLong(configProvider.getValue("a2a.replication.grace-period-seconds"));
+    }
+
     @Transactional
     @Override
     public void save(Task task) {

extras/task-store-database-jpa/src/main/resources/META-INF/a2a-defaults.properties

@@ -0,0 +1,6 @@
+# A2A JPA Database Task Store Default Configuration
+
+# Grace period for task finalization in replicated scenarios (seconds)
+# After a task reaches a final state, this is the minimum time to wait before cleanup
+# to allow replicated events to arrive and be processed
+a2a.replication.grace-period-seconds=15

integrations/microprofile-config/README.md

@@ -0,0 +1,148 @@
+# A2A Java SDK - MicroProfile Config Integration
+
+This optional integration module provides MicroProfile Config support for the A2A Java SDK configuration system.
+
+## Overview
+
+The A2A Java SDK core uses the `A2AConfigProvider` interface for configuration, with default values loaded from `META-INF/a2a-defaults.properties` files on the classpath.
+
+This module provides `MicroProfileConfigProvider`, which integrates with MicroProfile Config to allow configuration via:
+- `application.properties`
+- Environment variables
+- System properties (`-D` flags)
+- Custom ConfigSources
+
+## Quick Start
+
+### 1. Add Dependency
+
+```xml
+<dependency>
+    <groupId>io.github.a2asdk</groupId>
+    <artifactId>a2a-java-sdk-microprofile-config</artifactId>
+    <version>${io.a2a.sdk.version}</version>
+</dependency>
+```
+
+### 2. Configure Properties
+
+Once the dependency is added, you can override any A2A configuration property:
+
+**application.properties:**
+```properties
+# Executor configuration
+a2a.executor.core-pool-size=10
+a2a.executor.max-pool-size=100
+
+# Timeout configuration
+a2a.blocking.agent.timeout.seconds=60
+a2a.blocking.consumption.timeout.seconds=10
+```
+
+**Environment variables:**
+```bash
+export A2A_EXECUTOR_CORE_POOL_SIZE=10
+export A2A_BLOCKING_AGENT_TIMEOUT_SECONDS=60
+```
+
+**System properties:**
+```bash
+java -Da2a.executor.core-pool-size=10 -jar your-app.jar
+```
+
+## How It Works
+
+The `MicroProfileConfigProvider` implementation:
+
+1. **First tries MicroProfile Config** - Checks `application.properties`, environment variables, system properties, and custom ConfigSources
+2. **Falls back to defaults** - If not found, uses values from `META-INF/a2a-defaults.properties` provided by core modules and extras
+3. **Priority 50** - Can be overridden by custom providers with higher priority
+
+## Configuration Fallback Chain
+
+```
+MicroProfile Config Sources (application.properties, env vars, -D flags)
+  ↓ (not found?)
+DefaultValuesConfigProvider
+  → Scans classpath for ALL META-INF/a2a-defaults.properties files
+  → Merges all discovered properties together
+  → Throws exception if duplicate keys found
+  ↓ (property exists?)
+Return merged default value
+  ↓ (not found?)
+IllegalArgumentException
+```
+
+**Note**: All `META-INF/a2a-defaults.properties` files (from server-common, extras modules, etc.) are loaded and merged together by `DefaultValuesConfigProvider` at startup. This is not a sequential fallback chain, but a single merged set of defaults.
+
+## Available Configuration Properties
+
+See the [main README](../../README.md#configuration-system) for a complete list of configuration properties.
+
+## Framework Compatibility
+
+This module works with any MicroProfile Config implementation:
+
+- **Quarkus** - Built-in MicroProfile Config support
+- **Helidon** - Built-in MicroProfile Config support
+- **Open Liberty** - Built-in MicroProfile Config support
+- **WildFly/JBoss EAP** - Add `smallrye-config` dependency
+- **Other Jakarta EE servers** - Add MicroProfile Config implementation
+
+## Custom Config Providers
+
+If you're using a different framework (Spring, Micronaut, etc.), you can implement your own `A2AConfigProvider`:
+
+```java
+import io.a2a.server.config.A2AConfigProvider;
+import io.a2a.server.config.DefaultValuesConfigProvider;
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.enterprise.inject.Alternative;
+import jakarta.annotation.Priority;
+import jakarta.inject.Inject;
+
+@ApplicationScoped
+@Alternative
+@Priority(100)  // Higher than MicroProfileConfigProvider's priority of 50
+public class OtherEnvironmentConfigProvider implements A2AConfigProvider {
+
+    @Inject
+    Environment env;
+
+    @Inject
+    DefaultValuesConfigProvider defaultValues;
+
+    @Override
+    public String getValue(String name) {
+        String value = env.getProperty(name);
+        if (value != null) {
+            return value;
+        }
+        // Fallback to defaults
+        return defaultValues.getValue(name);
+    }
+
+    @Override
+    public Optional<String> getOptionalValue(String name) {
+        String value = env.getProperty(name);
+        if (value != null) {
+            return Optional.of(value);
+        }
+        return defaultValues.getOptionalValue(name);
+    }
+}
+```
+
+## Implementation Details
+
+- **Package**: `io.a2a.integrations.microprofile`
+- **Class**: `MicroProfileConfigProvider`
+- **Priority**: 50 (can be overridden)
+- **Scope**: `@ApplicationScoped`
+- **Dependencies**: MicroProfile Config API, A2A SDK server-common
+
+## Reference Implementations
+
+The A2A Java SDK reference implementations (Quarkus-based) automatically include this integration module, so MicroProfile Config properties work out of the box.
+
+If you're building a custom server implementation, add this dependency to enable property-based configuration.