What happened?
Problem
The TypeScript A2A SDK's ServerCallContext lacks a state property that exists in the Python SDK. This creates a fundamental feature gap that makes it impossible to faithfully port Python-based agent implementations to TypeScript without architectural workarounds.
The Python SDK's ServerCallContext exposes a state: MutableMapping[str, Any] — an arbitrary key/value bag used to pass request-scoped metadata through the call pipeline. The Python app layer actively relies on it (e.g. call_context.state['method'] = method), and downstream implementations use it to carry data like tenant IDs, auth tokens, or raw request headers.
The TypeScript SDK has no equivalent.
Impact
Any agent or middleware relying on context.state in the Python SDK has no direct equivalent in TypeScript. Developers migrating Python agents to TypeScript must invent their own out-of-band solutions (e.g. request-scoped stores, middleware globals), which undermines SDK consistency and increases migration friction.
Proposed Solution
Add the following to ServerCallContext in the TypeScript SDK:
- A
state property — a Map<string, unknown> key/value bag, mirroring Python's state: MutableMapping[str, Any]
- A
ServerCallContextBuilder type — mirroring Python's abstract CallContextBuilder.build(request) pattern
- A
defaultServerCallContextBuilder — a default implementation that pre-populates state with raw request headers (mirroring Python's DefaultCallContextBuilder)
- Optional
contextBuilder parameter on Express (jsonRpcHandler, restHandler) and gRPC handlers, falling back to the default builder
References
Relevant log output
Code of Conduct
What happened?
Problem
The TypeScript A2A SDK's
ServerCallContextlacks astateproperty that exists in the Python SDK. This creates a fundamental feature gap that makes it impossible to faithfully port Python-based agent implementations to TypeScript without architectural workarounds.The Python SDK's
ServerCallContextexposes astate: MutableMapping[str, Any]— an arbitrary key/value bag used to pass request-scoped metadata through the call pipeline. The Python app layer actively relies on it (e.g.call_context.state['method'] = method), and downstream implementations use it to carry data like tenant IDs, auth tokens, or raw request headers.The TypeScript SDK has no equivalent.
Impact
Any agent or middleware relying on
context.statein the Python SDK has no direct equivalent in TypeScript. Developers migrating Python agents to TypeScript must invent their own out-of-band solutions (e.g. request-scoped stores, middleware globals), which undermines SDK consistency and increases migration friction.Proposed Solution
Add the following to
ServerCallContextin the TypeScript SDK:stateproperty — aMap<string, unknown>key/value bag, mirroring Python'sstate: MutableMapping[str, Any]ServerCallContextBuildertype — mirroring Python's abstractCallContextBuilder.build(request)patterndefaultServerCallContextBuilder— a default implementation that pre-populatesstatewith raw request headers (mirroring Python'sDefaultCallContextBuilder)contextBuilderparameter on Express (jsonRpcHandler,restHandler) and gRPC handlers, falling back to the default builderReferences
ServerCallContext: https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/context.pyDefaultCallContextBuilder: https://github.com/a2aproject/a2a-python/blob/main/src/a2a/server/apps/jsonrpc/jsonrpc_app.pyRelevant log output
Code of Conduct