Skip to content

Commit 85bf672

Browse files
kabirkabir
committed
Docuemnt the new mechanism
1 parent 0672827 commit 85bf672

File tree

2 files changed

+170
-13
lines changed

2 files changed

+170
-13
lines changed

‎README.md‎

Lines changed: 27 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -232,11 +232,22 @@ public class WeatherAgentExecutorProducer {
232232
}
233233
```
234234

235-
### 4. Configure Executor Settings (Optional)
235+
### 4. Configuration System
236236

237-
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.
237+
The A2A Java SDK uses a flexible configuration system that works across different frameworks.
238238

239-
You can customize the executor settings in your `application.properties`:
239+
**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.
240+
241+
**Customizing configuration:**
242+
- **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
243+
- **Spring/other frameworks**: See the [integration module README](integrations/microprofile-config/README.md#custom-config-providers) for how to implement a custom `A2AConfigProvider`
244+
- **Reference implementations**: Already include the MicroProfile Config integration
245+
246+
#### Configuration Properties
247+
248+
**Executor Settings** (Optional)
249+
250+
The SDK uses a dedicated executor for async operations like streaming. Default: 5 core threads, 50 max threads.
240251

241252
```properties
242253
# Core thread pool size for the @Internal executor (default: 5)
@@ -249,20 +260,23 @@ a2a.executor.max-pool-size=50
249260
a2a.executor.keep-alive-seconds=60
250261
```
251262

252-
**Why this matters:**
253-
- **Streaming Performance**: The executor handles streaming subscriptions. Too few threads can cause timeouts under concurrent load.
254-
- **Resource Management**: The dedicated executor prevents streaming operations from competing with the ForkJoinPool used by other async tasks.
255-
- **Concurrency**: In production environments with high concurrent streaming requests, increase the pool sizes accordingly.
263+
**Blocking Call Timeouts** (Optional)
256264

257-
**Default Configuration:**
258265
```properties
259-
# These are the defaults - no need to set unless you want different values
260-
a2a.executor.core-pool-size=5
261-
a2a.executor.max-pool-size=50
262-
a2a.executor.keep-alive-seconds=60
266+
# Timeout for agent execution in blocking calls (default: 30 seconds)
267+
a2a.blocking.agent.timeout.seconds=30
268+
269+
# Timeout for event consumption in blocking calls (default: 5 seconds)
270+
a2a.blocking.consumption.timeout.seconds=5
263271
```
264272

265-
**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.
273+
**Why this matters:**
274+
- **Streaming Performance**: The executor handles streaming subscriptions. Too few threads can cause timeouts under concurrent load.
275+
- **Resource Management**: The dedicated executor prevents streaming operations from competing with the ForkJoinPool.
276+
- **Concurrency**: In production with high concurrent streaming, increase pool sizes accordingly.
277+
- **Agent Timeouts**: LLM-based agents may need longer timeouts (60-120s) compared to simple agents.
278+
279+
**Note:** The reference server implementations (Quarkus-based) automatically include the MicroProfile Config integration, so properties work out of the box in `application.properties`.
266280

267281
## A2A Client
268282

‎integrations/microprofile-config/README.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# A2A Java SDK - MicroProfile Config Integration
2+
3+
This optional integration module provides MicroProfile Config support for the A2A Java SDK configuration system.
4+
5+
## Overview
6+
7+
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.
8+
9+
This module provides `MicroProfileConfigProvider`, which integrates with MicroProfile Config to allow configuration via:
10+
- `application.properties`
11+
- Environment variables
12+
- System properties (`-D` flags)
13+
- Custom ConfigSources
14+
15+
## Quick Start
16+
17+
### 1. Add Dependency
18+
19+
```xml
20+
<dependency>
21+
<groupId>io.github.a2asdk</groupId>
22+
<artifactId>a2a-java-sdk-microprofile-config</artifactId>
23+
<version>${io.a2a.sdk.version}</version>
24+
</dependency>
25+
```
26+
27+
### 2. Configure Properties
28+
29+
Once the dependency is added, you can override any A2A configuration property:
30+
31+
**application.properties:**
32+
```properties
33+
# Executor configuration
34+
a2a.executor.core-pool-size=10
35+
a2a.executor.max-pool-size=100
36+
37+
# Timeout configuration
38+
a2a.blocking.agent.timeout.seconds=60
39+
a2a.blocking.consumption.timeout.seconds=10
40+
```
41+
42+
**Environment variables:**
43+
```bash
44+
export A2A_EXECUTOR_CORE_POOL_SIZE=10
45+
export A2A_BLOCKING_AGENT_TIMEOUT_SECONDS=60
46+
```
47+
48+
**System properties:**
49+
```bash
50+
java -Da2a.executor.core-pool-size=10 -jar your-app.jar
51+
```
52+
53+
## How It Works
54+
55+
The `MicroProfileConfigProvider` implementation:
56+
57+
1. **First tries MicroProfile Config** - Checks `application.properties`, environment variables, system properties, and custom ConfigSources
58+
2. **Falls back to defaults** - If not found, uses values from `META-INF/a2a-defaults.properties` provided by core modules and extras
59+
3. **Priority 50** - Can be overridden by custom providers with higher priority
60+
61+
## Configuration Fallback Chain
62+
63+
```
64+
MicroProfile Config Sources (application.properties, env vars, -D flags)
65+
↓ (not found?)
66+
META-INF/a2a-defaults.properties (from server-common)
67+
↓ (not found?)
68+
META-INF/a2a-defaults.properties (from extras modules)
69+
↓ (not found?)
70+
IllegalArgumentException
71+
```
72+
73+
## Available Configuration Properties
74+
75+
See the [main README](../../README.md#configuration-system) for a complete list of configuration properties.
76+
77+
## Framework Compatibility
78+
79+
This module works with any MicroProfile Config implementation:
80+
81+
- **Quarkus** - Built-in MicroProfile Config support
82+
- **Helidon** - Built-in MicroProfile Config support
83+
- **Open Liberty** - Built-in MicroProfile Config support
84+
- **WildFly/JBoss EAP** - Add `smallrye-config` dependency
85+
- **Other Jakarta EE servers** - Add MicroProfile Config implementation
86+
87+
## Custom Config Providers
88+
89+
If you're using a different framework (Spring, Micronaut, etc.), you can implement your own `A2AConfigProvider`:
90+
91+
```java
92+
import io.a2a.server.config.A2AConfigProvider;
93+
import io.a2a.server.config.DefaultValuesConfigProvider;
94+
import jakarta.enterprise.context.ApplicationScoped;
95+
import jakarta.enterprise.inject.Alternative;
96+
import jakarta.annotation.Priority;
97+
import jakarta.inject.Inject;
98+
99+
@ApplicationScoped
100+
@Alternative
101+
@Priority(100) // Higher than MicroProfileConfigProvider's priority of 50
102+
public class SpringConfigProvider implements A2AConfigProvider {
103+
104+
@Inject
105+
Environment env;
106+
107+
@Inject
108+
DefaultValuesConfigProvider defaultValues;
109+
110+
@Override
111+
public String getValue(String name) {
112+
String value = env.getProperty(name);
113+
if (value != null) {
114+
return value;
115+
}
116+
// Fallback to defaults
117+
return defaultValues.getValue(name);
118+
}
119+
120+
@Override
121+
public Optional<String> getOptionalValue(String name) {
122+
String value = env.getProperty(name);
123+
if (value != null) {
124+
return Optional.of(value);
125+
}
126+
return defaultValues.getOptionalValue(name);
127+
}
128+
}
129+
```
130+
131+
## Implementation Details
132+
133+
- **Package**: `io.a2a.integrations.microprofile`
134+
- **Class**: `MicroProfileConfigProvider`
135+
- **Priority**: 50 (can be overridden)
136+
- **Scope**: `@ApplicationScoped`
137+
- **Dependencies**: MicroProfile Config API, A2A SDK server-common
138+
139+
## Reference Implementations
140+
141+
The A2A Java SDK reference implementations (Quarkus-based) automatically include this integration module, so MicroProfile Config properties work out of the box.
142+
143+
If you're building a custom server implementation, add this dependency to enable property-based configuration.

0 commit comments

Comments
 (0)