fix!: Update the name of A2A headers (#709)

A2A-Version and A2A-Extensions are specified by the spec (as of dec790a)
instead of the X-A2A-*.

Also updates the gRPC context keys to get rid of the  prefix.

I did not change the `X-A2A-Notification-Token` header that is still
present in the spec but I'll open a PR to verify if that's not an
omission

Signed-off-by: Jeff Mesnil <jmesnil@ibm.com>

Author: jmesnil

client/transport/grpc/src/main/java/io/a2a/client/transport/grpc/GrpcTransport.java

@@ -61,10 +61,10 @@ public class GrpcTransport implements ClientTransport {
             AuthInterceptor.AUTHORIZATION,
             Metadata.ASCII_STRING_MARSHALLER);
     private static final Metadata.Key<String> EXTENSIONS_KEY = Metadata.Key.of(
-            A2AHeaders.X_A2A_EXTENSIONS,
+            A2AHeaders.A2A_EXTENSIONS.toLowerCase(),
             Metadata.ASCII_STRING_MARSHALLER);
     private static final Metadata.Key<String> VERSION_KEY = Metadata.Key.of(
-            A2AHeaders.X_A2A_VERSION,
+            A2AHeaders.A2A_VERSION.toLowerCase(),
             Metadata.ASCII_STRING_MARSHALLER);
     private final A2AServiceBlockingV2Stub blockingStub;
     private final A2AServiceStub asyncStub;
@@ -380,8 +380,8 @@ private io.a2a.grpc.SendMessageRequest createGrpcSendMessageRequest(MessageSendP
 
     /**
      * Creates gRPC metadata from ClientCallContext headers.
-     * Extracts headers like X-A2A-Extensions and sets them as gRPC metadata.
-     *
+     * Extracts headers like a2a-extensions and sets them as gRPC metadata.
+     * The headers are lower-cased (compared to the HTTP headers).
      * @param context the client call context containing headers, may be null
      * @param payloadAndHeaders the payload and headers wrapper, may be null
      * @return the gRPC metadata
@@ -390,14 +390,14 @@ private Metadata createGrpcMetadata(@Nullable ClientCallContext context, @Nullab
         Metadata metadata = new Metadata();
 
         if (context != null && context.getHeaders() != null) {
-            // Set X-A2A-Version header if present
-            String versionHeader = context.getHeaders().get(A2AHeaders.X_A2A_VERSION);
+            // Set a2a-version header if present
+            String versionHeader = context.getHeaders().get(A2AHeaders.A2A_VERSION.toLowerCase());
             if (versionHeader != null) {
                 metadata.put(VERSION_KEY, versionHeader);
             }
 
-            // Set X-A2A-Extensions header if present
-            String extensionsHeader = context.getHeaders().get(A2AHeaders.X_A2A_EXTENSIONS);
+            // Set a2a-extensions header if present
+            String extensionsHeader = context.getHeaders().get(A2AHeaders.A2A_EXTENSIONS.toLowerCase());
             if (extensionsHeader != null) {
                 metadata.put(EXTENSIONS_KEY, extensionsHeader);
             }

common/src/main/java/io/a2a/common/A2AHeaders.java

@@ -9,13 +9,13 @@ public final class A2AHeaders {
      * HTTP header name for A2A protocol version.
      * Used to communicate the protocol version that the client is using.
      */
-    public static final String X_A2A_VERSION = "X-A2A-Version";
+    public static final String A2A_VERSION = "A2A-Version";
 
     /**
      * HTTP header name for A2A extensions.
      * Used to communicate which extensions are requested by the client.
      */
-    public static final String X_A2A_EXTENSIONS = "X-A2A-Extensions";
+    public static final String A2A_EXTENSIONS = "A2A-Extensions";
 
     /**
      * HTTP header name for a push notification token.

reference/grpc/src/main/java/io/a2a/server/grpc/quarkus/A2AExtensionsInterceptor.java

@@ -21,8 +21,8 @@
  *
  * <h2>Captured Information</h2>
  * <ul>
- *   <li><b>A2A Protocol Version</b>: {@code X-A2A-Version} header</li>
- *   <li><b>A2A Extensions</b>: {@code X-A2A-Extensions} header</li>
+ *   <li><b>A2A Protocol Version</b>: {@code a2a-version} header</li>
+ *   <li><b>A2A Extensions</b>: {@code a2a-extensions} header</li>
  *   <li><b>Complete Metadata</b>: All request headers via {@link io.grpc.Metadata}</li>
  *   <li><b>Method Name</b>: gRPC method being invoked</li>
  *   <li><b>Peer Information</b>: Client connection details</li>
@@ -60,6 +60,13 @@
 @ApplicationScoped
 public class A2AExtensionsInterceptor implements ServerInterceptor {
 
+    private static final Metadata.Key<String> EXTENSIONS_KEY = Metadata.Key.of(
+            A2AHeaders.A2A_EXTENSIONS.toLowerCase(),
+            Metadata.ASCII_STRING_MARSHALLER);
+    private static final Metadata.Key<String> VERSION_KEY = Metadata.Key.of(
+            A2AHeaders.A2A_VERSION.toLowerCase(),
+            Metadata.ASCII_STRING_MARSHALLER);
+
     /**
      * Intercepts incoming gRPC calls to capture metadata and context information.
      *
@@ -68,8 +75,8 @@ public class A2AExtensionsInterceptor implements ServerInterceptor {
      *
      * <p><b>Extraction Process:</b>
      * <ol>
-     *   <li>Extract {@code X-A2A-Version} header from metadata</li>
-     *   <li>Extract {@code X-A2A-Extensions} header from metadata</li>
+     *   <li>Extract {@code a2a-version} header from metadata</li>
+     *   <li>Extract {@code a2a-extensions} header from metadata</li>
      *   <li>Capture complete {@link Metadata} object</li>
      *   <li>Capture gRPC method name from {@link ServerCall}</li>
      *   <li>Map gRPC method to A2A protocol method name</li>
@@ -92,14 +99,9 @@ public <ReqT, RespT> ServerCall.Listener<ReqT> interceptCall(
             ServerCallHandler<ReqT, RespT> serverCallHandler) {
 
         // Extract A2A protocol version header
-        Metadata.Key<String> versionKey =
-            Metadata.Key.of(A2AHeaders.X_A2A_VERSION, Metadata.ASCII_STRING_MARSHALLER);
-        String version = metadata.get(versionKey);
-
+        String version = metadata.get(VERSION_KEY);
         // Extract A2A extensions header
-        Metadata.Key<String> extensionsKey =
-            Metadata.Key.of(A2AHeaders.X_A2A_EXTENSIONS, Metadata.ASCII_STRING_MARSHALLER);
-        String extensions = metadata.get(extensionsKey);
+        String extensions = metadata.get(EXTENSIONS_KEY);
 
         // Create enhanced context with rich information (equivalent to Python's ServicerContext)
         Context context = Context.current()

reference/jsonrpc/src/main/java/io/a2a/server/apps/quarkus/A2AServerRoutes.java

@@ -514,11 +514,11 @@ public String getUsername() {
             state.put(TENANT_KEY, extractTenant(rc));
             state.put(TRANSPORT_KEY, TransportProtocol.JSONRPC);
 
-            // Extract requested protocol version from X-A2A-Version header
-            String requestedVersion = rc.request().getHeader(A2AHeaders.X_A2A_VERSION);
+            // Extract requested protocol version from A2A-Version header
+            String requestedVersion = rc.request().getHeader(A2AHeaders.A2A_VERSION);
 
-            // Extract requested extensions from X-A2A-Extensions header
-            List<String> extensionHeaderValues = rc.request().headers().getAll(A2AHeaders.X_A2A_EXTENSIONS);
+            // Extract requested extensions from A2A-Extensions header
+            List<String> extensionHeaderValues = rc.request().headers().getAll(A2AHeaders.A2A_EXTENSIONS);
             Set<String> requestedExtensions = A2AExtensions.getRequestedExtensions(extensionHeaderValues);
 
             return new ServerCallContext(user, state, requestedExtensions, requestedVersion);

reference/rest/src/main/java/io/a2a/server/rest/quarkus/A2AServerRoutes.java

@@ -731,11 +731,11 @@ public String getUsername() {
             state.put(TENANT_KEY, extractTenant(rc));
             state.put(TRANSPORT_KEY, TransportProtocol.HTTP_JSON);
 
-            // Extract requested protocol version from X-A2A-Version header
-            String requestedVersion = rc.request().getHeader(A2AHeaders.X_A2A_VERSION);
+            // Extract requested protocol version from A2A-Version header
+            String requestedVersion = rc.request().getHeader(A2AHeaders.A2A_VERSION);
 
-            // Extract requested extensions from X-A2A-Extensions header
-            List<String> extensionHeaderValues = rc.request().headers().getAll(A2AHeaders.X_A2A_EXTENSIONS);
+            // Extract requested extensions from A2A-Extensions header
+            List<String> extensionHeaderValues = rc.request().headers().getAll(A2AHeaders.A2A_EXTENSIONS);
             Set<String> requestedExtensions = A2AExtensions.getRequestedExtensions(extensionHeaderValues);
 
             return new ServerCallContext(user, state, requestedExtensions, requestedVersion);

transport/grpc/src/main/java/io/a2a/transport/grpc/context/GrpcContextKeys.java

@@ -1,8 +1,12 @@
 package io.a2a.transport.grpc.context;
 
 
+import static java.util.Locale.ROOT;
+
+import java.util.Locale;
 import java.util.Map;
 
+import io.a2a.common.A2AHeaders;
 import io.a2a.spec.A2AMethods;
 import io.grpc.Context;
 
@@ -40,18 +44,18 @@
 public final class GrpcContextKeys {
 
     /**
-     * Context key for storing the X-A2A-Version header value.
+     * Context key for storing the a2a-version header value.
      * Set by server interceptors and accessed by service handlers.
      */
     public static final Context.Key<String> VERSION_HEADER_KEY =
-        Context.key("x-a2a-version");
+        Context.key(A2AHeaders.A2A_VERSION.toLowerCase(ROOT));
 
     /**
-     * Context key for storing the X-A2A-Extensions header value.
+     * Context key for storing the a2a-extensions header value.
      * Set by server interceptors and accessed by service handlers.
      */
     public static final Context.Key<String> EXTENSIONS_HEADER_KEY =
-        Context.key("x-a2a-extensions");
+        Context.key(A2AHeaders.A2A_EXTENSIONS.toLowerCase(ROOT));
 
     /**
      * Context key for storing the complete gRPC Metadata object.

transport/grpc/src/main/java/io/a2a/transport/grpc/handler/CallContextFactory.java

@@ -18,8 +18,8 @@
  *   <li>User authentication from security context</li>
  *   <li>gRPC metadata (headers)</li>
  *   <li>Method name and peer information</li>
- *   <li>A2A protocol version from {@code X-A2A-Version} header</li>
- *   <li>Required extensions from {@code X-A2A-Extensions} header</li>
+ *   <li>A2A protocol version from {@code A2A-Version} header</li>
+ *   <li>Required extensions from {@code A2A-Extensions} header</li>
  *   <li>Response observer for gRPC streaming</li>
  * </ul>
  *

transport/grpc/src/main/java/io/a2a/transport/grpc/handler/GrpcHandler.java

@@ -600,8 +600,8 @@ public void deleteTaskPushNotificationConfig(io.a2a.grpc.DeleteTaskPushNotificat
      *   <li>HTTP headers extracted from metadata</li>
      *   <li>gRPC method name</li>
      *   <li>Peer information (client connection details)</li>
-     *   <li>A2A protocol version from {@code X-A2A-Version} header (via context)</li>
-     *   <li>Required extensions from {@code X-A2A-Extensions} header (via context)</li>
+     *   <li>A2A protocol version from {@code A2A-Version} header (via context)</li>
+     *   <li>Required extensions from {@code A2A-Extensions} header (via context)</li>
      * </ul>
      *
      * <p><b>Custom Context Creation:</b>
@@ -901,7 +901,7 @@ public static void setStreamingSubscribedRunnable(Runnable runnable) {
     protected abstract Executor getExecutor();
 
     /**
-     * Attempts to extract the X-A2A-Version header from the current gRPC context.
+     * Attempts to extract the A2A-Version header from the current gRPC context.
      * This will only work if a server interceptor has been configured to capture
      * the metadata and store it in the context.
      *
@@ -917,7 +917,7 @@ public static void setStreamingSubscribedRunnable(Runnable runnable) {
     }
 
     /**
-     * Attempts to extract the X-A2A-Extensions header from the current gRPC context.
+     * Attempts to extract the A2A-Extensions header from the current gRPC context.
      * This will only work if a server interceptor has been configured to capture
      * the metadata and store it in the context.
      *