@@ -96,6 +102,7 @@ public class ClientBuilder {
private static final Map
+ * Returns an unmodifiable view of the parameters map. Attempting to modify
+ * the returned map will throw {@link UnsupportedOperationException}.
+ *
+ * @return an unmodifiable map of configured parameters (never null, but may be empty)
+ */
+ public Map Wrappers are discovered via Java's ServiceLoader mechanism. To register a wrapper,
+ * create a file {@code META-INF/services/io.a2a.client.transport.spi.ClientTransportWrapper}
+ * containing the fully qualified class name of your implementation.
+ *
+ * Wrappers are sorted by priority in descending order (highest priority first).
+ * This interface implements {@link Comparable} to enable natural sorting.
+ *
+ * Example implementation:
+ * Implementations should check the configuration to determine if they should
+ * actually wrap the transport. If the wrapper is not applicable (e.g., required
+ * configuration is missing), return the original transport unchanged.
+ *
+ * @param transport the transport to wrap
+ * @param config the transport configuration, may contain wrapper-specific parameters
+ * @return the wrapped transport, or the original if wrapping is not applicable
+ */
+ ClientTransport wrap(ClientTransport transport, ClientTransportConfig config);
+
+ /**
+ * Returns the priority of this wrapper. Higher priority wrappers are applied first
+ * (wrap the transport earlier, resulting in being the outermost wrapper).
+ *
+ * Default priority is 0. Suggested ranges:
+ * Note: This comparison is reversed (higher priority comes first) to enable
+ * natural sorting in descending priority order.
+ *
+ * @param other the wrapper to compare to
+ * @return negative if this has higher priority, positive if lower, zero if equal
+ */
+ @Override
+ default int compareTo(ClientTransportWrapper other) {
+ // Reverse comparison: higher priority should come first
+ return Integer.compare(other.priority(), this.priority());
+ }
+}
diff --git a/examples/helloworld/client/README.md b/examples/helloworld/client/README.md
index ac01c890f..cd5043f11 100644
--- a/examples/helloworld/client/README.md
+++ b/examples/helloworld/client/README.md
@@ -41,9 +41,13 @@ The Python A2A server is part of the [a2a-samples](https://github.com/google-a2a
The server will start running on `http://localhost:9999`.
-## Run the Java A2A Client with JBang
+### Using the Java Server Instead
-The Java client can be run using JBang, which allows you to run Java source files directly without any manual compilation.
+Alternatively, you can use the Java server example instead of the Python server. The Java server supports multiple transport protocols (JSONRPC, GRPC, and HTTP+JSON). See the [server README](../server/README.md) for details on starting the Java server with different transport protocols.
+
+## Run the Java A2A Client
+
+The Java client can be run using either Maven or JBang.
### Build the A2A Java SDK
@@ -54,38 +58,204 @@ cd /path/to/a2a-java
mvn clean install
```
-### Using the JBang script
+### Option 1: Using Maven (Recommended)
-A JBang script is provided in the example directory to make running the client easy:
+Run the client using Maven's exec plugin:
-1. Make sure you have JBang installed. If not, follow the [JBang installation guide](https://www.jbang.dev/documentation/guide/latest/installation.html).
+```bash
+cd examples/helloworld/client
+mvn exec:java
+```
-2. Navigate to the example directory:
- ```bash
- cd examples/helloworld/client/src/main/java/io/a2a/examples/helloworld/
- ```
+#### Transport Protocol Selection
+
+The client supports multiple transport protocols. You can select which protocol to use via the `quarkus.agentcard.protocol` property:
+
+**Using JSONRPC (default)**:
+```bash
+mvn exec:java
+```
+
+**Using GRPC**:
+```bash
+mvn exec:java -Dquarkus.agentcard.protocol=GRPC
+```
+
+**Using HTTP+JSON**:
+```bash
+mvn exec:java -Dquarkus.agentcard.protocol=HTTP+JSON
+```
+
+Available protocols:
+- `JSONRPC` - Uses JSON-RPC for communication (default)
+- `GRPC` - Uses gRPC for communication
+- `HTTP+JSON` - Uses HTTP with JSON payloads
+
+**Note**: The protocol you select on the client must match the protocol configured on the server.
+
+#### Enabling OpenTelemetry
+
+To enable OpenTelemetry with Maven:
+```bash
+mvn exec:java -Dopentelemetry=true
+```
+
+You can combine protocol selection with OpenTelemetry:
+```bash
+mvn exec:java -Dquarkus.agentcard.protocol=HTTP+JSON -Dopentelemetry=true
+```
+
+### Option 2: Using JBang
+
+A JBang script is provided for running the client without Maven:
+
+1. Make sure you have JBang installed. If not, follow the [JBang installation guide](https://www.jbang.dev/documentation/guide/latest/installation.html).
3. Run the client using the JBang script:
```bash
- jbang HelloWorldRunner.java
+ jbang examples/helloworld/client/src/main/java/io/a2a/examples/helloworld/HelloWorldRunner.java
```
-This script automatically handles the dependencies and sources for you.
+#### Transport Protocol Selection with JBang
+
+Select the transport protocol using the same `-Dquarkus.agentcard.protocol` property:
+
+**Using JSONRPC (default)**:
+```bash
+jbang examples/helloworld/client/src/main/java/io/a2a/examples/helloworld/HelloWorldRunner.java
+```
+
+**Using GRPC**:
+```bash
+jbang examples/helloworld/client/src/main/java/io/a2a/examples/helloworld/HelloWorldRunner.java -Dquarkus.agentcard.protocol=GRPC
+```
+
+**Using HTTP+JSON**:
+```bash
+jbang examples/helloworld/client/src/main/java/io/a2a/examples/helloworld/HelloWorldRunner.java -Dquarkus.agentcard.protocol=HTTP+JSON
+```
+
+#### Enabling OpenTelemetry with JBang
+
+To enable OpenTelemetry with JBang:
+```bash
+jbang examples/helloworld/client/src/main/java/io/a2a/examples/helloworld/HelloWorldRunner.java -Dopentelemetry=true
+```
+
+You can combine protocol selection with OpenTelemetry:
+```bash
+jbang examples/helloworld/client/src/main/java/io/a2a/examples/helloworld/HelloWorldRunner.java -Dquarkus.agentcard.protocol=GRPC -Dopentelemetry=true
+```
## What the Example Does
The Java client (`HelloWorldClient.java`) performs the following actions:
1. Fetches the server's public agent card
-2. Fetches the server's extended agent card
+2. Fetches the server's extended agent card
3. Creates a client using the extended agent card that connects to the Python server at `http://localhost:9999`.
4. Sends a regular message asking "how much is 10 USD in INR?".
5. Prints the server's response.
6. Sends the same message as a streaming request.
7. Prints each chunk of the server's streaming response as it arrives.
+## Enable OpenTelemetry (Optional)
+
+The client includes support for distributed tracing with OpenTelemetry. To enable it:
+
+### Prerequisites
+
+**IMPORTANT**: The client expects an OpenTelemetry collector to be ready and accepting traces. You have two options:
+
+#### Option 1: Use the Java Server Example (Recommended)
+
+Instead of the Python server, use the Java server example which has built-in OpenTelemetry support:
+
+1. **Start the Java server with OpenTelemetry enabled**:
+ ```bash
+ mvn quarkus:dev -Popentelemetry -pl examples/helloworld/server/ -Dquarkus.agentcard.protocol=HTTP+JSON
+ ```
+ This will:
+ - Start the server at `http://localhost:9999`
+ - Launch Grafana at `http://localhost:3001`
+ - Start OTLP collectors on ports 5317 (gRPC) and 5318 (HTTP)
+
+2. **Run the client with OpenTelemetry**:
+
+ Using Maven (from `examples/helloworld/client`):
+ ```bash
+ mvn exec:java -Dopentelemetry=true
+ ```
+
+ With specific protocol:
+ ```bash
+ mvn exec:java -Dquarkus.agentcard.protocol=HTTP+JSON -Dopentelemetry=true
+ ```
+
+ Or using JBang:
+ ```bash
+ jbang examples/helloworld/client/src/main/java/io/a2a/examples/helloworld/HelloWorldRunner.java -Dopentelemetry=true
+ ```
+
+ With specific protocol:
+ ```bash
+ jbang examples/helloworld/client/src/main/java/io/a2a/examples/helloworld/HelloWorldRunner.java -Dquarkus.agentcard.protocol=HTTP+JSON -Dopentelemetry=true
+ ```
+
+3. **View traces in Grafana**:
+ - Open `http://localhost:3001` (credentials: admin/admin)
+ - Go to "Explore" → select "Tempo" data source
+ - View distributed traces showing the full request flow from client to server
+
+#### Option 2: Use External OpenTelemetry Collector
+
+If you want to use the Python server with OpenTelemetry:
+
+1. **Start an OpenTelemetry collector** on port 5317 (e.g., using Docker):
+ ```bash
+ docker run -p 5317:4317 otel/opentelemetry-collector
+ ```
+
+2. **Run the Python server**
+
+3. **Run the client with OpenTelemetry**:
+ ```bash
+ mvn exec:java -Dopentelemetry=true
+ ```
+
+ Or with JBang:
+ ```bash
+ jbang examples/helloworld/client/src/main/java/io/a2a/examples/helloworld/HelloWorldRunner.java -Dopentelemetry=true
+ ```
+
+ With specific protocol:
+ ```bash
+ mvn exec:java -Dquarkus.agentcard.protocol=HTTP+JSON -Dopentelemetry=true
+ ```
+
+### What Gets Traced
+
+When OpenTelemetry is enabled, the client traces:
+- Agent card fetching (public and extended)
+- Message sending (blocking and streaming)
+- Task operations (get, cancel, list)
+- Push notification configuration operations
+- Connection and transport layer operations
+
+Client traces are automatically linked with server traces (when using the Java server), providing end-to-end visibility of the entire A2A protocol flow.
+
+### Configuration
+
+The client is configured to send traces to `http://localhost:5317` (OTLP gRPC endpoint). To use a different endpoint, modify the `initOpenTelemetry()` method in `HelloWorldClient.java`:
+
+```java
+OtlpGrpcSpanExporter.builder()
+ .setEndpoint("http://your-collector:4317")
+ .build()
+```
+
## Notes
- Make sure the Python server is running before starting the Java client.
- The client will wait for 10 seconds to collect streaming responses before exiting.
-- You can modify the message text or server URL in the `HelloWorldClient.java` file if needed.
\ No newline at end of file
+- You can modify the message text or server URL in the `HelloWorldClient.java` file if needed.
diff --git a/examples/helloworld/client/pom.xml b/examples/helloworld/client/pom.xml
index a9e0cf0d4..7f18c0ba8 100644
--- a/examples/helloworld/client/pom.xml
+++ b/examples/helloworld/client/pom.xml
@@ -12,7 +12,7 @@
{@code
+ * public class TracingWrapper implements ClientTransportWrapper {
+ * @Override
+ * public ClientTransport wrap(ClientTransport transport, ClientTransportConfig config) {
+ * if (config.getParameters().containsKey("tracer")) {
+ * return new TracingTransport(transport, (Tracer) config.getParameters().get("tracer"));
+ * }
+ * return transport;
+ * }
+ *
+ * @Override
+ * public int priority() {
+ * return 100; // Higher priority = wraps earlier (outermost)
+ * }
+ * }
+ * }
+ */
+public interface ClientTransportWrapper extends Comparable
+ *
+ *
+ * @return the priority value, higher values = higher priority
+ */
+ default int priority() {
+ return 0;
+ }
+
+ /**
+ * Compares this wrapper with another based on priority.
+ * Returns a negative integer, zero, or a positive integer as this wrapper
+ * has higher priority than, equal to, or lower priority than the specified wrapper.
+ *
+ *
This wrapper is automatically discovered via Java's ServiceLoader mechanism. + * To enable tracing, add a {@link Tracer} instance to the transport configuration: + *
{@code
+ * ClientTransportConfig config = new JSONRPCTransportConfig();
+ * config.setParameters(Map.of(
+ * OpenTelemetryClientTransportFactory.OTEL_TRACER_KEY,
+ * openTelemetry.getTracer("my-service"),
+ * OpenTelemetryClientTransportFactory.OTEL_OPEN_TELEMETRY_KEY,
+ * openTelemetry
+ * ));
+ * }
+ */
+public class OpenTelemetryClientPropagatorTransportWapper implements ClientTransportWrapper {
+
+ /**
+ * Configuration key for the OpenTelemetry Tracer instance.
+ * Value must be of type {@link Tracer}.
+ */
+ public static final String OTEL_TRACER_KEY = "io.a2a.extras.opentelemetry.Tracer";
+ public static final String OTEL_OPEN_TELEMETRY_KEY = "io.a2a.extras.opentelemetry.OpenTelemetry";
+
+ @Override
+ public ClientTransport wrap(ClientTransport transport, ClientTransportConfig config) {
+ Object openTelemetryObj = config.getParameters().get(OTEL_OPEN_TELEMETRY_KEY);
+ if (openTelemetryObj != null && openTelemetryObj instanceof OpenTelemetry openTelemetry) {
+ return new OpenTelemetryClientPropagatorTransport(transport, openTelemetry);
+ }
+ // No tracer configured, return unwrapped transport
+ return transport;
+ }
+
+ @Override
+ public int priority() {
+ // Observability/tracing should be in the middle priority range
+ // so it can observe other wrappers but doesn't interfere with security
+ return 500;
+ }
+}
diff --git a/extras/opentelemetry/client-propagation/src/main/java/io/a2a/extras/opentelemetry/client/propagation/package-info.java b/extras/opentelemetry/client-propagation/src/main/java/io/a2a/extras/opentelemetry/client/propagation/package-info.java
new file mode 100644
index 000000000..0ca927df9
--- /dev/null
+++ b/extras/opentelemetry/client-propagation/src/main/java/io/a2a/extras/opentelemetry/client/propagation/package-info.java
@@ -0,0 +1,5 @@
+@NullMarked
+package io.a2a.extras.opentelemetry.client.propagation;
+
+import org.jspecify.annotations.NullMarked;
+
diff --git a/extras/opentelemetry/client-propagation/src/main/resources/META-INF/services/io.a2a.client.transport.spi.ClientTransportWrapper b/extras/opentelemetry/client-propagation/src/main/resources/META-INF/services/io.a2a.client.transport.spi.ClientTransportWrapper
new file mode 100644
index 000000000..66627c2b2
--- /dev/null
+++ b/extras/opentelemetry/client-propagation/src/main/resources/META-INF/services/io.a2a.client.transport.spi.ClientTransportWrapper
@@ -0,0 +1 @@
+io.a2a.extras.opentelemetry.client.propagation.OpenTelemetryClientPropagatorTransportWapper
diff --git a/extras/opentelemetry/client/pom.xml b/extras/opentelemetry/client/pom.xml
new file mode 100644
index 000000000..daf97421c
--- /dev/null
+++ b/extras/opentelemetry/client/pom.xml
@@ -0,0 +1,48 @@
+
+This wrapper is automatically discovered via Java's ServiceLoader mechanism. + * To enable tracing, add a {@link Tracer} instance to the transport configuration: + *
{@code
+ * ClientTransportConfig config = new JSONRPCTransportConfig();
+ * config.setParameters(Map.of(
+ * OpenTelemetryClientTransportFactory.OTEL_TRACER_KEY,
+ * openTelemetry.getTracer("my-service"),
+ * OpenTelemetryClientTransportFactory.OTEL_OPEN_TELEMETRY_KEY,
+ * openTelemetry
+ * ));
+ * }
+ */
+public class OpenTelemetryClientTransportWrapper implements ClientTransportWrapper {
+
+ /**
+ * Configuration key for the OpenTelemetry Tracer instance.
+ * Value must be of type {@link Tracer}.
+ */
+ public static final String OTEL_TRACER_KEY = "io.a2a.extras.opentelemetry.Tracer";
+
+ @Override
+ public ClientTransport wrap(ClientTransport transport, ClientTransportConfig config) {
+ Object tracerObj = config.getParameters().get(OTEL_TRACER_KEY);
+ if (tracerObj != null && tracerObj instanceof Tracer tracer) {
+ return new OpenTelemetryClientTransport(transport, tracer);
+ }
+ // No tracer configured, return unwrapped transport
+ return transport;
+ }
+
+ @Override
+ public int priority() {
+ // Observability/tracing should be in the middle priority range
+ // so it can observe other wrappers but doesn't interfere with security
+ return 600;
+ }
+}
diff --git a/extras/opentelemetry/client/src/main/java/io/a2a/extras/opentelemetry/client/package-info.java b/extras/opentelemetry/client/src/main/java/io/a2a/extras/opentelemetry/client/package-info.java
new file mode 100644
index 000000000..0a7d54541
--- /dev/null
+++ b/extras/opentelemetry/client/src/main/java/io/a2a/extras/opentelemetry/client/package-info.java
@@ -0,0 +1,5 @@
+@NullMarked
+package io.a2a.extras.opentelemetry.client;
+
+import org.jspecify.annotations.NullMarked;
+
diff --git a/extras/opentelemetry/client/src/main/resources/META-INF/services/io.a2a.client.transport.spi.ClientTransportWrapper b/extras/opentelemetry/client/src/main/resources/META-INF/services/io.a2a.client.transport.spi.ClientTransportWrapper
new file mode 100644
index 000000000..801f7dd3a
--- /dev/null
+++ b/extras/opentelemetry/client/src/main/resources/META-INF/services/io.a2a.client.transport.spi.ClientTransportWrapper
@@ -0,0 +1 @@
+io.a2a.extras.opentelemetry.client.OpenTelemetryClientTransportWrapper
diff --git a/extras/opentelemetry/client/src/test/java/io/a2a/extras/opentelemetry/client/OpenTelemetryClientTransportTest.java b/extras/opentelemetry/client/src/test/java/io/a2a/extras/opentelemetry/client/OpenTelemetryClientTransportTest.java
new file mode 100644
index 000000000..e930c18e1
--- /dev/null
+++ b/extras/opentelemetry/client/src/test/java/io/a2a/extras/opentelemetry/client/OpenTelemetryClientTransportTest.java
@@ -0,0 +1,489 @@
+package io.a2a.extras.opentelemetry.client;
+
+import static io.a2a.extras.opentelemetry.A2AObservabilityNames.EXTRACT_REQUEST_SYS_PROPERTY;
+import static io.a2a.extras.opentelemetry.A2AObservabilityNames.EXTRACT_RESPONSE_SYS_PROPERTY;
+import static io.a2a.extras.opentelemetry.A2AObservabilityNames.GENAI_REQUEST;
+import static io.a2a.extras.opentelemetry.A2AObservabilityNames.GENAI_RESPONSE;
+
+import io.a2a.client.transport.spi.ClientTransport;
+import io.a2a.client.transport.spi.interceptors.ClientCallContext;
+import io.a2a.jsonrpc.common.wrappers.ListTasksResult;
+import io.a2a.spec.A2AClientException;
+import io.a2a.spec.AgentCard;
+import io.a2a.spec.DeleteTaskPushNotificationConfigParams;
+import io.a2a.spec.EventKind;
+import io.a2a.spec.GetTaskPushNotificationConfigParams;
+import io.a2a.spec.ListTaskPushNotificationConfigParams;
+import io.a2a.spec.ListTaskPushNotificationConfigResult;
+import io.a2a.spec.ListTasksParams;
+import io.a2a.spec.Message;
+import io.a2a.spec.MessageSendParams;
+import io.a2a.spec.StreamingEventKind;
+import io.a2a.spec.TextPart;
+import io.a2a.spec.Task;
+import io.a2a.spec.TaskIdParams;
+import io.a2a.spec.TaskPushNotificationConfig;
+import io.a2a.spec.TaskQueryParams;
+import io.opentelemetry.api.trace.Span;
+import io.opentelemetry.api.trace.SpanBuilder;
+import io.opentelemetry.api.trace.SpanContext;
+import io.opentelemetry.api.trace.SpanKind;
+import io.opentelemetry.api.trace.StatusCode;
+import io.opentelemetry.api.trace.Tracer;
+import io.opentelemetry.context.Scope;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.ArgumentCaptor;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.mockito.junit.jupiter.MockitoSettings;
+import org.mockito.quality.Strictness;
+
+import java.util.List;
+import java.util.function.Consumer;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.*;
+import static org.mockito.Mockito.*;
+
+import io.a2a.spec.A2AMethods;
+
+@ExtendWith(MockitoExtension.class)
+@MockitoSettings(strictness = Strictness.LENIENT)
+class OpenTelemetryClientTransportTest {
+
+ @Mock
+ private ClientTransport delegate;
+
+ @Mock
+ private Tracer tracer;
+
+ @Mock
+ private SpanBuilder spanBuilder;
+
+ @Mock
+ private Span span;
+
+ @Mock
+ private Scope scope;
+
+ @Mock
+ private SpanContext spanContext;
+
+ @Mock
+ private ClientCallContext context;
+
+ private OpenTelemetryClientTransport transport;
+
+ @BeforeEach
+ void setUp() {
+ System.setProperty(EXTRACT_REQUEST_SYS_PROPERTY, "true");
+ System.setProperty(EXTRACT_RESPONSE_SYS_PROPERTY, "true");
+ when(tracer.spanBuilder(anyString())).thenReturn(spanBuilder);
+ when(spanBuilder.setSpanKind(any(SpanKind.class))).thenReturn(spanBuilder);
+ when(spanBuilder.setAttribute(anyString(), anyString())).thenReturn(spanBuilder);
+ when(spanBuilder.setAttribute(anyString(), anyLong())).thenReturn(spanBuilder);
+ when(spanBuilder.addLink(any(SpanContext.class))).thenReturn(spanBuilder);
+ when(spanBuilder.startSpan()).thenReturn(span);
+ when(span.makeCurrent()).thenReturn(scope);
+ when(span.getSpanContext()).thenReturn(spanContext);
+ when(context.getHeaders()).thenReturn(new java.util.HashMap<>());
+
+ transport = new OpenTelemetryClientTransport(delegate, tracer);
+ }
+
+ @Test
+ void testSendMessage_Success() throws A2AClientException {
+ MessageSendParams request = mock(MessageSendParams.class);
+ EventKind expectedResult = mock(EventKind.class);
+ when(request.toString()).thenReturn("request-string");
+ when(expectedResult.toString()).thenReturn("response-string");
+ when(delegate.sendMessage(eq(request), any(ClientCallContext.class))).thenReturn(expectedResult);
+
+ EventKind result = transport.sendMessage(request, context);
+
+ assertEquals(expectedResult, result);
+ verify(tracer).spanBuilder(A2AMethods.SEND_MESSAGE_METHOD);
+ verify(spanBuilder).setSpanKind(SpanKind.CLIENT);
+ verify(spanBuilder).setAttribute(GENAI_REQUEST, "request-string");
+ verify(span).setAttribute(GENAI_RESPONSE, "response-string");
+ verify(span).setStatus(StatusCode.OK);
+ verify(span).end();
+ verify(scope).close();
+ }
+
+ @Test
+ void testSendMessage_NullResponse() throws A2AClientException {
+ MessageSendParams request = mock(MessageSendParams.class);
+ when(request.toString()).thenReturn("request-string");
+ when(delegate.sendMessage(eq(request), any(ClientCallContext.class))).thenReturn(null);
+
+ EventKind result = transport.sendMessage(request, context);
+
+ assertNull(result);
+ verify(spanBuilder).setAttribute(GENAI_REQUEST, "request-string");
+ verify(spanBuilder, never()).setAttribute(eq(GENAI_RESPONSE), anyString());
+ verify(span, never()).setStatus(StatusCode.OK);
+ verify(span).end();
+ }
+
+ @Test
+ void testSendMessage_ThrowsException() throws A2AClientException {
+ MessageSendParams request = mock(MessageSendParams.class);
+ when(request.toString()).thenReturn("request-string");
+ A2AClientException expectedException = new A2AClientException("Test error");
+ when(delegate.sendMessage(eq(request), any(ClientCallContext.class))).thenThrow(expectedException);
+
+ A2AClientException exception = assertThrows(A2AClientException.class,
+ () -> transport.sendMessage(request, context));
+
+ assertEquals(expectedException, exception);
+ verify(span).setStatus(StatusCode.ERROR, "Test error");
+ verify(span).end();
+ verify(scope).close();
+ }
+
+ @Test
+ void testSendMessageStreaming() throws A2AClientException {
+ MessageSendParams request = mock(MessageSendParams.class);
+ when(request.toString()).thenReturn("request-string");
+ Consumer
+ * This package contains common utilities, constants, and helper classes
+ * used across both client and server OpenTelemetry integrations.
+ */
+@org.jspecify.annotations.NullMarked
+package io.a2a.extras.opentelemetry;
diff --git a/extras/opentelemetry/integration-tests/README.md b/extras/opentelemetry/integration-tests/README.md
new file mode 100644
index 000000000..a66fe8f6c
--- /dev/null
+++ b/extras/opentelemetry/integration-tests/README.md
@@ -0,0 +1,160 @@
+# OpenTelemetry Integration Tests (Quarkus-based)
+
+## Overview
+
+This module provides **Quarkus-based integration tests** for OpenTelemetry tracing in the A2A Java SDK, similar to the approach used in the [Quarkus OpenTelemetry quickstart](https://github.com/quarkusio/quarkus/tree/main/integration-tests/opentelemetry-quickstart).
+
+Unlike the previous mock-based tests, these are **real integration tests** that:
+- Start an actual Quarkus application
+- Expose a REST API with A2A agent endpoints
+- Make real HTTP requests
+- Validate that OpenTelemetry spans are created correctly
+
+## Architecture
+
+### Components
+
+1. **SimpleAgent** - A basic A2A agent implementation for testing
+ - Implements all RequestHandler methods
+ - Stores tasks in memory
+ - Provides simple echo responses for messages
+
+2. **AgentResource** - JAX-RS REST resource
+ - Exposes HTTP endpoints (`/a2a/tasks`, `/a2a/messages`, etc.)
+ - Delegates to the RequestHandler
+ - Creates ServerCallContext for each request
+
+3. **InstrumentedRequestHandler** - CDI Alternative
+ - Wraps SimpleAgent with OpenTelemetry decorator
+ - Delegates to the OpenTelemetry decorator for span creation
+ - Ensures spans are created for each operation
+
+4. **OpenTelemetryProducer** - CDI bean producer
+ - Creates the Tracer from Quarkus OpenTelemetry
+ - Produces the OpenTelemetryRequestHandlerDecorator (CDI decorator)
+ - Integrates with Quarkus OpenTelemetry extension
+
+## Test Strategy
+
+### Functional Tests (`OpenTelemetryIntegrationTest`)
+- Use `@QuarkusTest` annotation
+- Make real HTTP requests using REST Assured
+- Verify HTTP responses are correct
+- Ensure the application behaves correctly end-to-end
+
+### Tracing Tests (`OpenTelemetryTracingTest`)
+- Use `InMemorySpanExporter` to capture spans
+- Verify that HTTP requests create OpenTelemetry spans
+- Validate span names, kinds (CLIENT/SERVER), and status codes
+- Check that spans are properly ended
+
+## Current Status
+
+### ✅ Completed
+- Project structure and POM configuration
+- Quarkus dependencies and plugins (including opentelemetry-sdk-testing)
+- SimpleAgentExecutor following reference module pattern
+- TestAgentCardProducer with proper JSONRPC interface
+- InMemorySpanExporter producer for span validation
+- OpenTelemetryIntegrationTest using Client API
+- Tests compile and run (service loader issues resolved)
+
+### 🔨 In Progress / Known Issues
+
+1. **Test Execution Timeouts**
+ - Tests are timing out during message send operations
+ - Error: "Timeout waiting for consumption to complete for task test-task-1"
+ - Likely a configuration issue between client (non-streaming) and server (streaming capable)
+ - Need to investigate JSONRPC transport configuration
+
+2. **Span Validation**
+ - InMemorySpanExporter is configured but needs verification
+ - Some tests are not finding expected spans
+ - May need to configure span processor to route to InMemorySpanExporter
+
+## Running the Tests
+
+### Prerequisites
+```bash
+# Build all A2A SDK modules first
+mvn clean install -DskipTests
+```
+
+### Run Integration Tests
+```bash
+# From the integration-tests directory
+mvn clean verify
+
+# Or from the root
+mvn verify -pl extras/opentelemetry/integration-tests -am
+```
+
+### Run Specific Test
+```bash
+mvn test -Dtest=OpenTelemetryIntegrationTest
+```
+
+## Configuration
+
+### Application Properties
+- `src/main/resources/application.properties` - Runtime configuration
+- `src/test/resources/application.properties` - Test-specific configuration
+
+Key settings:
+```properties
+# OpenTelemetry
+quarkus.otel.sdk.disabled=false
+quarkus.otel.traces.enabled=true
+quarkus.otel.service.name=a2a-opentelemetry-integration-test
+
+# Test mode: use in-memory exporter
+quarkus.otel.traces.exporter=none
+```
+
+### beans.xml
+Located at `src/main/resources/META-INF/beans.xml`:
+- Enables CDI bean discovery
+- Configures alternatives (InstrumentedRequestHandler)
+
+## Next Steps
+
+To complete this integration test module:
+
+1. **Resolve CDI ambiguity**
+ - Add `@Named` or custom qualifier to SimpleAgent
+ - Or exclude DefaultRequestHandler from test classpath
+ - Or use `@Alternative` more effectively
+
+2. **Configure span exporter**
+ - Properly wire InMemorySpanExporter into Quarkus OpenTelemetry
+ - May need custom OTel SDK configuration
+
+3. **Add more test scenarios**
+ - Test error handling and error spans
+ - Test streaming operations
+ - Test context propagation across services
+ - Test span attributes and metadata
+
+4. **Performance testing** (optional)
+ - Measure overhead of OpenTelemetry instrumentation
+ - Verify spans don't impact performance significantly
+
+## Comparison with Quarkus Quickstart
+
+This implementation follows the same patterns as the Quarkus OpenTelemetry quickstart:
+- ✅ Uses `@QuarkusTest` for integration tests
+- ✅ Uses REST Assured for HTTP testing
+- ✅ Integrates with Quarkus OpenTelemetry extension
+- ✅ Uses in-memory span exporter for validation
+- ✅ Tests actual HTTP requests, not mocks
+
+Unlike the quickstart which is a standalone app, this module:
+- Tests A2A SDK-specific functionality
+- Validates OpenTelemetry CDI decorator integration
+- Focuses on A2A protocol operations (tasks, messages, etc.)
+
+## References
+
+- [Quarkus OpenTelemetry Guide](https://quarkus.io/guides/opentelemetry)
+- [Quarkus OpenTelemetry Quickstart](https://github.com/quarkusio/quarkus/tree/main/integration-tests/opentelemetry-quickstart)
+- [OpenTelemetry Java Documentation](https://opentelemetry.io/docs/languages/java/)
diff --git a/extras/opentelemetry/integration-tests/pom.xml b/extras/opentelemetry/integration-tests/pom.xml
new file mode 100644
index 000000000..7f6c52871
--- /dev/null
+++ b/extras/opentelemetry/integration-tests/pom.xml
@@ -0,0 +1,117 @@
+
+
+ * This test uses the Client API and TestUtilsBean to validate that
+ * OpenTelemetry spans are created correctly for A2A operations.
+ */
+@QuarkusTest
+class OpenTelemetryA2ATest extends BaseTest {
+
+ private Client client;
+ private int serverPort = 8081;
+
+ @BeforeEach
+ void setUp() throws A2AClientException {
+ // Create client with non-streaming mode for simplicity
+ ClientConfig clientConfig = new ClientConfig.Builder()
+ .setStreaming(false)
+ .build();
+
+ client = Client.builder(A2A.getAgentCard("http://localhost:8081"))
+ .clientConfig(clientConfig)
+ .withTransport(JSONRPCTransport.class, new JSONRPCTransportConfigBuilder())
+ .build();
+ }
+
+ @BeforeEach
+ void reset() {
+ await().atMost(5, SECONDS).until(() -> {
+ List
+ * This decorator adds distributed tracing to A2A server request handlers.
+ * It creates spans for each request handler method invocation, capturing:
+ *
+ * To enable this decorator, add it to your beans.xml:
+ *
+ *
+ * {@code
+ *
+ */
+@Decorator
+@Priority(100)
+public abstract class OpenTelemetryRequestHandlerDecorator implements RequestHandler {
+
+ private static final Logger LOGGER = LoggerFactory.getLogger(OpenTelemetryRequestHandlerDecorator.class);
+
+ @Inject
+ @Delegate
+ @Any
+ private RequestHandler delegate;
+
+ @Inject
+ private Tracer tracer;
+
+ /**
+ * Default constructor for CDI.
+ */
+ public OpenTelemetryRequestHandlerDecorator() {
+ }
+
+ /**
+ * Constructor for testing.
+ *
+ * @param delegate the delegate request handler
+ * @param tracer the tracer to use
+ */
+ public OpenTelemetryRequestHandlerDecorator(RequestHandler delegate, Tracer tracer) {
+ this.delegate = delegate;
+ this.tracer = tracer;
+ }
+
+ @Override
+ public Task onGetTask(TaskQueryParams params, ServerCallContext context) throws A2AError {
+ var spanBuilder = tracer.spanBuilder(A2AMethods.GET_TASK_METHOD)
+ .setSpanKind(SpanKind.SERVER)
+ .setAttribute(GENAI_OPERATION_NAME, A2AMethods.GET_TASK_METHOD);
+
+ if (params.id() != null) {
+ spanBuilder.setAttribute(GENAI_TASK_ID, params.id());
+ }
+ if (extractRequest()) {
+ spanBuilder.setAttribute(GENAI_REQUEST, params.toString());
+ }
+
+ Span span = spanBuilder.startSpan();
+
+ try (Scope scope = span.makeCurrent()) {
+ Task result = delegate.onGetTask(params, context);
+
+ if (result != null && extractResponse()) {
+ span.setAttribute(GENAI_RESPONSE, result.toString());
+ }
+
+ span.setStatus(StatusCode.OK);
+ return result;
+ } catch (A2AError error) {
+ span.setAttribute(ERROR_TYPE, error.getMessage());
+ span.setStatus(StatusCode.ERROR, error.getMessage());
+ throw error;
+ } finally {
+ span.end();
+ }
+ }
+
+ @Override
+ public ListTasksResult onListTasks(ListTasksParams params, ServerCallContext context) throws A2AError {
+ var spanBuilder = tracer.spanBuilder(A2AMethods.LIST_TASK_METHOD)
+ .setSpanKind(SpanKind.SERVER)
+ .setAttribute(GENAI_OPERATION_NAME, A2AMethods.LIST_TASK_METHOD);
+
+ if (extractRequest()) {
+ spanBuilder.setAttribute(GENAI_REQUEST, params.toString());
+ }
+ if (params.contextId() != null) {
+ spanBuilder.setAttribute(GENAI_CONTEXT_ID, params.contextId());
+ }
+ Span span = spanBuilder.startSpan();
+
+ try (Scope scope = span.makeCurrent()) {
+ ListTasksResult result = delegate.onListTasks(params, context);
+
+ if (result != null && extractResponse()) {
+ span.setAttribute(GENAI_RESPONSE, result.toString());
+ }
+
+ span.setStatus(StatusCode.OK);
+ return result;
+ } catch (A2AError error) {
+ span.setAttribute(ERROR_TYPE, error.getMessage());
+ span.setStatus(StatusCode.ERROR, error.getMessage());
+ throw error;
+ } finally {
+ span.end();
+ }
+ }
+
+ @Override
+ public Task onCancelTask(TaskIdParams params, ServerCallContext context) throws A2AError {
+ var spanBuilder = tracer.spanBuilder(A2AMethods.CANCEL_TASK_METHOD)
+ .setSpanKind(SpanKind.SERVER)
+ .setAttribute(GENAI_OPERATION_NAME, A2AMethods.CANCEL_TASK_METHOD);
+
+ if (params.id() != null) {
+ spanBuilder.setAttribute(GENAI_TASK_ID, params.id());
+ }
+ if (extractRequest()) {
+ spanBuilder.setAttribute(GENAI_REQUEST, params.toString());
+ }
+
+ Span span = spanBuilder.startSpan();
+
+ try (Scope scope = span.makeCurrent()) {
+ Task result = delegate.onCancelTask(params, context);
+
+ if (result != null && extractResponse()) {
+ span.setAttribute(GENAI_RESPONSE, result.toString());
+ }
+
+ span.setStatus(StatusCode.OK);
+ return result;
+ } catch (A2AError error) {
+ span.setAttribute(ERROR_TYPE, error.getMessage());
+ span.setStatus(StatusCode.ERROR, error.getMessage());
+ throw error;
+ } finally {
+ span.end();
+ }
+ }
+
+ @Override
+ public EventKind onMessageSend(MessageSendParams params, ServerCallContext context) throws A2AError {
+ var spanBuilder = tracer.spanBuilder(A2AMethods.SEND_MESSAGE_METHOD)
+ .setSpanKind(SpanKind.SERVER)
+ .setAttribute(GENAI_OPERATION_NAME, A2AMethods.SEND_MESSAGE_METHOD);
+
+ if (params.message() != null) {
+ if (params.message().taskId() != null) {
+ spanBuilder.setAttribute(GENAI_TASK_ID, params.message().taskId());
+ }
+ if (params.message().contextId() != null) {
+ spanBuilder.setAttribute(GENAI_CONTEXT_ID, params.message().contextId());
+ }
+ if (params.message().messageId() != null) {
+ spanBuilder.setAttribute(GENAI_MESSAGE_ID, params.message().messageId());
+ }
+ if (params.message().role() != null) {
+ spanBuilder.setAttribute(GENAI_ROLE, params.message().role().asString());
+ }
+ if (params.message().extensions() != null && !params.message().extensions().isEmpty()) {
+ spanBuilder.setAttribute(GENAI_EXTENSIONS, String.join(",", params.message().extensions()));
+ }
+ spanBuilder.setAttribute(GENAI_PARTS_NUMBER, params.message().parts().size());
+ }
+ if (extractRequest()) {
+ spanBuilder.setAttribute(GENAI_REQUEST, params.toString());
+ }
+
+ Span span = spanBuilder.startSpan();
+
+ try (Scope scope = span.makeCurrent()) {
+ EventKind result = delegate.onMessageSend(params, context);
+
+ if (result != null && extractResponse()) {
+ span.setAttribute(GENAI_RESPONSE, result.toString());
+ }
+
+ span.setStatus(StatusCode.OK);
+ return result;
+ } catch (A2AError error) {
+ span.setAttribute(ERROR_TYPE, error.getMessage());
+ span.setStatus(StatusCode.ERROR, error.getMessage());
+ throw error;
+ } finally {
+ span.end();
+ }
+ }
+
+ @Override
+ public Flow.Publisher
diff --git a/spec/src/main/java/io/a2a/spec/Task.java b/spec/src/main/java/io/a2a/spec/Task.java index 24336dcd9..b51db72ce 100644 --- a/spec/src/main/java/io/a2a/spec/Task.java +++ b/spec/src/main/java/io/a2a/spec/Task.java @@ -103,6 +103,11 @@ public static Builder builder(Task task) { return new Builder(task); } + @Override + public String toString() { + return "Task{" + "id=" + id + ", contextId=" + contextId + ", status=" + status + ", artifacts=" + artifacts + ", history=" + history + ", metadata=" + metadata + '}'; + } + /** * Builder for constructing immutable {@link Task} instances. *
diff --git a/transport/grpc/src/main/java/io/a2a/transport/grpc/context/GrpcContextKeys.java b/transport/grpc/src/main/java/io/a2a/transport/grpc/context/GrpcContextKeys.java
index a025236f0..a1392f20a 100644
--- a/transport/grpc/src/main/java/io/a2a/transport/grpc/context/GrpcContextKeys.java
+++ b/transport/grpc/src/main/java/io/a2a/transport/grpc/context/GrpcContextKeys.java
@@ -1,16 +1,20 @@
package io.a2a.transport.grpc.context;
+
+import java.util.Map;
+
+import io.a2a.spec.A2AMethods;
import io.grpc.Context;
/**
* Shared gRPC context keys for A2A protocol data.
- *
+ *
* These keys provide access to gRPC context information similar to
* Python's grpc.aio.ServicerContext, enabling rich context access
* in service method implementations.
*/
public final class GrpcContextKeys {
-
+
/**
* Context key for storing the X-A2A-Version header value.
* Set by server interceptors and accessed by service handlers.
@@ -24,21 +28,28 @@ public final class GrpcContextKeys {
*/
public static final Context.Key