feat(api)!: Update codebase to use only Proto based types by bartek-gralewicz · Pull Request #337 · a2aproject/a2a-js

bartek-gralewicz · 2026-02-20T14:05:49Z

Description

Updated the codebase to only use Proto based types and remove the old JSON types.ts completely.

This change unifies the usage of types with other SDKs and is part of the 1.0.0 scope. Equivalent PR on the Python SDK: a2aproject/a2a-python#572.

Important

This is a breaking change and therefore it is going to be merged into an epic v1.0 branch instead of main. Later 1.0 release will introduce this in the main branch.

…s file. Focused the solution on proto generated types information.

…me unit tests still failing.

gemini-code-assist · 2026-02-20T14:07:52Z

Summary of Changes

Hello @bartek-gralewicz, 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 completes a fundamental shift in the project's type management by fully adopting Protocol Buffers (Proto) as the canonical type system. This strategic move eliminates the previous JSON-schema-derived types, leading to a more unified and consistent type experience across the SDK, mirroring efforts in other language implementations. The changes span across the entire codebase, from core client and server logic to sample agents and utility functions, ensuring all components interact seamlessly with the new Proto-based data models.

Highlights

Type System Migration: The codebase has been fully migrated to use Proto-based types, replacing the legacy JSON types.ts file. This involves updating all relevant imports and type definitions across client, server, and sample code.
JSON-RPC Specific Types: A new file, src/json_rpc_types.ts, has been introduced to house types specific to the JSON-RPC protocol, ensuring a clear separation from the core Proto-generated types.
Message and Task Structure Updates: The internal structure of Message and Task objects has been updated to align with the new Proto definitions. This includes renaming the parts property to content within Message and removing the kind discriminator property from both Message and Task.
Converter Adjustments: The FromProto and ToProto conversion utilities have been refactored. FromProto now largely acts as an identity mapper for core Proto types, reflecting their new role as the source of truth, while still handling parameter extraction for JSON-RPC specific types. ToProto also primarily passes through Proto types or converts JSON-RPC specific types to their Proto equivalents.
Agent Executor and CLI Updates: Sample agent executors and the command-line interface (CLI) have been updated to reflect the new Proto-based TaskState and Role enums, and to correctly handle the revised Message and Task structures.

Changelog

src/a2a_response.ts
- Updated import path for JSON-RPC success responses.
src/client/card-resolver.ts
- Updated import path for AgentCard.
src/client/client.ts
- Updated import paths for various types
- Adjusted sendMessage and setTaskPushNotificationConfig calls with type assertions.
src/client/factory.ts
- Updated import path for AgentCard
- Added explicit 'any' type assertions for additionalInterfaces mapping.
src/client/interceptors.ts
- Updated import path for AgentCard and MessageSendParams.
src/client/multitransport-client.ts
- Updated import paths for various types
- Added type assertions for cancelTask and pushNotificationConfig assignments.
src/client/transports/grpc/grpc_transport.ts
- Updated import paths to use json_rpc_types.js for JSON-RPC specific types and a2a_types.js for core Task and AgentCard
- Modified setTaskPushNotificationConfig, getTaskPushNotificationConfig, and listTaskPushNotificationConfig to use JsonRpcTaskPushNotificationConfig and adjusted conversion logic.
src/client/transports/json_rpc_transport.ts
- Updated import paths to use index.js for all types
- Removed JSONRPCRequest import
- Introduced JsonRpcTaskPushNotificationConfig
- Added type assertions for various method return values and rpcRequest types
- Modified stream event processing to extract payload.value.
src/client/transports/rest/rest_transport.ts
- Updated import paths to use index.js for all types and JsonRpcTaskPushNotificationConfig
- Modified setTaskPushNotificationConfig, getTaskPushNotificationConfig, and listTaskPushNotificationConfig to use JsonRpcTaskPushNotificationConfig and adjusted conversion logic
- Updated normalizePart and normalizeMessage functions to handle new Proto-based Part and Message structures, including role mapping and content handling.
src/client/transports/transport.ts
- Updated import paths to use index.js for all types and JsonRpcTaskPushNotificationConfig
- Updated method signatures to use JsonRpcTaskPushNotificationConfig.
src/index.ts
- Modified exports to use types/pb/a2a_types.js for core types and json_rpc_types.js for JSON-RPC specific types, effectively replacing the old types.js export.
src/json_rpc_types.ts
- Added a new file defining JSON-RPC specific types, including error types, request/response interfaces, and parameter types, referencing Proto types where applicable.
src/samples/agents/movie-agent/index.ts
- Updated imports, removed TextPart import
- Adjusted Task, TaskStatusUpdateEvent, Artifact, Message, and Part object structures to align with Proto types, including TaskState and Role enums.
src/samples/agents/sample-agent/agent_executor.ts
- Updated imports, added TaskState and Role imports
- Adjusted Task, TaskStatusUpdateEvent, Artifact, and Message object structures to align with Proto types.
src/samples/agents/sample-agent/index.ts
- Updated AgentCard capabilities and added new fields to align with Proto AgentCard structure.
src/samples/authentication/agent_executor.ts
- Updated imports to include Role
- Adjusted Message structure.
src/samples/authentication/index.ts
- Updated AgentCard capabilities, security schemes, and added new fields to align with Proto AgentCard structure.
src/samples/cli.ts
- Updated imports to use TaskState and Role enums
- Modified printAgentEvent and printMessageContent functions to handle new Proto-based event and message structures
- Updated messagePayload creation to use Proto Message structure.
src/samples/extensions/extensions.ts
- Updated TaskStatusUpdateEvent import
- Adjusted timestampEvent to check for status.update.metadata.
src/samples/extensions/index.ts
- Updated AgentCard capabilities and added new fields to align with Proto AgentCard structure.
src/server/agent_execution/request_context.ts
- Updated imports for Message and Task.
src/server/error.ts
- Updated import for JSONRPCError to json_rpc_types.js.
src/server/events/execution_event_bus.ts
- Updated imports for Message, Task, TaskStatusUpdateEvent, and TaskArtifactUpdateEvent.
src/server/events/execution_event_queue.ts
- Updated TaskStatusUpdateEvent import
- Adjusted event kind checks.
src/server/express/agent_card_handler.ts
- Updated AgentCard import.
src/server/express/json_rpc_handler.ts
- Updated imports for JSON-RPC response types.
src/server/express/rest_handler.ts
- Updated imports for Message, Task, TaskArtifactUpdateEvent, and TaskStatusUpdateEvent
- Removed direct parsing of a2a.SendMessageRequest and FromProto.messageSendParams in message:send and message:stream endpoints.
src/server/push_notification/default_push_notification_sender.ts
- Updated imports for Task and PushNotificationConfig.
src/server/push_notification/push_notification_sender.ts
- Updated Task import.
src/server/push_notification/push_notification_store.ts
- Updated PushNotificationConfig import.
src/server/request_handler/a2a_request_handler.ts
- Updated imports for various types and JsonRpcTaskPushNotificationConfig
- Updated method signatures to use JsonRpcTaskPushNotificationConfig.
src/server/request_handler/default_request_handler.ts
- Updated imports for various types, Role, JsonRpcTaskPushNotificationConfig
- Adjusted terminalStates to use TaskState enum
- Updated logic for handling MessageSendParams and TaskStatusUpdateEvent to align with Proto structures
- Modified cancelTask and push notification handling.
src/server/result_manager.ts
- Updated imports for Message, Task, TaskArtifactUpdateEvent, and TaskStatusUpdateEvent
- Adjusted event kind checks and artifact handling to align with Proto structures.
src/server/store.ts
- Updated Task import.
src/server/transports/jsonrpc/jsonrpc_transport_handler.ts
- Updated imports for various types, StreamResponse, Message, Task, TaskStatusUpdateEvent, TaskArtifactUpdateEvent
- Adjusted stream event processing to map to StreamResponse payload.
src/server/transports/rest/rest_transport_handler.ts
- Updated imports for various types, Role, JsonRpcTaskPushNotificationConfig
- Refactored normalizePart, normalizeFile, normalizeMessage, normalizeMessageSendParams, and normalizeTaskPushNotificationConfig to handle new Proto structures and type conversions.
src/server/transports/rest/rest_types.ts
- Moved FileWithBytes and FileWithUri interfaces from types.js to this file.
src/server/utils.ts
- Updated imports for TaskStatus and Artifact.
src/types.ts
- Removed.
src/types/converters/from_proto.ts
- Updated imports to use json_rpc_types.js for JSON-RPC specific types
- Refactored all conversion methods to act as identity mappers for Proto types, or to extract parameters for JSON-RPC specific types.
src/types/converters/to_proto.ts
- Removed types.js import
- Refactored all conversion methods to act as identity mappers for Proto types, or to convert JSON-RPC specific types to Proto types
- Added extractTaskIdFromName helper.
tck/agent/index.ts
- Updated imports to include TaskState and Role
- Adjusted Task and TaskStatusUpdateEvent object structures.
test/client/card-resolver.spec.ts
- Updated AgentCard import
- Added missing AgentCard properties for mock data.
test/client/client.spec.ts
- Removed TextPart import
- Updated JSONRPCResponse import
- Added Role import
- Adjusted MessageSendParams and Task mock data to align with Proto structures
- Updated assertions for sendMessage results.
test/client/client_auth.spec.ts
- Updated SendMessageResponse import
- Adjusted assertions for sendMessage results.
test/client/factory.spec.ts
- Updated AgentCard import
- Added missing AgentCard properties for mock data.
test/client/multitransport-client.spec.ts
- Updated imports to include Role and TaskState
- Adjusted AgentCard, Message, Task, and TaskStatusUpdateEvent mock data to align with Proto structures.
test/client/transports/grpc/grpc_transport.spec.ts
- Added TaskState import
- Updated ToProto and FromProto mocks to include jsonRpcTaskPushNotificationConfig
- Adjusted createMockTask usage and mockConfig for push notifications.
test/client/transports/json_rpc_transport.spec.ts
- Removed TextPart import
- Added Role import
- Adjusted MessageSendParams mock data.
test/client/transports/rest/rest_transport.spec.ts
- Updated imports to include JsonRpcTaskPushNotificationConfig
- Adjusted createMockTask usage and mockConfig for push notifications
- Updated assertions for push notification config results.
test/client/util.ts
- Updated imports to include Role and TaskState
- Adjusted createMockAgentCard, createMockMessage, and createMockTask to align with Proto structures.
test/e2e.spec.ts
- Updated imports to include Role and TaskState
- Adjusted AgentCard, Task, and Message mock data to align with Proto structures.
test/server/default_request_handler.spec.ts
- Updated imports to include Role and JsonRpcTaskPushNotificationConfig
- Adjusted AgentCard, Message, Task, and TaskStatusUpdateEvent mock data to align with Proto structures
- Updated assertions and logic related to task states and messages.
test/server/execution_event_bus.spec.ts
- Updated imports to include Role
- Adjusted createMessage mock data.
test/server/express/a2a_express_app.spec.ts
- Updated JSONRPCSuccessResponse import to JSONRPCResponse
- Adjusted mock JSONRPCResponse result type.
test/server/express/rest_handler.spec.ts
- Updated imports to include Role and TaskState
- Adjusted AgentCard, Message, and Task mock data to align with Proto structures
- Updated assertions for push notification config results and message parsing.
test/server/grpc/from_proto.spec.ts
- Removed idDecoding and A2AError imports
- Simplified tests to reflect FromProto acting as an identity mapper for most types, while still testing parameter extraction for specific requests.
test/server/grpc/grpc_handler.spec.ts
- Updated imports to include Role and TaskState
- Adjusted AgentCard and Message mock data.
test/server/grpc/to_proto.spec.ts
- Removed types.js and A2AError imports
- Added generateTaskName mock
- Simplified tests to reflect ToProto acting as an identity mapper for most types.
test/server/jsonrpc_transport_handler.spec.ts
- Removed JSONRPCRequest import
- Adjusted mock request type.
test/server/mocks/agent-executor.mock.ts
- Updated imports to include TaskState
- Adjusted Task and TaskStatusUpdateEvent mock data to align with Proto structures.
test/server/push_notification_integration.spec.ts
- Updated imports to include Role, TaskState, TaskStatus, and JsonRpcTaskPushNotificationConfig
- Adjusted AgentCard, Message, PushNotificationConfig, and Task mock data to align with Proto structures
- Updated assertions for push notification content.

Activity

The pull request was opened by bartek-gralewicz.
The author states that this change is part of the 1.0 scope and aims to unify type usage with other SDKs, referencing a similar PR in the Python SDK.

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. ↩

…mini suggestion.

gemini-code-assist

Code Review

This pull request is a significant and impressive refactoring to unify the codebase on Protobuf-based types, removing the old JSON types. The changes are extensive, touching many files across the client and server implementations, but they are consistent and well-executed. The introduction of json_rpc_types.ts and the updates to the from_proto and to_proto converters are central to this effort and appear correct. The sample applications and tests have also been diligently updated to reflect these new types, which is great to see.

I have a couple of minor suggestions to improve code quality and consistency, but overall, this is a solid piece of work that moves the project in the right direction for type safety and cross-SDK compatibility.

src/client/transports/json_rpc_transport.ts

src/server/request_handler/default_request_handler.ts

github-actions · 2026-02-24T09:52:53Z

🧪 Code Coverage

⬇️ Download Full Report

	Main	PR	Delta
src/client/card-resolver.ts	96.82%	95.23%	🔴 -1.59%
src/client/client.ts	68.16%	64.1%	🔴 -4.06%
src/client/multitransport-client.ts	97.66%	97.72%	🟢 +0.06%
src/client/transports/grpc/grpc_transport.ts	93.92%	93.53%	🔴 -0.39%
src/client/transports/json_rpc_transport.ts	62.57%	68.55%	🟢 +5.98%
src/client/transports/rest_transport.ts	85.8%	86.68%	🟢 +0.88%
src/server/express/rest_handler.ts	85.76%	85.44%	🔴 -0.32%
src/server/push_notification/push_notification_store.ts	89.18%	83.78%	🔴 -5.40%
src/server/request_handler/default_request_handler.ts	79.69%	79.31%	🔴 -0.38%
src/server/result_manager.ts	61.7%	62.79%	🟢 +1.09%
src/server/transports/jsonrpc/jsonrpc_transport_handler.ts	76.68%	73.13%	🔴 -3.55%
src/server/transports/rest/rest_transport_handler.ts	98.78%	98.85%	🟢 +0.07%
src/types/converters/from_proto.ts	71.59%	66.66%	🔴 -4.93%
src/types/converters/id_decoding.ts	52%	76%	🟢 +24.00%
src/types/converters/to_proto.ts	69.38%	54.38%	🔴 -15.00%
src/json_rpc_types.ts (new)	—	0%	—
Total	80.84%	81.85%	🟢 +1.01%

Generated by coverage-comment.yml

src/samples/agents/movie-agent/index.ts

src/client/client.ts

src/client/transports/transport.ts

src/client/multitransport-client.ts

src/server/transports/rest/rest_transport_handler.ts

src/json_rpc_types.ts

…eir relevant locations. Resolved type issues after updating imports.

src/client/transports/grpc/grpc_transport.ts

src/client/transports/json_rpc_transport.ts

src/client/transports/rest_transport.ts

src/client/client.ts

src/server/events/execution_event_queue.ts

src/server/express/rest_handler.ts

src/server/request_handler/a2a_request_handler.ts

src/json_rpc_types.ts

Co-authored-by: Ivan Shymko <ishymko@google.com>

… into bgralewicz/proto_types

…pes and toJSON/fromJSON methods.

… methods remain for now as removing them would introduce other necessary changes.

ishymko

🚀

Updated the codebase to only use Proto based types and remove the old JSON types.ts completely. This change unifies the usage of types with other SDKs and is part of the 1.0.0 scope. Equivalent PR on the Python SDK: a2aproject/a2a-python#572. This is a breaking change and therefore it is going to be merged into an epic `v1.0` branch instead of `main`. Later 1.0 release will introduce this in the `main` branch. --------- Co-authored-by: Bartek Gralewicz <bgralewicz@google.com> Co-authored-by: Ivan Shymko <ishymko@google.com>

bartek-gralewicz added 8 commits February 19, 2026 14:32

Added new enums and applied them across the codebase. Removed types.t…

1fa50c8

…s file. Focused the solution on proto generated types information.

Apply further types changes. Resolve issues with missing structs.

e6276be

WIP: Updated types in the entire codebase. Needs revisiting due to so…

0bb1cdd

…me unit tests still failing.

Improved tests passing ratio for server unit tests.

a7512b1

Applied multiple fixes to default_request_handler tests.

c1a8ea0

Fixed all tests.

adc42f7

Resolve issues in default_request_handler.spec.ts.

38b67c9

Resolve all leftover build related issues.

d5d2983

This comment was marked as outdated.

Sign in to view

bartek-gralewicz added 8 commits February 20, 2026 14:22

Minor self-review cleanup and test restoring.

30cf6ae

Lint and formatting changes.

f4ae1b9

Code assist suggestions.

c9baa85

Gemini code review adaptations.

791e1e9

Remove unused imports.

92e43a3

Resolve lint issues in grpc_transport.ts.

12e18ae

Resolve current issues with failing unit tests.

d14babf

Resolve linter errors.

891b066

This comment was marked as outdated.

Sign in to view

Apply suggestions from gemini-code-review.

3036435

This comment was marked as outdated.

Sign in to view

Minor update to checking state in default_request_handler based on ge…

e7f5fb9

…mini suggestion.

This comment was marked as outdated.

Sign in to view

gemini-code-assist bot reviewed Feb 23, 2026

View reviewed changes

src/client/transports/json_rpc_transport.ts Outdated Show resolved Hide resolved

src/server/request_handler/default_request_handler.ts Outdated Show resolved Hide resolved

Applied gemini code suggestion. Resolved leftover TODO in a unit test.

ab9a627

bartek-gralewicz changed the base branch from bgralewicz/epic_1.0_braking_changes to epic/1.0_braking_changes February 24, 2026 09:22

Update CI workflows to trigger checks when merging to an epic branch.

a5e9d42

bartek-gralewicz changed the base branch from epic/1.0_braking_changes to epic/1.0_breaking_changes February 24, 2026 10:28

Remove type specifications from grpc_transport.

9f80c5f

jezekra1 reviewed Mar 3, 2026

View reviewed changes

src/samples/agents/movie-agent/index.ts Show resolved Hide resolved

jezekra1 reviewed Mar 3, 2026

View reviewed changes

src/samples/agents/movie-agent/index.ts Show resolved Hide resolved

bartek-gralewicz added 3 commits March 4, 2026 10:53

Restore type agnosticity in a2a_request_handler.

ea41ce7

Defined Base classes to reduce repetitions in json_rpc_types.js.

6fafc6b

Update betterer results after adding Base types for Params.

37e145d

bartek-gralewicz requested a review from ishymko March 5, 2026 07:43

ishymko reviewed Mar 9, 2026

View reviewed changes

bartek-gralewicz added 6 commits March 9, 2026 10:07

Move msg/task conversion logic from client.ts to ToProto.

c64081a

Reuse extractTaskId method in client.ts.

5dc353d

Restructure imports and exports to keep transport related types in th…

49a488a

…eir relevant locations. Resolved type issues after updating imports.

Minor formatting changes + code diff reduction.

224504a

Minor formatting changes + code diff reduction.

3ded9cb

Minor formatting changes + code diff reduction.

e7c4df4

ishymko reviewed Mar 10, 2026

View reviewed changes

bartek-gralewicz and others added 11 commits March 10, 2026 14:52

Apply changes from #346 bugfix PR.

8fd779a

Removed an empty echo parser in .

e8eb53d

Update src/client/transports/rest_transport.ts

27cbbae

Co-authored-by: Ivan Shymko <ishymko@google.com>

Import types directly from index.js instead of /types/pb/a2a_types.js.

22875d4

Merge branch 'bgralewicz/proto_types' of github.com:a2aproject/a2a-js…

16abc9d

… into bgralewicz/proto_types

Removed most of JSON-RPC types and replaced them with proper PROTO ty…

b439d67

…pes and toJSON/fromJSON methods.

Remove redundant and unused FromProto and ToProto methods. Note: some…

33fefd0

… methods remain for now as removing them would introduce other necessary changes.

Remove redundant and unused FromProto and ToProto methods. Note: some…

6ccf298

… methods remain for now as removing them would introduce other necessary changes.

Removed unwanted export for Base type interface.

dd1c08a

Small diff reduction and import cleanup.

d66f1d4

Merge branch 'epic/1.0_breaking_changes' into bgralewicz/proto_types

c2129d3

ishymko approved these changes Mar 13, 2026

View reviewed changes

bartek-gralewicz merged commit a886b1a into epic/1.0_breaking_changes Mar 13, 2026
10 checks passed

bartek-gralewicz deleted the bgralewicz/proto_types branch March 13, 2026 13:23

Conversation

bartek-gralewicz commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Important

Uh oh!

gemini-code-assist bot commented Feb 20, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

This comment was marked as outdated.

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🧪 Code Coverage

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ishymko left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bartek-gralewicz commented Feb 20, 2026 •

edited

Loading

github-actions bot commented Feb 24, 2026 •

edited

Loading