Skip to content

Commit dc5a5da

Browse files
authored
feat(rest): serve HTTP+JSON responses as application/a2a+json (#1274)
## What Spec [11.1](https://a2a-protocol.org/latest/specification/#111-protocol-requirements): "**Content-Type:** application/a2a+json **SHOULD** be used for requests and responses". The spec uses it in every worked HTTP+JSON example - 20-plus of them. Every REST response inherited Starlette's `JSONResponse.media_type` default of `application/json`. `application/a2a+json` appeared nowhere in the repo, so the constant is new. ## Worth knowing: nobody implements this All four SDKs with published ACTS metrics - python, go, java, rust - fail `REST-CT-001`. It is a SHOULD, so it blocks no one's conformance, and a reasonable response to this PR is "not yet, let the others move first". Merging it makes a2a-python the first. Flagging it rather than burying it, since the other six PRs in this stack all had at least one SDK already passing to corroborate them. ## Two limits, both deliberate **Success responses only.** The error path runs through `rest_error_handler`, which `compat/v0_3/rest_adapter.py` shares. 11.1 is the 1.0 binding's requirement, and v0.3 predates the media type, so changing that decorator would alter a different protocol version's wire format. Splitting it would mean making a bare decorator parameterized and touching every call site in both bindings - not worth it for a SHOULD the corpus does not test on the error path. The result is that 1.0 errors still answer `application/json`; worth a follow-up, not worth bundling here. **Responses only, not requests.** 11.1 says both, but changing what the client *sends* risks servers that only accept `application/json`, and no test covers it. **No `JSONResponse` subclass.** It would have reduced nine sites to an import swap, but `rest_dispatcher.py` aliases `JSONResponse = Any` when Starlette is absent, and `class X(Any)` is a `TypeError` on Python 3.10, which this package supports. Passing `media_type=` explicitly keeps the no-Starlette path importable and the sites greppable. ## Result Clears `REST-CT-001` (`should`, rest only). With it, **all three bindings are at zero failures at every level**: | binding | passed | must | failed | | --- | --- | --- | --- | | jsonrpc | 101/111 | 59/59 | 0 | | grpc | 88/111 | 47/47 | 0 | | rest | 92/111 | 49/49 | 0 | The remainder are skips whose preconditions the fixture does not meet, not failures.
1 parent 83f1cf8 commit dc5a5da

4 files changed

Lines changed: 45 additions & 11 deletions

File tree

‎.github/actions/spelling/allow.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ AGrpc
1515
aio
1616
aiomysql
1717
AIP
18+
AJSON
1819
alg
1920
amannn
2021
aproject

‎src/a2a/server/routes/rest_dispatcher.py‎

Lines changed: 17 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,8 @@
3636
from sse_starlette.event import ServerSentEvent
3737
from sse_starlette.sse import EventSourceResponse
3838
from starlette.requests import Request
39-
from starlette.responses import JSONResponse, Response
39+
from starlette.responses import JSONResponse as A2AJSONResponse
40+
from starlette.responses import Response
4041

4142
_package_starlette_installed = True
4243
else:
@@ -46,12 +47,17 @@
4647
from starlette.requests import Request
4748
from starlette.responses import JSONResponse, Response
4849

50+
class A2AJSONResponse(JSONResponse):
51+
"""JSONResponse labelled with the A2A media type."""
52+
53+
media_type = constants.A2A_JSON_MEDIA_TYPE
54+
4955
_package_starlette_installed = True
5056
except ImportError:
5157
EventSourceResponse = Any
5258
ServerSentEvent = Any
5359
Request = Any
54-
JSONResponse = Any
60+
A2AJSONResponse = Any
5561
Response = Any
5662

5763
_package_starlette_installed = False
@@ -172,7 +178,7 @@ async def _handler(
172178
return a2a_pb2.SendMessageResponse(message=task_or_message)
173179

174180
response = await self._handle_non_streaming(request, _handler)
175-
return JSONResponse(content=MessageToDict(response))
181+
return A2AJSONResponse(content=MessageToDict(response))
176182

177183
@rest_stream_error_handler
178184
async def on_message_send_stream(
@@ -210,7 +216,7 @@ async def _handler(context: ServerCallContext) -> a2a_pb2.Task:
210216
raise TaskNotFoundError
211217

212218
response = await self._handle_non_streaming(request, _handler)
213-
return JSONResponse(content=MessageToDict(response))
219+
return A2AJSONResponse(content=MessageToDict(response))
214220

215221
@rest_stream_error_handler
216222
async def on_subscribe_to_task(
@@ -246,7 +252,7 @@ async def _handler(context: ServerCallContext) -> a2a_pb2.Task:
246252
raise TaskNotFoundError
247253

248254
response = await self._handle_non_streaming(request, _handler)
249-
return JSONResponse(content=MessageToDict(response))
255+
return A2AJSONResponse(content=MessageToDict(response))
250256

251257
@rest_error_handler
252258
async def get_push_notification(self, request: Request) -> Response:
@@ -268,7 +274,7 @@ async def _handler(
268274
)
269275

270276
response = await self._handle_non_streaming(request, _handler)
271-
return JSONResponse(content=MessageToDict(response))
277+
return A2AJSONResponse(content=MessageToDict(response))
272278

273279
@rest_error_handler
274280
async def delete_push_notification(self, request: Request) -> Response:
@@ -286,7 +292,7 @@ async def _handler(context: ServerCallContext) -> None:
286292
)
287293

288294
await self._handle_non_streaming(request, _handler)
289-
return JSONResponse(content={})
295+
return A2AJSONResponse(content={})
290296

291297
@rest_error_handler
292298
async def set_push_notification(self, request: Request) -> Response:
@@ -305,7 +311,7 @@ async def _handler(
305311
)
306312

307313
response = await self._handle_non_streaming(request, _handler)
308-
return JSONResponse(content=MessageToDict(response))
314+
return A2AJSONResponse(content=MessageToDict(response))
309315

310316
@rest_error_handler
311317
async def list_push_notifications(self, request: Request) -> Response:
@@ -323,7 +329,7 @@ async def _handler(
323329
)
324330

325331
response = await self._handle_non_streaming(request, _handler)
326-
return JSONResponse(content=MessageToDict(response))
332+
return A2AJSONResponse(content=MessageToDict(response))
327333

328334
@rest_error_handler
329335
async def list_tasks(self, request: Request) -> Response:
@@ -338,7 +344,7 @@ async def _handler(
338344
return await self.request_handler.on_list_tasks(params, context)
339345

340346
response = await self._handle_non_streaming(request, _handler)
341-
return JSONResponse(
347+
return A2AJSONResponse(
342348
content=serialize_list_tasks_response(
343349
response, params.include_artifacts
344350
)
@@ -360,4 +366,4 @@ async def _handler(
360366
)
361367

362368
response = await self._handle_non_streaming(request, _handler)
363-
return JSONResponse(content=MessageToDict(response))
369+
return A2AJSONResponse(content=MessageToDict(response))

‎src/a2a/utils/constants.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,9 @@
1111
MAX_LIST_TASKS_PAGE_SIZE = 100
1212
"""Maximum page size for the `tasks/list` method."""
1313

14+
A2A_JSON_MEDIA_TYPE = 'application/a2a+json'
15+
"""Media type for HTTP+JSON binding payloads."""
16+
1417

1518
class TransportProtocol(str, Enum):
1619
"""Transport protocol string constants."""

‎tests/server/routes/test_rest_routes.py‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,3 +92,27 @@ def test_rest_list_tasks(agent_card, mock_handler):
9292
response = client.get('/tasks', headers={'A2A-Version': '1.0'})
9393
assert response.status_code == 200
9494
assert mock_handler.on_list_tasks.called
95+
96+
97+
def test_send_message_response_uses_the_a2a_media_type(
98+
agent_card, mock_handler
99+
):
100+
"""HTTP+JSON responses are labelled application/a2a+json."""
101+
mock_handler.on_message_send.return_value = Task(id='123')
102+
client = TestClient(Starlette(routes=create_rest_routes(mock_handler)))
103+
104+
response = client.post(
105+
'/message:send', json={}, headers={'A2A-Version': '1.0'}
106+
)
107+
108+
assert response.headers['content-type'].startswith('application/a2a+json')
109+
110+
111+
def test_list_tasks_response_uses_the_a2a_media_type(agent_card, mock_handler):
112+
"""The list path serializes separately, so it is asserted separately."""
113+
mock_handler.on_list_tasks.return_value = ListTasksResponse()
114+
client = TestClient(Starlette(routes=create_rest_routes(mock_handler)))
115+
116+
response = client.get('/tasks', headers={'A2A-Version': '1.0'})
117+
118+
assert response.headers['content-type'].startswith('application/a2a+json')

0 commit comments

Comments
 (0)