From 9c3662321dd133b4d9d066c14083fe555726403f Mon Sep 17 00:00:00 2001 From: Saquib Jawed <138011435+saquibjawedbit@users.noreply.github.com> Date: Sun, 15 Nov 2026 23:13:09 +0530 Subject: [PATCH] fix(server): answer HEAD on GET routes mounted on FastAPI The Starlette route factories answer HEAD for every GET route, but add_a2a_routes_to_fastapi does not. It re-registers each route as a FastAPI APIRoute without HEAD, to avoid duplicate operation IDs in /docs, and APIRoute does not add HEAD back for a GET route. HEAD on the agent card or on GET /tasks/{id} therefore stopped working once the routes were mounted on FastAPI, including the cheap ETag revalidation of the agent card. Keep the original route mounted behind the APIRoute. It is not an APIRoute, so it stays out of the OpenAPI schema, and it serves HEAD as it does on Starlette. --- src/a2a/server/routes/fastapi_routes.py | 8 ++++- tests/server/routes/test_fastapi_routes.py | 38 ++++++++++++++++++++++ 2 files changed, 45 insertions(+), 1 deletion(-) diff --git a/src/a2a/server/routes/fastapi_routes.py b/src/a2a/server/routes/fastapi_routes.py index 77c0c0711..fdee2962f 100644 --- a/src/a2a/server/routes/fastapi_routes.py +++ b/src/a2a/server/routes/fastapi_routes.py @@ -91,7 +91,9 @@ def _attach_route( if not (isinstance(route, Route) and route.methods): app.routes.append(route) return - # Drop HEAD: Starlette adds it alongside GET, but FastAPI registers duplicate operation IDs. + # Drop HEAD from the APIRoute: Starlette adds it alongside GET, but + # FastAPI would register duplicate operation IDs. HEAD is served by the + # original route, mounted below. methods = sorted(m for m in route.methods if m != 'HEAD') if require_version_header: extra = dict(openapi_extra or {}) @@ -106,6 +108,10 @@ def _attach_route( openapi_extra=openapi_extra, ) ) + if 'HEAD' in route.methods: + # APIRoute does not answer HEAD for a GET route. The original route + # is not an APIRoute, so it serves HEAD without entering the schema. + app.routes.append(route) def add_a2a_routes_to_fastapi( diff --git a/tests/server/routes/test_fastapi_routes.py b/tests/server/routes/test_fastapi_routes.py index 817862039..bd6bb988d 100644 --- a/tests/server/routes/test_fastapi_routes.py +++ b/tests/server/routes/test_fastapi_routes.py @@ -85,6 +85,44 @@ def test_routes_dispatch_under_fastapi( assert rest_response.json()['task']['id'] == 'task-123' +def test_get_routes_still_answer_head( + agent_card: AgentCard, mock_handler: AsyncMock +) -> None: + """GET routes answer HEAD, without a HEAD operation in the schema.""" + mock_handler.on_get_task.return_value = Task(id='task-123') + + app = _build_app(agent_card, mock_handler) + client = TestClient(app) + + card_response = client.head(AGENT_CARD_WELL_KNOWN_PATH) + assert card_response.status_code == 200 + assert card_response.content == b'' + assert ( + card_response.headers['etag'] + == client.get(AGENT_CARD_WELL_KNOWN_PATH).headers['etag'] + ) + + task_response = client.head( + '/tasks/task-123', headers={VERSION_HEADER: PROTOCOL_VERSION_1_0} + ) + assert task_response.status_code == 200 + assert task_response.content == b'' + mock_handler.on_get_task.assert_awaited_once() + + paths = app.openapi()['paths'] + assert 'head' not in paths[AGENT_CARD_WELL_KNOWN_PATH] + assert 'head' not in paths['/tasks/{id}'] + + card_only = FastAPI() + add_a2a_routes_to_fastapi( + card_only, agent_card_routes=create_agent_card_routes(agent_card) + ) + assert ( + TestClient(card_only).head(AGENT_CARD_WELL_KNOWN_PATH).status_code + == 200 + ) + + def test_tenant_mount_still_dispatches(mock_handler: AsyncMock) -> None: """`Mount` entries (tenant routing) keep dispatching after registration.""" mock_handler.on_message_send.return_value = Task(id='tenant-task')