Skip to content

fix(a2a): declare a2a-sdk[http-server] so the a2a extra can serve - #6671

Open
arunpshankar wants to merge 1 commit into
google:mainfrom
arunpshankar:fix-a2a-extra-sse-starlette
Open

fix(a2a): declare a2a-sdk[http-server] so the a2a extra can serve#6671
arunpshankar wants to merge 1 commit into
google:mainfrom
arunpshankar:fix-a2a-extra-sse-starlette

Conversation

@arunpshankar

Copy link
Copy Markdown

Link to Issue or Description of Change

No existing issue.

Problem:

The a2a extra installs a2a-sdk with no extras. That is enough to
import the package but not to run the server: sse-starlette is declared
only under a2a-sdk's http-server, fastapi and all extras, and every
server dispatcher imports it at module level.

to_a2a() builds an A2AStarletteApplication, which routes through
a2a.server.routes.jsonrpc_dispatcher, so a clean install of
google-adk[a2a] fails at startup with:

ModuleNotFoundError: No module named 'sse_starlette'

This stays invisible during development because mcp requires
sse-starlette, so any environment that has ever installed the mcp extra
already satisfies it by accident. It surfaces on the first genuinely
clean install — typically a container — and the runtime then reports a
failed startup probe on the port rather than the missing module, which
sends you looking at networking instead of packaging.

Solution:

Declare a2a-sdk[http-server] in the a2a extra.

http-server rather than a direct sse-starlette pin because it states
the intent — ADK serves the A2A HTTP application — and leaves the
transitive set to a2a-sdk to decide. The extra exists at the pinned floor
(0.3.4) and carries sse-starlette through the current 1.1.2, so it holds
across the whole >=0.3.4,<2 range.

This is not the lazy-import case that some earlier dependency reports
turned out to be: the import lives inside a2a-sdk rather than in ADK, and
it is needed to serve, not merely to import.

Testing Plan

Unit Tests:

  • I have added or updated unit tests for my change.
  • All unit tests pass locally (unaffected by this change).

No unit test is added, and I want to be explicit about why rather than
add a token one: this is an install-time property, and CI installs the
extras it needs, so the failure is not observable from inside a test
session that can already import the module. Happy to add one if you would
like it — the natural home looks like the packaging-adjacent checks in
tests/unittests/test_import_loading.py.

That file's test_constructing_agent_defers_optional_mcp_server_stack
asserts sse_starlette is not imported when constructing an Agent.
This change does not affect it: installing a package does not import it.

Manual End-to-End (E2E) Tests:

From an empty virtualenv, installing exactly what the a2a extra
installs today:

$ pip install "a2a-sdk>=0.3.4,<2"
$ python -c "import a2a.server.routes.jsonrpc_dispatcher"
ModuleNotFoundError: No module named 'sse_starlette'
$ python -c "import a2a.compat.v0_3.jsonrpc_adapter"
ModuleNotFoundError: No module named 'sse_starlette'
$ python -c "import a2a.server.routes.rest_dispatcher"
ModuleNotFoundError: No module named 'sse_starlette'

With this change:

$ pip install "a2a-sdk[http-server]>=0.3.4,<2"
$ python -c "import a2a.server.routes.jsonrpc_dispatcher"   # ok
$ python -c "import a2a.compat.v0_3.jsonrpc_adapter"        # ok
$ python -c "import a2a.server.routes.rest_dispatcher"      # ok

pyproject-fmt==2.24.0, the version pinned in .pre-commit-config.yaml,
reports no change for pyproject.toml.

Checklist

  • I have read the CONTRIBUTING.md document.
  • I have performed a self-review of my own code.
  • I have commented my code, particularly in hard-to-understand areas.
  • My changes generate no new warnings.

The `a2a` extra installs `a2a-sdk` with no extras, which is enough to
import the package but not to run the server. `sse-starlette` is only
declared under a2a-sdk's `http-server`, `fastapi` and `all` extras, and
every server dispatcher imports it at module level:

    a2a.server.routes.jsonrpc_dispatcher
    a2a.server.routes.rest_dispatcher
    a2a.compat.v0_3.jsonrpc_adapter

`to_a2a()` builds an `A2AStarletteApplication`, which routes through the
first of these, so a clean install of `google-adk[a2a]` raises
ModuleNotFoundError: No module named 'sse_starlette' at startup.

This is invisible during development because `mcp` requires
sse-starlette, so any environment that has ever installed the `mcp`
extra already satisfies it by accident. It surfaces on the first clean
install - typically a container - and the runtime reports a failed
startup probe on the port rather than the missing module.

Repro, from an empty venv:

    pip install "a2a-sdk>=0.3.4,<2"          # what the a2a extra installs
    python -c "import a2a.server.routes.jsonrpc_dispatcher"
    # ModuleNotFoundError: No module named 'sse_starlette'

    pip install "a2a-sdk[http-server]>=0.3.4,<2"
    python -c "import a2a.server.routes.jsonrpc_dispatcher"   # ok

`http-server` rather than a direct `sse-starlette` pin because it states
the intent - ADK serves the A2A HTTP application - and leaves the
transitive set to a2a-sdk. The extra exists at the pinned floor (0.3.4)
and carries sse-starlette through the current 1.1.2, so it holds across
the whole `>=0.3.4,<2` range.

This is not the lazy-import case: the import is inside a2a-sdk, and it
is needed to serve, not merely to import. It also leaves
test_constructing_agent_defers_optional_mcp_server_stack unaffected -
that asserts sse_starlette is not imported when constructing an Agent,
which installing it does not change.
@adk-bot adk-bot added the core [Component] This issue is related to the core interface and implementation label Aug 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

core [Component] This issue is related to the core interface and implementation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants