HTTP+JSON payload shape mismatches proto‑JSON (ADK/Agent Engine 400s)

[adamfweidman]

What happened?

Bug Report / Feature Request: HTTP+JSON Payload Shape

Reference PR in gemini-cli: google-gemini/gemini-cli#16013

Summary

HTTP+JSON requests from @a2a-js/sdk@0.3.7 are rejected by ADK/Agent Engine
unless the client rewrites request/response payloads. The SDK emits a legacy
JSON shape that does not match the spec’s proto-JSON binding.

Environment

• @a2a-js/sdk@0.3.7
• Node 18+
• ClientFactory + HTTP+JSON transport
• Server: ADK/Agent Engine (A2A REST adapter)

Repro (API call that rejects)

The SDK sends a POST to /v1/message:send with this shape:

{
  "message": {
    "kind": "message",
    "role": "user",
    "messageId": "msg-1",
    "parts": [{ "kind": "text", "text": "hello" }]
  },
  "configuration": { "blocking": true }
}

Response from ADK/Agent Engine: HTTP 400 (request rejected).

Spec vs SDK Mismatch (Summary)

Spec (proto-JSON): ROLE_* enums, parts oneof (no kind), TASK_STATE_*,
wrapper responses { task|message: ... }.
SDK 0.3.7: role: "user", parts with kind, lower-case task states, expects
bare Task/Message.

Impact

When talking to ADK/Agent Engine (which parses proto-JSON), requests are
rejected (invalid enum values / unknown fields), or responses cannot be
parsed because they are wrapped.

This forces client applications to implement a shim that:

• maps user -> ROLE_USER
• converts parts to proto-JSON oneof form (no kind)
• unwraps { task: ... } / { message: ... }
• maps TASK_STATE_* to lower-case states

Request

Add a proto-JSON mode (or dedicated transport) for HTTP+JSON that:

• emits ROLE_* enums
• encodes parts oneof without kind
• unwraps { task|message: ... }
• maps TASK_STATE_* for SDK consumers

Relevant log output

Code of Conduct

• I agree to follow this project's Code of Conduct

[ishymko]

v0.3 doesn't mention using ProtoJSON for HTTP+JSON/REST, in fact it doesn't mention serialization for HTTP+JSON/REST format at all except for

Request/Response Format: MUST use JSON objects that are structurally equivalent to the core A2A data structures.

from here which can be interpreted differently.

In my opinion using two different ways of serializing JSON in JSON-RPC and REST is wrong (it was reported in Python SDK: a2aproject/a2a-python#548), however the fact that it became is a de-facto standard across SDKs was missed on our end when implementing REST support.

Current v1.0 DRAFT specifies kebab-case for enums, BUT there is a pending PR to change it once again and stick with ProtoJSON everywhere: a2aproject/A2A#1214.

Given that all SDKs use different format now I agree it should be changed in TS SDK to make it compatible with others.