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 4ce79ebb1..c88861fdb 100644 --- a/tests/server/routes/test_fastapi_routes.py +++ b/tests/server/routes/test_fastapi_routes.py @@ -88,6 +88,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')