Skip to content

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

@jmesnil

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.

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