feat!: remove the built-in Handler agent

[alDuncanson]

uv tool install a2a-handler has been failing on macOS. handler update and uv tool upgrade failed the same way, for the same reason.

The cause

litellm stopped shipping macOS wheels. 1.92.0 added a Rust native extension (litellm-rust/crates/python-bridge), and every release since publishes manylinux and win_amd64 only:

litellm	Date	Wheels
≤ 1.91.4	thru 2026-07-19	py3-none-any — installs everywhere
1.92.0 → 1.95.0	2026-07-12 → 08-02	manylinux + win only

With no macOS wheel at any Python version, macOS falls back to building the sdist, which needs rustc >= 1.94.1. Anything older dies in cargo on the aws-* crates.

Two things this is not: it isn't Python 3.14-specific (there is no mac wheel for 3.11–3.13 either), and it isn't the lockfile. But the lockfile is why we never saw it — uv.lock pinned litellm 1.87.0, so CI and local dev stayed green while every published install was broken. uv tool install, uvx, and pip all ignore the lockfile and resolve from wheel metadata, where litellm>=1.0.0 was unbounded. Linux users were unaffected throughout.

Why remove the agent rather than cap the dependency

litellm was only ever reachable through the built-in agent, via google.adk.models.lite_llm.LiteLlm. Nothing else in Handler imported it. Capping it would have pinned us to a July build of a package we do not otherwise need, to keep alive a feature that was never core: Handler is an A2A client, and hosting an agent sat well outside that. The agent also accounted for roughly a third of the dependency tree.

What is gone

• src/a2a_handler/server/ — the agent, its A2A app, card builder, Ollama probing, and ADK doc tools
• handler server run agent
• the synthetic "Handler Agent" entry auto-injected into the global server catalog
• the TUI's auto-spawn/shutdown of that agent as a subprocess (~194 lines in tui/server/tab.py)
• the google-adk and litellm dependencies

What is unaffected

The CLI, TUI, MCP bridge, session and task handling, server configuration management, and handler server run push. a2a-sdk[http-server] stays — it is what provides starlette for the webhook server.

Resolved dependencies drop 104 → 73.

Verification

Local: ruff, ruff format, ty, and 415 tests pass. Snapshots differ only by the version string; TUI rendering is unchanged.

Then the path that was actually broken — built the wheel and installed it with uv tool install against a clean cache with no lockfile, on macOS/CPython 3.14. It installs with no Rust and no build step.

Then end-to-end against a real remote A2A agent on GKE (A2A v1.0 JSONRPC):

Exercised	Result
card get	Resolved, v1.0, skills listed
message send --url	Answered and executed Python remotely
server add / list / validate / remove	Full round trip, status: ok
message send --server	Completed, --output json envelope valid
task get --task <id>	Re-fetched, same artifact
session list	Session persisted
handler mcp stdio	Initialized, 10 tools
MCP send_message → live agent	Task completed

Breaking change

handler server run agent is removed, along with the built-in "Handler Agent" entry in the TUI server picker. Connect to an external A2A server instead. Version bumped to 0.2.0 — a minor bump, since removing a public CLI command is breaking under pre-1.0 semver.

Docs updated across quickstart, guides/servers, guides/local-servers, guides/agent-docs-mcp, reference/cli, and CONTRIBUTING.

Follow-ups, not in this PR

• Snapshot fixtures embed the version string, so all 3 break on every release. The footer test now derives from __version__; the snapshots still need --snapshot-update each bump.
• webhook.py imports starlette directly but receives it via a2a-sdk[http-server]; worth declaring outright.
• handler task get requires --task rather than accepting a positional id.
• The MCP server reports the mcp library version in serverInfo, not Handler's.
• The README screenshot still shows the built-in agent.

🤖 Generated with Claude Code