feat(server): expose SendMessageRequest metadata to AgentExecutor via RequestContext

The A2A specification defines SendMessageRequest.metadata as 'a flexible
key-value map for passing additional context or parameters', and the
extension mechanism encourages carrying extension data in request metadata.
DefaultRequestHandler previously dropped this field before invoking the
AgentExecutor, leaving server-side agents no way to read it.

RequestContext gains an optional readonly metadata property, threaded from
params.metadata in both sendMessage and sendMessageStream. Existing
RequestContext call sites are unaffected (new trailing optional parameter).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: boblangley

src/server/agent_execution/request_context.ts

@@ -8,20 +8,29 @@ export class RequestContext {
   public readonly task?: Task;
   public readonly referenceTasks?: Task[];
   public readonly context: ServerCallContext;
+  /**
+   * The request-level metadata from the originating `SendMessageRequest`,
+   * when provided. This is the spec's "flexible key-value map for passing
+   * additional context or parameters" and is distinct from
+   * `userMessage.metadata`.
+   */
+  public readonly metadata?: Record<string, unknown>;
 
   constructor(
     userMessage: Message,
     taskId: string,
     contextId: string,
     context: ServerCallContext,
     task?: Task,
-    referenceTasks?: Task[]
+    referenceTasks?: Task[],
+    metadata?: Record<string, unknown>
   ) {
     this.userMessage = userMessage;
     this.taskId = taskId;
     this.contextId = contextId;
     this.context = context;
     this.task = task;
     this.referenceTasks = referenceTasks;
+    this.metadata = metadata;
   }
 }

src/server/request_handler/default_request_handler.ts

@@ -143,7 +143,8 @@ export class DefaultRequestHandler implements A2ARequestHandler {
 
   private async _createRequestContext(
     incomingMessage: Message,
-    context: ServerCallContext
+    context: ServerCallContext,
+    requestMetadata?: Record<string, unknown>
   ): Promise<RequestContext> {
     let task: Task | undefined;
     let referenceTasks: Task[] | undefined;
@@ -220,7 +221,15 @@ export class DefaultRequestHandler implements A2ARequestHandler {
       contextId,
       taskId,
     };
-    return new RequestContext(messageForContext, taskId, contextId, context, task, referenceTasks);
+    return new RequestContext(
+      messageForContext,
+      taskId,
+      contextId,
+      context,
+      task,
+      referenceTasks,
+      requestMetadata
+    );
   }
 
   private async _processEvents(
@@ -558,7 +567,11 @@ export class DefaultRequestHandler implements A2ARequestHandler {
     const resultManager = new ResultManager(this.taskStore, context);
     resultManager.setContext(incomingMessage);
 
-    const requestContext = await this._createRequestContext(incomingMessage, context);
+    const requestContext = await this._createRequestContext(
+      incomingMessage,
+      context,
+      params.metadata
+    );
     const taskId = requestContext.taskId;
     const finalMessageForAgent = requestContext.userMessage;
 
@@ -652,7 +665,11 @@ export class DefaultRequestHandler implements A2ARequestHandler {
     const resultManager = new ResultManager(this.taskStore, context);
     resultManager.setContext(incomingMessage);
 
-    const requestContext = await this._createRequestContext(incomingMessage, context);
+    const requestContext = await this._createRequestContext(
+      incomingMessage,
+      context,
+      params.metadata
+    );
     const taskId = requestContext.taskId;
 
     const eventBus = this.eventBusManager.createOrGetByTaskId(taskId);

test/server/default_request_handler.spec.ts

@@ -3543,6 +3543,130 @@ describe('DefaultRequestHandler as A2ARequestHandler', () => {
     expect(capturedRequestContext?.context?.user).to.be.an.instanceOf(UnauthenticatedUser);
   });
 
+  it('should expose SendMessageRequest metadata to agentExecutor via RequestContext', async () => {
+    const requestMetadata = {
+      'a2a-service-parameters': { 'A2A-Extensions': 'https://example.com/extensions/sample/v1' },
+      traceId: 'trace-123',
+    };
+
+    const params: SendMessageRequest = {
+      tenant: '',
+      metadata: requestMetadata,
+      configuration: undefined,
+      message: {
+        messageId: 'msg-request-metadata',
+        role: Role.ROLE_USER,
+        parts: [
+          {
+            content: { $case: 'text', value: 'Verify request metadata.' },
+            filename: '',
+            mediaType: 'text/plain',
+            metadata: undefined,
+          },
+        ],
+        contextId: 'metadata-context-id',
+        taskId: '',
+        extensions: [],
+        referenceTaskIds: [],
+        metadata: {},
+      },
+    };
+
+    let capturedRequestContext: RequestContext | undefined;
+    (mockAgentExecutor.execute as unknown as Mock).mockImplementation(
+      async (ctx: RequestContext, bus: ExecutionEventBus) => {
+        capturedRequestContext = ctx;
+        bus.publish(
+          AgentEvent.task({
+            id: ctx.taskId,
+            contextId: ctx.contextId,
+            status: {
+              state: TaskState.TASK_STATE_COMPLETED,
+              message: undefined,
+              timestamp: undefined,
+            },
+            artifacts: [],
+            history: [],
+            metadata: {},
+          })
+        );
+        bus.finished();
+      }
+    );
+
+    await handler.sendMessage(params, serverCallContext);
+    expect(capturedRequestContext?.metadata).to.deep.equal(
+      requestMetadata,
+      'sendMessage should thread request metadata into RequestContext'
+    );
+
+    capturedRequestContext = undefined;
+    const streamParams: SendMessageRequest = {
+      ...params,
+      message: { ...params.message!, messageId: 'msg-request-metadata-stream' },
+    };
+    for await (const event of handler.sendMessageStream(streamParams, serverCallContext)) {
+      void event; // drain the stream
+    }
+    expect(capturedRequestContext?.metadata).to.deep.equal(
+      requestMetadata,
+      'sendMessageStream should thread request metadata into RequestContext'
+    );
+  });
+
+  it('should leave RequestContext metadata undefined when the request carries none', async () => {
+    const params: SendMessageRequest = {
+      tenant: '',
+      metadata: undefined,
+      configuration: undefined,
+      message: {
+        messageId: 'msg-no-request-metadata',
+        role: Role.ROLE_USER,
+        parts: [
+          {
+            content: { $case: 'text', value: 'No request metadata.' },
+            filename: '',
+            mediaType: 'text/plain',
+            metadata: undefined,
+          },
+        ],
+        contextId: 'no-metadata-context-id',
+        taskId: '',
+        extensions: [],
+        referenceTaskIds: [],
+        metadata: {},
+      },
+    };
+
+    let capturedRequestContext: RequestContext | undefined;
+    (mockAgentExecutor.execute as unknown as Mock).mockImplementation(
+      async (ctx: RequestContext, bus: ExecutionEventBus) => {
+        capturedRequestContext = ctx;
+        bus.publish(
+          AgentEvent.task({
+            id: ctx.taskId,
+            contextId: ctx.contextId,
+            status: {
+              state: TaskState.TASK_STATE_COMPLETED,
+              message: undefined,
+              timestamp: undefined,
+            },
+            artifacts: [],
+            history: [],
+            metadata: {},
+          })
+        );
+        bus.finished();
+      }
+    );
+
+    await handler.sendMessage(params, serverCallContext);
+    expect(capturedRequestContext?.metadata).to.equal(
+      undefined,
+      'RequestContext metadata should be undefined when the request has none'
+    );
+  });
+
   describe('getAuthenticatedExtendedAgentCard tests', async () => {
     class A2AUser implements User {
       constructor(private _isAuthenticated: boolean) {}