You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
[Task]: Clarify the scope and exposition of the internal JSON wire format and the general API #523
I'm not sure I understand correctly the scope and breadth of the spec API.
This represents the "domain" objects which are a user-friendly Java-idiomatic API that users can leverage to build A2A clients and servers.
It aims to be "transport" agnostic and be used whether the transport protocol is JSON-RPC, gRPC or REST+JSON.
I spotted a few things that seem to contradict my understanding:
JSON-RPC is implied by many exposed types (JSONRPCMessage, JSONRPCError) which looks weird when the user would rely on another transport (eg gRPC)
The spec module exposes many classes that do not need to be part of the API (eg CancelTaskRequest is used at the transportlevel, not a theclient` level
The io.a2a.util.Utils expose the internal JSON wire format used by a2a-java (for replication) and is not meant to be used or exposed by the client API
From an user point of view, this makes the task of using a2a-java more complex that it really is, the client part of the spec can be simplified (eg #517, #507, #506), reducing the exposed types and making the client API more intuitive.
Depending on the pace of the a2a protocols providing a better isolation of the client & server API from the internal changes of the protocol would provide a more robust user-experience and less painful path for upgrades.
The history of this is that initially JSON-RPC was the only protocol in the spec, which we then followed for the first version of the client.
Later gRCP and HTTP+JSON were introduced, which don't have those wrappers.
At one stage we had three versions of clients, depending on the protocol used, which led to us standardising on the current 'common client'.
If that can be simplified further, I think that sounds like a good thing
Activity
kabir commentedon Dec 10, 2025
The history of this is that initially JSON-RPC was the only protocol in the spec, which we then followed for the first version of the client.
Later gRCP and HTTP+JSON were introduced, which don't have those wrappers.
At one stage we had three versions of clients, depending on the protocol used, which led to us standardising on the current 'common client'.
If that can be simplified further, I think that sounds like a good thing
kabir commentedon Dec 22, 2025
Fixed by #556