[bug] Fresh `pip install google-adk` per docs leaves `adk web` without the chat UI (undeclared deps: `google-cloud-storage`, `python-multipart`)

[mautomo]

[bug] Fresh pip install google-adk per docs leaves adk web without the chat UI (undeclared deps: google-cloud-storage, python-multipart)

TL;DR

Following the official install instructions at https://adk.dev/get-started/installation/ (just pip install google-adk) on Python 3.13 produces a working adk run CLI but a silently degraded adk web: the API server starts, but the dev chat UI is unreachable because DevServer fails to import on missing transitive deps that aren't declared in the core install.

Two undeclared runtime deps for the dev server:

1. google-cloud-storage — only declared under [gcp], [all], and [test] extras (METADATA lines 58, 117, 148), but imported unconditionally by google.adk.cli.dev_server → google.adk.cli.utils.evals → google.adk.evaluation.gcs_eval_set_results_manager.
2. python-multipart — declared nowhere in METADATA, but needed for the Builder UI endpoints.

Reproduction

# Fresh venv, Python 3.13.7 (uv-managed)
uv init adk-repro --python 3.13
cd adk-repro
uv add google-adk      # matches the official docs verbatim
# Create a minimal agent at agents/demo/{__init__.py, agent.py}
uv run adk web agents --port 8000

Expected

Per the README and AGENTS.md (adk web is described as "Launch web UI (recommended for development)"), opening http://127.0.0.1:8000 should show the chat UI bundled at /dev-ui/.

Actual

Server starts but logs:

WARNING - fast_api.py:525 - DevServer not found, falling back to ApiServer. Dev-only endpoints will not be available.
WARNING - fast_api.py:79  - python-multipart not installed. Builder UI endpoints will not be available.

GET / returns 307 → /dev-ui/ but /dev-ui/ 404s because the static assets are served by DevServer, which never got mounted.

The underlying import error (visible by reproducing from google.adk.cli.dev_server import DevServer directly):

ModuleNotFoundError: No module named 'google.cloud'
  File ".../google/adk/cli/dev_server.py", line 69, in <module>
    from .utils import evals
  File ".../google/adk/cli/utils/evals.py", line 25, in <module>
    from ...evaluation.gcs_eval_set_results_manager import GcsEvalSetResultsManager
  File ".../google/adk/evaluation/gcs_eval_set_results_manager.py", line 19, in <module>
    from google.cloud import exceptions as cloud_exceptions

Workaround

uv add google-cloud-storage python-multipart

Confirmed: with both installed, DevServer imports cleanly and /dev-ui/ serves the 55KB SPA. No other code changes needed.

Proposed fixes (pick one)

1. Move google-cloud-storage and python-multipart to core Requires-Dist. Smallest change, matches what adk web already promises out of the box. ~50KB install bump for python-multipart; google-cloud-storage pulls a heavier tail but most ADK users hit it eventually via Vertex / GCS sessions anyway.
2. Lazy-import the GCS eval manager inside google.adk.cli.utils.evals (and downstream evaluation.gcs_eval_set_results_manager) so DevServer doesn't crash when google-cloud-storage isn't present. Pair with adding python-multipart to core, or a new [web] extra. Best behavior: full UI on minimal install, GCS-backed eval sets gated behind [gcp].
3. Document the extras requirement. Update https://adk.dev/get-started/installation/ to say pip install "google-adk[gcp]" python-multipart (or similar) is required for adk web. Lowest engineering cost, but a fresh-install user still hits the silent fallback unless they read carefully.

Option 2 seems closest to the existing extras architecture intent — the [gcp] extra exists for a reason, and the dev server hard-importing GCS-backed eval state defeats the split.

Environment

• OS: Windows 11 (10.0.26200)
• Python: 3.13.7 (uv-managed)
• google-adk: 2.0.0 (PyPI wheel)
• uv: 0.11.15
• Reproduced both via uv add google-adk and pip install google-adk in a venv.

Related

• UnboundLocalError on ApiServer in cli/fast_api.py when running adk web --reload_agents on 2.0.0 #5765, adk web command fails with "UnboundLocalError: cannot access local variable 'ApiServer' where it is not associated with a value" #5782 — the --reload_agents UnboundLocalError on ApiServer is a separate (already-reported) bug that becomes reachable only after this one is fixed (i.e., when DevServer actually imports).

Not filed separately because

• The --reload_agents UnboundLocalError is already tracked at UnboundLocalError on ApiServer in cli/fast_api.py when running adk web --reload_agents on 2.0.0 #5765 and adk web command fails with "UnboundLocalError: cannot access local variable 'ApiServer' where it is not associated with a value" #5782.
• This issue is scoped to install-time/import-time degradation of adk web. Once How to use api_transport "REST"? in Agent #1 of the proposed fixes lands, the chat UI works on a fresh install without surprises.

[mautomo]

Three more issues surfaced while exploring SQLite session persistence and the A2A protocol on a fresh pip install google-adk install. The first two are the same packaging-bug pattern as the original report; the third is behavioral and may warrant its own issue.

4) agent.json is silently skipped when --a2a is set

fast_api.py:666-673 iterates the agents directory and continues past any folder that doesn't contain agent.json. There is no logger.info or logger.warning — the user just sees no A2A endpoints mounted and has no idea why.

Repro: launch adk api_server agents --a2a --port 8001 against a normal agent folder (__init__.py + agent.py, no agent.json). The server starts, /list-apps returns the agent, but /a2a/<agent>/.well-known/agent-card.json returns 404 with no diagnostic in the server log.

Suggested fix: logger.info("Skipping %s for A2A — no agent.json found", p.name) inside the skip branch.

5) --a2a requires a2a-sdk[http-server] (undeclared)

After adding an agent.json, the next failure is at server startup:

ERROR - fast_api.py:712 - Failed to setup A2A agent sandbox_agent:
Packages `starlette` and `sse-starlette` are required to use the `JSONRPCApplication`.
They can be added as a part of `a2a-sdk` optional dependencies, `a2a-sdk[http-server]`.

google-adk[a2a] pulls a2a-sdk but not its [http-server] extra (which provides sse-starlette). Same pattern as the original report — feature surface promised by the CLI flag, dep not in the install chain. Workaround: pip install "a2a-sdk[http-server]". This one is logged as an ERROR at least, but it's still a fresh-install-per-docs failure.

Suggested fix: either bump google-adk[a2a] to depend on a2a-sdk[http-server] rather than bare a2a-sdk, or make it a soft suggestion in the error message that this can be pulled via the [a2a] extra path.

6) [behavioral — possibly separate issue] event.is_final_response() doesn't fire over A2A

A RemoteA2aAgent consumer that filters events with event.is_final_response() will silently drop the final text. The A2A protocol bundles tool_call + tool_response + final_text into a single event with multiple parts, where the local-agent equivalent would emit them as separate events. The is_final_response() heuristic appears to expect the separated form.

Repro (against the server set up above):

remote = RemoteA2aAgent(name="ws", agent_card="http://.../a2a/<name>/.well-known/agent-card.json", use_legacy=False)
runner = Runner(app_name="c", agent=remote, session_service=InMemorySessionService())
await runner.session_service.create_session(app_name="c", user_id="d", session_id="s")
final = ""
async for ev in runner.run_async(user_id="d", session_id="s", new_message=msg):
    if ev.is_final_response() and ev.content and ev.content.parts:
        final = ev.content.parts[0].text  # never fires

Printing every event shows exactly one event with three parts: a function_call part, a function_response part, and a text part containing the final answer. is_final_response() returns False on this event.

This is documented nowhere I could find. Sample/quickstart code at adk.dev/a2a/quickstart-consuming doesn't surface the issue because the consumer there doesn't print the response, only routes it as a sub-agent.

Workaround for now is "take the last non-empty text part across all events":

final = ""
async for ev in runner.run_async(...):
    if ev.content and ev.content.parts:
        for part in ev.content.parts:
            if getattr(part, "text", None):
                final = part.text

If is_final_response() is supposed to be a stable cross-transport API, the bundling behavior on the A2A side or the heuristic itself probably needs a tweak. Happy to file this separately if you'd rather track it apart from the install-time issues.

---

Environment (same as original report)

• Windows 11, Python 3.13.7 (uv-managed), google-adk==2.0.0 from PyPI
• a2a-sdk==0.3.26 (via google-adk[a2a])
• All three reproduced today (2026-05-21).

[mangod12]

I've submitted a PR to fix this: #5789