Skip to content

fix(server): answer HEAD on GET routes mounted on FastAPI - #1472

Closed
saquibjawedbit wants to merge 2 commits into
a2aproject:mainfrom
saquibjawedbit:fix/fastapi-head-routes
Closed

saquibjawedbit wants to merge 2 commits into
a2aproject:mainfrom
saquibjawedbit:fix/fastapi-head-routes

Conversation

@saquibjawedbit

Copy link
Copy Markdown
Contributor

Description

The SDK's Starlette route factories answer HEAD on every GET route, but add_a2a_routes_to_fastapi does not. Once the routes are mounted on FastAPI, HEAD on the agent card and on GET /tasks/{id} stops working. This also breaks the cheap way to revalidate the agent card: since #1272 the card is served with ETag and Cache-Control, and a client or cache can check those headers with HEAD without downloading the card. RFC 9110 §9.1 says general-purpose servers MUST support GET and HEAD.

starlette = TestClient(Starlette(routes=create_agent_card_routes(card)))
app = FastAPI()
add_a2a_routes_to_fastapi(app, agent_card_routes=create_agent_card_routes(card))

starlette.head('/.well-known/agent-card.json').status_code      # 200
TestClient(app).head('/.well-known/agent-card.json').status_code  # 405

With the REST routes mounted as well, the same request returns 404 instead. That 404 comes from the helper's own route order: with no route left to answer HEAD, the request falls into the /{tenant} mount, which reads .well-known as a tenant. This PR does not change the tenant mount or how routes are matched (the subject of #1443). It only gives HEAD a route to land on again.

The cause is in _attach_route. Since #1024 it drops HEAD when it rebuilds each route as an APIRoute, so that /docs does not get duplicate operation IDs. Unlike Starlette's Route, APIRoute does not add HEAD back for a GET route, so nothing answers it any more.

Fix

When the original route accepts HEAD, _attach_route now also appends that route after the APIRoute. GET still matches the APIRoute first. For HEAD the APIRoute matches only partly (wrong method), so the router moves on to the original route, which answers it as it does on Starlette. The original route is not an APIRoute, so FastAPI leaves it out of the schema, and /docs still has no HEAD operations.

Testing evidence

New test test_get_routes_still_answer_head in tests/server/routes/test_fastapi_routes.py. It checks that:

  • HEAD on the agent card returns 200 with an empty body and the same ETag as GET.
  • HEAD /tasks/{id} returns 200 with an empty body and calls the handler once.
  • The schema has no head operation for either path.
  • An app with only the agent card routes (the 405 case) answers HEAD with 200.

Before the fix (src/a2a/server/routes/fastapi_routes.py from main at caab6a2):

$ uv run pytest tests/server/routes/test_fastapi_routes.py -k still_answer_head
>       assert card_response.status_code == 200
E       assert 404 == 200
E        +  where 404 = <Response [404 Not Found]>.status_code
tests/server/routes/test_fastapi_routes.py:98: AssertionError
1 failed, 7 deselected, 1 warning in 0.42s

After the fix:

$ uv run pytest tests/server/routes/test_fastapi_routes.py
8 passed, 1 warning in 0.41s
  • ./scripts/lint.sh: ruff check and ruff format pass (285 files unchanged), and so does ty. ty prints the same 3 unused type: ignore warnings as on main, in files this PR does not touch.

  • uv run pytest --cov=src --cov-report=term-missing: 2618 passed, 215 skipped, 4 xfailed, 1 xpassed, 4 errors, 94% total coverage. The 4 errors are in tests/integration/cross_version/client_server/test_client_server.py: the v0.3 test server does not start in time on my machine. main gives the same 4 errors.

  • Follow the CONTRIBUTING Guide.

  • Make your Pull Request title in the https://www.conventionalcommits.org/ specification.

  • Ensure the tests and linter pass (Run bash scripts/format.sh from the repository root to format)

  • Appropriate docs were updated (if necessary)

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.
@saquibjawedbit
saquibjawedbit requested a review from a team as a code owner November 15, 2026 17:50
@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

🧪 Code Coverage (vs main)

⬇️ Download Full Report

Base PR Delta
src/a2a/server/routes/fastapi_routes.py 91.89% 92.31% 🟢 +0.42%
Total 93.63% 93.63% ⚪️ 0.00%

Generated by coverage-comment.yml

@Iwaniukooo11 Iwaniukooo11 self-assigned this Nov 16, 2026
@Iwaniukooo11

Copy link
Copy Markdown
Member

Thanks for the detailed writeup and the repro.

We're not going to merge this one. The spec doesn't mention HEAD anywhere, and the current 405 matches what a2a-go does

You're right that Starlette answers HEAD by default. But that's a property of the library we happen to mount on, not a decision about where the SDK is going

If you think that HEAD should be supported, then please raise it in the A2A spec repo so all the SDKs move together.

Thanks again.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants