Skip to content

[Task]: Clarify the scope and exposition of the internal JSON wire format and the general API #523

Closed

Description

@jmesnil

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.

Activity

  1. kabir commented on Dec 10, 2025

    @kabir
    Collaborator

    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

  2. kabir commented on Dec 22, 2025

    @kabir
    Collaborator

    Fixed by #556

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions