|
| 1 | +--- |
| 2 | +title: HTTP Clients |
| 3 | +description: Alternative HTTP client implementations for the A2A Java SDK, including Vert.x WebClient for reactive applications and an Android-specific client. |
| 4 | +layout: page |
| 5 | +--- |
| 6 | + |
| 7 | +# HTTP Clients |
| 8 | + |
| 9 | +The A2A SDK uses an `A2AHttpClient` abstraction for all HTTP communication — fetching agent cards, making transport calls, and SSE streaming. By default, the SDK uses a JDK 11+ HttpClient implementation. These extras provide alternative implementations. |
| 10 | + |
| 11 | +## Vert.x HTTP Client |
| 12 | + |
| 13 | +Replaces the default `JdkA2AHttpClient` with a [Vert.x WebClient](https://vertx.io/docs/vertx-web-client/java/)-based implementation (`VertxA2AHttpClient`) for reactive, non-blocking HTTP communication. |
| 14 | + |
| 15 | +### When to Use |
| 16 | + |
| 17 | +**Recommended for:** |
| 18 | + |
| 19 | +- Quarkus applications (Vert.x is already included) |
| 20 | +- Reactive applications using Vert.x or reactive frameworks |
| 21 | +- High-throughput scenarios with many concurrent requests |
| 22 | +- Applications requiring efficient SSE streaming |
| 23 | +- Cloud-native deployments optimizing for resource usage |
| 24 | + |
| 25 | +**Not needed for** simple, low-volume applications or environments where JDK HttpClient performs adequately. |
| 26 | + |
| 27 | +### What It Solves |
| 28 | + |
| 29 | +| | JDK HttpClient | Vert.x WebClient | |
| 30 | +|--|----------------|-------------------| |
| 31 | +| **I/O model** | Platform threads, blocking | Event loop, non-blocking | |
| 32 | +| **Memory** | Higher (one thread per connection) | Lower (shared event loop) | |
| 33 | +| **HTTP/2** | Manual configuration | Automatic ALPN negotiation | |
| 34 | +| **Reactive integration** | Requires bridging | Native | |
| 35 | + |
| 36 | +### 1. Add Dependency |
| 37 | + |
| 38 | +```xml |
| 39 | +<dependency> |
| 40 | + <groupId>org.a2aproject.sdk</groupId> |
| 41 | + <artifactId>a2a-java-sdk-http-client-vertx</artifactId> |
| 42 | +</dependency> |
| 43 | +``` |
| 44 | + |
| 45 | +For non-Quarkus environments, also add `vertx-web-client`: |
| 46 | + |
| 47 | +```xml |
| 48 | +<dependency> |
| 49 | + <groupId>io.vertx</groupId> |
| 50 | + <artifactId>vertx-web-client</artifactId> |
| 51 | +</dependency> |
| 52 | +``` |
| 53 | + |
| 54 | +### 2. Automatic Discovery (No Code Changes) |
| 55 | + |
| 56 | +The `VertxA2AHttpClientProvider` has **priority 100** (vs. 0 for the JDK client). The SDK's `A2AHttpClientFactory` uses `ServiceLoader` to discover and select the highest-priority provider available: |
| 57 | + |
| 58 | +```java |
| 59 | +// No changes needed — A2A SDK automatically uses VertxA2AHttpClient |
| 60 | +A2ACardResolver resolver = A2ACardResolver.builder().baseUrl("http://localhost:9999").build(); |
| 61 | +AgentCard card = resolver.getAgentCard(); // Uses Vert.x under the hood |
| 62 | + |
| 63 | +Client client = Client.builder(card) |
| 64 | + .withTransport(JSONRPCTransport.class, new JSONRPCTransportConfig()) |
| 65 | + .build(); |
| 66 | +``` |
| 67 | + |
| 68 | +If Vert.x classes are not on the classpath, the provider returns priority `-1` and the SDK falls back to the JDK HttpClient. |
| 69 | + |
| 70 | +### Usage Examples |
| 71 | + |
| 72 | +#### GET Request |
| 73 | + |
| 74 | +```java |
| 75 | +try (A2AHttpClient client = A2AHttpClientFactory.create()) { |
| 76 | + A2AHttpResponse response = client.createGet() |
| 77 | + .url("https://api.example.com/data") |
| 78 | + .addHeader("Authorization", "Bearer token") |
| 79 | + .get(); |
| 80 | + |
| 81 | + if (response.success()) { |
| 82 | + System.out.println(response.body()); |
| 83 | + } |
| 84 | +} |
| 85 | +``` |
| 86 | + |
| 87 | +#### POST Request with JSON Body |
| 88 | + |
| 89 | +```java |
| 90 | +try (A2AHttpClient client = A2AHttpClientFactory.create()) { |
| 91 | + A2AHttpResponse response = client.createPost() |
| 92 | + .url("https://api.example.com/submit") |
| 93 | + .addHeader("Content-Type", "application/json") |
| 94 | + .body("{\"key\":\"value\"}") |
| 95 | + .post(); |
| 96 | + |
| 97 | + System.out.println("Status: " + response.status()); |
| 98 | +} |
| 99 | +``` |
| 100 | + |
| 101 | +#### Server-Sent Events (SSE) Streaming |
| 102 | + |
| 103 | +```java |
| 104 | +try (A2AHttpClient client = A2AHttpClientFactory.create()) { |
| 105 | + CompletableFuture<Void> future = client.createGet() |
| 106 | + .url("https://api.example.com/stream") |
| 107 | + .getAsyncSSE( |
| 108 | + message -> System.out.println("Received: " + message), |
| 109 | + error -> error.printStackTrace(), |
| 110 | + () -> System.out.println("Stream complete") |
| 111 | + ); |
| 112 | + |
| 113 | + // Do other work while streaming... |
| 114 | + future.join(); |
| 115 | +} |
| 116 | +``` |
| 117 | + |
| 118 | +### CDI / Quarkus Integration |
| 119 | + |
| 120 | +In Quarkus or other CDI environments, the `VertxA2AHttpClient` automatically discovers and reuses the CDI-managed `Vertx` instance so that your entire application shares the same event loop. |
| 121 | + |
| 122 | +For non-CDI environments, you can share a Vert.x instance manually: |
| 123 | + |
| 124 | +```java |
| 125 | +Vertx vertx = Vertx.vertx(); |
| 126 | + |
| 127 | +try { |
| 128 | + try (VertxA2AHttpClient client = new VertxA2AHttpClient(vertx)) { |
| 129 | + A2AHttpResponse response = client.createGet() |
| 130 | + .url("https://example.com") |
| 131 | + .get(); |
| 132 | + } |
| 133 | +} finally { |
| 134 | + vertx.close(); |
| 135 | +} |
| 136 | +``` |
| 137 | + |
| 138 | +### Lifecycle Management |
| 139 | + |
| 140 | +| Usage | Behavior on close | |
| 141 | +|-------|--------------------| |
| 142 | +| Standalone (`new VertxA2AHttpClient()`) | Both `WebClient` and `Vertx` are closed | |
| 143 | +| CDI/Quarkus (`new VertxA2AHttpClient(injectedVertx)`) | Only `WebClient` is closed; `Vertx` remains open | |
| 144 | + |
| 145 | +Always use try-with-resources to avoid leaking `Vertx` instances. |
| 146 | + |
| 147 | +### Thread Safety |
| 148 | + |
| 149 | +- **Client instances** are thread-safe — multiple threads can use the same client |
| 150 | +- **Builder instances** are NOT thread-safe — create separate builders per thread |
| 151 | +- All I/O operations execute on Vert.x event loop threads |
| 152 | + |
| 153 | +### Performance Notes |
| 154 | + |
| 155 | +Synchronous methods (`.get()`, `.post()`, `.delete()`) block the calling thread despite using Vert.x's async API internally. Vert.x still provides benefits at the network layer: non-blocking I/O, efficient connection pooling, and lower thread usage overall. |
| 156 | + |
| 157 | +Async methods (`.getAsyncSSE()`, `.postAsyncSSE()`) are truly async — they return a `CompletableFuture` immediately. |
| 158 | + |
| 159 | +### Troubleshooting |
| 160 | + |
| 161 | +**Client not being used** — If logs show `JdkA2AHttpClient` instead of `VertxA2AHttpClient`, verify Vert.x WebClient is on the classpath: |
| 162 | + |
| 163 | +```bash |
| 164 | +mvn dependency:tree | grep vertx-web-client |
| 165 | +``` |
| 166 | + |
| 167 | +**ClassNotFoundException for Vert.x** — Add the `vertx-web-client` dependency (see above). For Quarkus, ensure `quarkus-vertx` is present. |
| 168 | + |
| 169 | +**Memory leaks** — Always use try-with-resources when creating `VertxA2AHttpClient` with the no-args constructor. |
| 170 | + |
| 171 | +### Version Compatibility |
| 172 | + |
| 173 | +- **Java**: 17+ |
| 174 | +- **Vert.x**: 4.x (tested with 4.5.0+) |
| 175 | +- **Quarkus**: Any version using Vert.x 4.x |
| 176 | +- **Jakarta EE**: 9.0+ |
| 177 | + |
| 178 | +## Android HTTP Client |
| 179 | + |
| 180 | +HTTP client implementation for Android applications. |
| 181 | + |
| 182 | +```xml |
| 183 | +<dependency> |
| 184 | + <groupId>org.a2aproject.sdk</groupId> |
| 185 | + <artifactId>a2a-java-sdk-http-client-android</artifactId> |
| 186 | +</dependency> |
| 187 | +``` |
0 commit comments