A2A is disabled on the pinned a2a-sdk 1.2.1: adk_main.py uses the 0.3.x API #223

What happens

requirements.lock pins a2a-sdk==1.2.1 (since 362b617, 2026-10-03). The A2A setup in adk_main.py (lines ~504–640) is written against the a2a-sdk 0.3.x API, so starting the ADK server with --a2a does not expose any agent.

• from a2a.server.apps import A2AStarletteApplication (line 504): a2a.server.apps does not exist in 1.2.1. The import raises ImportError, the except ImportError branch prints ❌ A2A dependencies not available: ... and ⚠️ A2A support disabled, and startup continues with no /a2a/* routes.
• AgentCard(**agent_card_data) (line 618): in 1.x AgentCard is a protobuf message (a2a/types/a2a_pb2.py), not the pydantic model the dict was written for (url, capabilities, defaultInputModes, ...).
• JSON-RPC method names: 1.x serves SendMessage, SendStreamingMessage, GetTask, CancelTask, GetExtendedAgentCard. The 0.3 names (message/send, tasks/get, ...) are only handled by the v0.3 compat layer (a2a/compat/v0_3/).

ServerControlService always starts ADK with --a2a, so this affects every dashboard-managed deployment. The failure is only a printed line at startup.

Knock-on effect: agents over MCP

shared/utils/tools/agent_mcp_protocol_handler.py (~line 152) forwards MCP tools/call to http://{adk_host}:{adk_port}/a2a/{agent_name} with a message/send payload. With no /a2a routes, exposing an agent over MCP fails too.

How this was found

While reviewing #217 (the A2A dev guide), by reading the a2a-sdk==1.2.1 and google-adk==2.11.0 wheels. ADK was not started with --a2a here. Please confirm with a real start: python adk_main.py --a2a should print the "A2A dependencies not available" line.

Pointers for the fix

google-adk==2.11.0 already handles both SDK versions in google/adk/a2a/_compat.py (IS_A2A_V1):

• attach_a2a_routes_to_app(app, agent_card=..., agent_executor=..., task_store=..., prefix=...) mounts the JSON-RPC route and the agent card under a prefix. On 1.x it uses a2a.server.routes.create_jsonrpc_routes / create_agent_card_routes, with enable_v0_3_compat=True by default, so the existing message/send callers (including the MCP handler) keep working.
• parse_agent_card(dict) builds an AgentCard from a JSON dict on either version, which fits the default card plus agents/<name>/agent.json merge.

Using these instead of a2a.* directly would also keep adk_main.py working across future SDK bumps. Alternatively, pin a2a-sdk back to 0.3.x, but that only defers it.

Done when

• python adk_main.py --a2a registers /a2a/{agent} and /a2a/{agent}/.well-known/agent-card.json for each agent on the pinned versions.
• A message/send request to /a2a/{agent} gets an answer, and so does an MCP tools/call for an exposed agent.
• A test covers that the A2A setup imports and registers routes, so a dependency bump that breaks it fails CI instead of logging a line.
• docs/dev/a2a.md (docs(dev): verify a2a guide against code and remove migrated status (#206) #217) is checked against the result: method names, card format, and which protocol versions are accepted.