feat: support metadata providers for remote A2A messages

Author: YuqiGuo105

a2a/src/main/java/com/google/adk/a2a/agent/A2ARequestMetadataProvider.java

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.google.adk.a2a.agent;
+
+import com.google.adk.agents.InvocationContext;
+import io.a2a.spec.Message;
+import java.util.Map;
+import org.jspecify.annotations.Nullable;
+
+/** Supplies application-selected metadata for an outgoing A2A message. */
+@FunctionalInterface
+public interface A2ARequestMetadataProvider {
+
+  /**
+   * Returns JSON-serializable metadata after the message's parts and identifiers have been set.
+   * Returning {@code null} leaves the message unchanged. An exception aborts sending the message.
+   *
+   * <p>The result is attached to {@link Message#getMetadata()}, not request-level metadata or
+   * authentication headers. On an ADK receiver it is available through the incoming A2A message; it
+   * is not automatically copied into session state or {@code RunConfig.customMetadata()}.
+   */
+  @Nullable Map<String, Object> provide(
+      InvocationContext invocationContext, Message outgoingMessage);
+}

a2a/src/main/java/com/google/adk/a2a/agent/RemoteA2AAgent.java

@@ -49,7 +49,9 @@
 import io.reactivex.rxjava3.core.Flowable;
 import io.reactivex.rxjava3.core.FlowableEmitter;
 import java.util.ArrayList;
+import java.util.LinkedHashMap;
 import java.util.List;
+import java.util.Map;
 import java.util.Objects;
 import java.util.Optional;
 import java.util.function.BiConsumer;
@@ -84,6 +86,7 @@ public class RemoteA2AAgent extends BaseAgent {
   private final Client a2aClient;
   private String description;
   private final boolean streaming;
+  private final @Nullable A2ARequestMetadataProvider requestMetadataProvider;
 
   // Internal constructor used by builder
   private RemoteA2AAgent(Builder builder) {
@@ -117,6 +120,7 @@ private RemoteA2AAgent(Builder builder) {
       this.description = this.agentCard.description();
     }
     this.streaming = builder.streaming && this.agentCard.capabilities().streaming();
+    this.requestMetadataProvider = builder.requestMetadataProvider;
   }
 
   public static Builder builder() {
@@ -133,6 +137,7 @@ public static class Builder {
     private List<Callbacks.BeforeAgentCallback> beforeAgentCallback;
     private List<Callbacks.AfterAgentCallback> afterAgentCallback;
     private boolean streaming;
+    private @Nullable A2ARequestMetadataProvider requestMetadataProvider;
 
     @CanIgnoreReturnValue
     public Builder streaming(boolean streaming) {
@@ -182,6 +187,16 @@ public Builder a2aClient(Client a2aClient) {
       return this;
     }
 
+    /**
+     * Sets an optional provider called once for each outgoing message, after its parts and
+     * identifiers have been populated. Session state is never forwarded automatically.
+     */
+    @CanIgnoreReturnValue
+    public Builder requestMetadataProvider(@Nullable A2ARequestMetadataProvider provider) {
+      this.requestMetadataProvider = provider;
+      return this;
+    }
+
     public RemoteA2AAgent build() {
       return new RemoteA2AAgent(this);
     }
@@ -198,19 +213,30 @@ private Message.Builder newA2AMessage(
 
   private Message prepareMessage(InvocationContext invocationContext) {
     Event userCall = EventConverter.findUserFunctionCall(invocationContext.session().events());
+    Message message;
     if (userCall != null) {
       ImmutableList<io.a2a.spec.Part<?>> parts =
           EventConverter.contentToParts(userCall.content(), userCall.partial().orElse(false));
-      return newA2AMessage(invocationContext, Message.Role.USER, parts)
-          .taskId(EventConverter.taskId(userCall))
-          .contextId(EventConverter.contextId(userCall))
-          .build();
+      message =
+          newA2AMessage(invocationContext, Message.Role.USER, parts)
+              .taskId(EventConverter.taskId(userCall))
+              .contextId(EventConverter.contextId(userCall))
+              .build();
+    } else {
+      message =
+          newA2AMessage(
+                  invocationContext,
+                  Message.Role.USER,
+                  EventConverter.messagePartsFromContext(invocationContext))
+              .build();
+    }
+    if (requestMetadataProvider == null) {
+      return message;
     }
-    return newA2AMessage(
-            invocationContext,
-            Message.Role.USER,
-            EventConverter.messagePartsFromContext(invocationContext))
-        .build();
+    Map<String, Object> metadata = requestMetadataProvider.provide(invocationContext, message);
+    return metadata == null
+        ? message
+        : new Message.Builder(message).metadata(new LinkedHashMap<>(metadata)).build();
   }
 
   @Override