fix!: use ProtoJSON for REST transport by guglielmo-san · Pull Request #292 · a2aproject/a2a-js

guglielmo-san · 2026-01-09T14:53:56Z

Description

This PR resolves an incompatibility in the payload shape between the REST Transport handlers and other A2A SDKs.

In this version, the transmitted payload now aligns with the field names and structure defined in the proto file. A new a2a.ts file has been introduced to represent the proto types, including their corresponding fromJson and toJson conversion functions.

Technically this is a breaking change, however current implementation isn't compatible with other official SDKs, so fixing in-place. Current situation with JSON format for HTTP+JSON is complicated as there is no explicit specification in 0.3, see here for more details.

Fixes #291 🦕

Release-As: 0.3.8

gemini-code-assist · 2026-01-09T14:54:45Z

Summary of Changes

Hello @guglielmo-san, 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 significantly updates the data handling within the REST transport layer by migrating to Protocol Buffer generated types. This change aims to enhance data consistency and interoperability across the system by enforcing a structured data format for all API interactions. The implementation includes comprehensive conversion mechanisms to ensure compatibility between the existing application logic and the new protobuf structures.

Highlights

Protocol Buffer Integration: The REST transport layer has been refactored to utilize Protocol Buffer (proto) generated types for API requests and responses, standardizing data structures.
New Dependencies and Build Steps: New dependencies for protobuf generation and handling (ts-proto, @bufbuild/buf, @bufbuild/protobuf, google-proto-files) have been added, along with new npm scripts to automate proto type generation.
Breaking Change: This pull request introduces a breaking change due to the direct use of proto types in the REST transport handler, requiring updates to how data is sent and received.
Conversion Utilities: New utility modules (FromProto, ToProto, id_decoding) have been introduced to facilitate seamless conversion between existing internal data models and the new proto types.
Updated API Handlers and Tests: Both client-side (rest_transport.ts) and server-side (rest_handler.ts) API handlers, along with their respective tests, have been updated to incorporate the new proto types and conversion logic.

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.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

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-01-09T14:55:09Z

🧪 Code Coverage

⬇️ Download Full Report

	Main	PR	Delta
src/client/transports/rest_transport.ts	84.52%	85.8%	🟢 +1.28%
src/server/express/rest_handler.ts	83.71%	85.76%	🟢 +2.05%
src/types/converters/from_proto.ts (new)	—	51.27%	—
src/types/converters/id_decoding.ts (new)	—	52%	—
src/types/converters/to_proto.ts (new)	—	49.28%	—
Total	82.74%	76.12%	🔴 -6.62%

Generated by coverage-comment.yml

gemini-code-assist

Code Review

This pull request is a significant and well-executed refactoring to adopt Protobuf-generated types for the REST transport layer. This is a great improvement for type safety and consistency across the client and server. The changes are comprehensive, touching the client transport, server handler, and updating tests accordingly. I've identified a few minor issues, including a potential runtime error from a missing type cast, a duplicated test assertion, a method name typo, and an incorrect path in a build script. Overall, this is a high-quality contribution.

src/server/express/rest_handler.ts

package.json

src/client/transports/rest_transport.ts

src/types/utils/from_proto.ts

test/server/express/rest_handler.spec.ts

guglielmo-san · 2026-01-12T10:19:56Z

/gemini review

gemini-code-assist

Code Review

This pull request successfully refactors the REST transport to use Protobuf-generated types, which is a significant improvement for ensuring payload compatibility with other A2A SDKs. The introduction of ToProto and FromProto utility classes is a good design choice for centralizing the conversion logic. The changes are consistently applied across both client and server implementations, and the tests have been largely updated to reflect this.

I've identified a few areas for improvement, mainly concerning test correctness and a small opportunity for code deduplication to enhance maintainability. My specific comments are detailed below.

src/server/express/rest_handler.ts

test/e2e.spec.ts

test/server/express/rest_handler.spec.ts

…ation and deserialization

src/client/transports/rest_transport.ts

src/server/express/rest_handler.ts

src/types/converters/from_proto.ts

vitest.config.ts

test/e2e.spec.ts

src/server/express/rest_handler.ts

test/e2e.spec.ts

… utility

# Description Bring back TCK capabilities tests for REST and use [0.3.0.beta3](https://github.com/a2aproject/a2a-tck/releases/tag/0.3.0.beta3) tag, both work now after #292.

🤖 I have created a release *beep* *boop* --- ## [0.3.8](v0.3.7...v0.3.8) (2026-01-15) ### ⚠ BREAKING CHANGES * use ProtoJSON for REST transport ([#292](#292)) ### Features * use case-insensitive transport protocol name comparison in ClientFactory ([5246067](5246067)) ### Bug Fixes * add typesVersions to support legacy module resolution ([#288](#288)) ([6499e29](6499e29)) * use ProtoJSON for REST transport ([#292](#292)) ([d2efc4c](d2efc4c)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please).

Apparently the code removed in #346 wasn't "dead", this method was missed in #292.

…352) Apparently the code removed in #346 wasn't "dead", this method wasn't properly migrated in #292. Tests are updated to cover this. Fixes #336

…2aproject#352) Apparently the code removed in a2aproject#346 wasn't "dead", this method wasn't properly migrated in a2aproject#292. Tests are updated to cover this. Fixes a2aproject#336

guglielmo-san added 12 commits January 8, 2026 10:52

first commit

e009c70

wip

12df166

remove files

0772ae7

wip

79c597f

wip

1e4a76b

wip

4d0f893

wip

81dbf04

wip

ea9b8f5

wip

42fabfb

wip

ee673f2

wip

45be53b

wip

abb0073

guglielmo-san changed the title ~~!feat: Adapt Rest Transport to use the proto generated types~~ feat: Adapt Rest Transport to use the proto generated types Jan 9, 2026

gemini-code-assist bot reviewed Jan 9, 2026

View reviewed changes

guglielmo-san added 9 commits January 9, 2026 15:40

wip

a4a6271

wip

b3d9fbe

fix typo

f7f9a4b

Merge branch 'main' into fix_rest

cecbc9c

fix lint

ebc0c55

wip

2d65891

fix tck test

1ae80be

fix test

9a806da

fix tck tests

8f11bcf

gemini-code-assist bot reviewed Jan 12, 2026

View reviewed changes

src/server/express/rest_handler.ts Show resolved Hide resolved

test/e2e.spec.ts Outdated Show resolved Hide resolved

test/server/express/rest_handler.spec.ts Show resolved Hide resolved

guglielmo-san requested a review from ishymko January 12, 2026 10:26

guglielmo-san marked this pull request as ready for review January 12, 2026 10:26

guglielmo-san requested a review from a team as a code owner January 12, 2026 10:26

guglielmo-san added 3 commits January 12, 2026 15:54

regenerate package-lock

39795d2

fix: update RestTransport to use direct class references for serializ…

2800ff1

…ation and deserialization

rename folders

1dbfdf6

guglielmo-san requested a review from ishymko January 12, 2026 16:23

rename folders

e86fc27

ishymko reviewed Jan 13, 2026

View reviewed changes

guglielmo-san added 2 commits January 13, 2026 11:07

fix comment suggestions

f17d9d2

fix test

de78a6a

guglielmo-san requested a review from ishymko January 13, 2026 11:32

guglielmo-san added 4 commits January 13, 2026 11:42

fix sanitize

4eb1fb1

update generated types

483ee55

Merge branch 'main' into fix_rest

f56dc6c

run linter

85b7e6a

ishymko approved these changes Jan 13, 2026

View reviewed changes

test/e2e.spec.ts Outdated Show resolved Hide resolved

refactor: replace custom sanitize function with removeUndefinedFields…

20750cb

… utility

guglielmo-san enabled auto-merge (squash) January 13, 2026 17:08

guglielmo-san merged commit d2efc4c into a2aproject:main Jan 13, 2026
14 checks passed

guglielmo-san deleted the fix_rest branch January 13, 2026 17:08

a2a-bot mentioned this pull request Jan 13, 2026

chore(main): release 0.3.8 #283

Merged

ishymko mentioned this pull request Jan 14, 2026

ci: run TCK capabilities tests for REST #296

Merged

ishymko mentioned this pull request Feb 11, 2026

[Task]: 1.0: Use types generated from protos instead of types.ts #322

Open

ishymko added a commit that referenced this pull request Mar 13, 2026

fix: properly parse ProtoJSON body for POST pushNotificationConfigs

f3d7188

Apparently the code removed in #346 wasn't "dead", this method was missed in #292.

ishymko mentioned this pull request Mar 13, 2026

fix: properly parse ProtoJSON body for POST pushNotificationConfigs #352

Merged

ishymko added a commit that referenced this pull request Mar 13, 2026

fix: properly parse ProtoJSON body for POST pushNotificationConfigs

5c0a1a8

Apparently the code removed in #346 wasn't "dead", this method was missed in #292.

ishymko added a commit that referenced this pull request Mar 13, 2026

fix: properly parse ProtoJSON body for POST pushNotificationConfigs

d01ab3a

Apparently the code removed in #346 wasn't "dead", this method was missed in #292.

ishymko added a commit that referenced this pull request Mar 13, 2026

fix: properly parse ProtoJSON body for POST pushNotificationConfigs

8937790

Apparently the code removed in #346 wasn't "dead", this method was missed in #292.

Conversation

guglielmo-san commented Jan 9, 2026 • edited by ishymko Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

gemini-code-assist bot commented Jan 9, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

github-actions bot commented Jan 9, 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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

guglielmo-san commented Jan 12, 2026

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

guglielmo-san commented Jan 9, 2026 •

edited by ishymko

Loading

github-actions bot commented Jan 9, 2026 •

edited

Loading