feat: add state bag and ServerCallContextBuilder to ServerCallContext by ikubicki · Pull Request #364 · a2aproject/a2a-js

ikubicki · 2026-03-19T14:53:22Z

Description

Motivation

The Python A2A SDK exposes a state property
on ServerCallContext
— an arbitrary MutableMapping[str, Any] used to pass metadata through the call pipeline.
The Python app layer actively uses it (e.g.
call_context.state['method'] = method),
and op-SDK implementations rely on it to carry request-scoped data such as tenant IDs,
auth tokens, or raw headers.

The TypeScript SDK was missing this capability, making it impossible to faithfully port
Python-based agent implementations to TypeScript without architectural workarounds.

Changes

`ServerCallContext`

Added a state property — a Map<string, unknown> key/value bag, directly mirroring
Python's state: MutableMapping[str, Any].
Added withRequestedExtensions() method that returns a new context with updated extensions
while preserving user, state, and activatedExtensions.
Extended the constructor to accept an optional state map.

`ServerCallContextBuilder`

Added ServerCallContextBuilder factory function type, mirroring Python's abstract
CallContextBuilder.build(request) pattern.
Added defaultServerCallContextBuilder — the default implementation that pre-populates
state with raw request headers under the headers key, mirroring Python's
DefaultCallContextBuilder.
Added STATE_HEADERS_KEY constant for the headers key.
Added RequestHeaders type — transport-agnostic representation of request headers.

Express handlers (`jsonRpcHandler`, `restHandler`)

Added optional contextBuilder?: ServerCallContextBuilder to JsonRpcHandlerOptions
and RestHandlerOptions, falling back to defaultServerCallContextBuilder.
Both handlers now pass raw req.headers into the context builder.

gRPC handler

Updated grpc_service.ts to pass request metadata as headers into the context builder.

Exports

ServerCallContextBuilder, RequestHeaders, defaultServerCallContextBuilder,
and STATE_HEADERS_KEY are now exported from @a2a-js/sdk/server.

Tests & samples

Added unit tests for the new ServerCallContext API in test/server/context.spec.ts.
Added src/samples/authentication/server_call_context.ts demonstrating custom context usage.

Impact

This change enables direct migration of Python A2A agent implementations to TypeScript —
any code relying on context.state in the Python SDK will have a direct equivalent in the
TypeScript SDK with the same semantics.

Checklist

Follow the CONTRIBUTING Guide.
Make your Pull Request title in the https://www.conventionalcommits.org/ specification.
Ensure the tests and linter pass
Appropriate docs were updated (if necessary)

gemini-code-assist · 2026-03-19T14:53:47Z

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a state bag to the TypeScript A2A SDK's ServerCallContext, enabling the passing of request-scoped metadata throughout the call pipeline. This change directly addresses a capability gap compared to the Python A2A SDK, allowing for a more faithful and straightforward migration of Python-based agent implementations to TypeScript by providing an equivalent mechanism for handling data like tenant IDs or auth tokens. It provides flexibility for custom context creation and ensures header information is readily available.

Highlights

ServerCallContext Enhanced: Introduced a state property (a Map<string, unknown>) to ServerCallContext for passing arbitrary request-scoped metadata, directly mirroring the Python SDK's state functionality.
Context Builder Introduced: Added a ServerCallContextBuilder type and a defaultServerCallContextBuilder function to allow for custom context creation and pre-population of the state bag with raw request headers.
Handler Integration: Express (jsonRpcHandler, restHandler) and gRPC handlers were updated to accept an optional contextBuilder and now pass raw request headers (or gRPC metadata converted to headers) to it for context creation.
New Sample and Tests: Included a new sample demonstrating custom context usage for reading request headers and added comprehensive unit tests for the new ServerCallContext API and defaultServerCallContextBuilder.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

github-actions · 2026-03-19T14:54:23Z

🧪 Code Coverage

⬇️ Download Full Report

	Base	PR	Delta
src/server/express/json_rpc_handler.ts	94.56%	94.68%	🟢 +0.12%
src/server/express/rest_handler.ts	84.58%	84.69%	🟢 +0.11%
src/server/grpc/grpc_service.ts	81.12%	82.62%	🟢 +1.50%
src/server/request_handler/default_request_handler.ts	81.45%	81.29%	🔴 -0.16%
Total	87.83%	87.96%	🟢 +0.13%

Generated by coverage-comment.yml

gemini-code-assist

Code Review

The pull request introduces a state property to ServerCallContext and a ServerCallContextBuilder pattern, effectively mirroring the Python A2A SDK's capabilities. The implementation is robust, including a default builder that populates request headers into the state, and a withRequestedExtensions method that correctly handles context immutability. The changes are well-integrated into existing Express and gRPC handlers, and the new sample and comprehensive unit tests demonstrate and validate the new functionality. The code quality is high, and the changes align perfectly with the stated motivation and objectives.

ikubicki · 2026-04-13T14:59:30Z

Friendly ping — this has been open for ~4 weeks with passing CI and positive review. Would love any feedback or a merge timeline if this fits the roadmap.

ishymko · 2026-04-17T08:17:25Z

Hi @ikubicki, thanks for the ping, we're currently working on 1.0 spec support (#321) and unfortunately don't have bandwidth for anything else, it's unlikely that we'll be able to incorporate this change in 0.3.x version, but we'll consider it for 1.0 as it's indeed a difference with Python you called out in the description.

Could you please file an issue describing the problem? We'll link it to 1.0 milestone. For now rebasing this PR into 1.0 dev branch is a bit early as things may change there still, but we'll ping you once it's possible.

Thank you!

ikubicki · 2026-04-17T11:13:46Z

Thank you @ishymko
I have created an issue: #416
I will keep an eye out for a stable spec 1.0 version

ishymko · 2026-05-12T07:13:50Z

Hey @ikubicki, we've just pushed 1.0 alpha version available under next npm tag.

Could you please rebase your PR onto epic/1.0_breaking_changes branch (which is a 1.0 dev branch)?

- Fix context.spec.ts to use new ServerCallContext options object constructor - Fix server_call_context.ts sample: constructor, Message.parts format, AgentSkill.securityRequirements, AgentCard.supportedInterfaces - Fix rest_handler.ts: add 'as string' casts for Express 5 req.params typing - Install jose dependency for signature module

…handler

…enant params Builder teraz dostaje wszystkie dane potrzebne do zbudowania kompletnego ServerCallContext - eliminuje dwuetapowy wzorzec create-base-then-overlay we wszystkich handlerach (JSONRPC, REST, gRPC).

…sitional args Introduces ServerCallContextBuilderOptions interface - rozszerzalne bez breaking change, spójne z ServerCallContextOptions.

ikubicki · 2026-05-12T15:09:13Z

@ishymko done :)

ikubicki requested a review from a team as a code owner March 19, 2026 14:53

gemini-code-assist Bot reviewed Mar 19, 2026

View reviewed changes

ikubicki force-pushed the feat/server-call-context-engancements branch from 87c04bd to 1a25ae6 Compare March 21, 2026 22:46

ikubicki force-pushed the feat/server-call-context-engancements branch from 1a25ae6 to c612394 Compare April 13, 2026 14:53

ikubicki mentioned this pull request Apr 17, 2026

[Bug]: ServerCallContext is missing state bag and CallContextBuilder — parity gap with Python SDK #416

Open

1 task

ikubicki force-pushed the feat/server-call-context-engancements branch from c612394 to ce8c2fe Compare May 12, 2026 10:48

ikubicki marked this pull request as draft May 12, 2026 10:59

ikubicki changed the base branch from main to epic/1.0_breaking_changes May 12, 2026 10:59

ikubicki force-pushed the feat/server-call-context-engancements branch from ce8c2fe to f6e636d Compare May 12, 2026 12:47

ikubicki added 5 commits May 12, 2026 14:54

fix: remove unused buildContext helpers in grpc_service and json_rpc_…

77b499f

…handler

fix: restore contextBuilder support in grpc_service _buildContext

1b620b3

refactor: extend ServerCallContextBuilder with requestedVersion and t…

44d87ae

…enant params Builder teraz dostaje wszystkie dane potrzebne do zbudowania kompletnego ServerCallContext - eliminuje dwuetapowy wzorzec create-base-then-overlay we wszystkich handlerach (JSONRPC, REST, gRPC).

refactor: ServerCallContextBuilder takes options object instead of po…

34f5223

…sitional args Introduces ServerCallContextBuilderOptions interface - rozszerzalne bez breaking change, spójne z ServerCallContextOptions.

fix: update sample curl commands to use SendMessage method name

c46cb29

ikubicki marked this pull request as ready for review May 12, 2026 14:52

test: extend context.spec.ts with tenant and requestedVersion coverage

56c8351

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add state bag and ServerCallContextBuilder to ServerCallContext#364

feat: add state bag and ServerCallContextBuilder to ServerCallContext#364
ikubicki wants to merge 7 commits into
a2aproject:epic/1.0_breaking_changesfrom
ikubicki:feat/server-call-context-engancements

ikubicki commented Mar 19, 2026 •

edited

Loading

Uh oh!

gemini-code-assist Bot commented Mar 19, 2026

Uh oh!

github-actions Bot commented Mar 19, 2026 •

edited

Loading

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

ikubicki commented Apr 13, 2026

Uh oh!

ishymko commented Apr 17, 2026

Uh oh!

ikubicki commented Apr 17, 2026

Uh oh!

ishymko commented May 12, 2026

Uh oh!

ikubicki commented May 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

ikubicki commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation

Changes

ServerCallContext

ServerCallContextBuilder

Express handlers (jsonRpcHandler, restHandler)

gRPC handler

Exports

Tests & samples

Impact

Checklist

Uh oh!

gemini-code-assist Bot commented Mar 19, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

github-actions Bot commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🧪 Code Coverage

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

ikubicki commented Apr 13, 2026

Uh oh!

ishymko commented Apr 17, 2026

Uh oh!

ikubicki commented Apr 17, 2026

Uh oh!

ishymko commented May 12, 2026

Uh oh!

ikubicki commented May 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ikubicki commented Mar 19, 2026 •

edited

Loading

`ServerCallContext`

`ServerCallContextBuilder`

Express handlers (`jsonRpcHandler`, `restHandler`)

github-actions Bot commented Mar 19, 2026 •

edited

Loading