a2a-handler 0.1.24__tar.gz → 0.1.26__tar.gz

{a2a_handler-0.1.24 → a2a_handler-0.1.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: a2a-handler
-Version: 0.1.24
+Version: 0.1.26
 Summary: An A2A Protocol client TUI and CLI.
 Keywords: a2a,a2a-protocol,agent,agent-to-agent,ai,cli,tui
 Author: Al Duncanson
@@ -18,9 +18,9 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
-Requires-Dist: a2a-sdk>=0.3.24,<1.0.0
+Requires-Dist: a2a-sdk[http-server]>=1.0.0,<2.0.0
 Requires-Dist: click>=8.0.0
-Requires-Dist: google-adk>=2.0.0
+Requires-Dist: google-adk[mcp]>=2.5.0
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: litellm>=1.0.0
 Requires-Dist: python-dotenv>=1.0.0
@@ -28,7 +28,7 @@ Requires-Dist: rich>=13.0.0
 Requires-Dist: textual>=0.47.0
 Requires-Dist: uvicorn>=0.30.0
 Requires-Dist: textual-serve>=1.1.0
-Requires-Dist: mcp[cli]>=1.27.1
+Requires-Dist: mcp[cli]>=1.27.1,<2
 Requires-Dist: truststore>=0.9.0
 Requires-Dist: platformdirs>=4.0.0
 Requires-Python: >=3.11
@@ -42,7 +42,7 @@ Description-Content-Type: text/markdown
 # Handler
 
 [![CI](https://github.com/alDuncanson/handler/actions/workflows/ci.yml/badge.svg)](https://github.com/alDuncanson/handler/actions/workflows/ci.yml)
-[![A2A Protocol](https://img.shields.io/badge/A2A_Protocol-v0.3.0-blue)](https://a2a-protocol.org/latest/)
+[![A2A Protocol](https://img.shields.io/badge/A2A_Protocol-v1.0.0-blue)](https://a2a-protocol.org/latest/)
 [![PyPI version](https://img.shields.io/pypi/v/a2a-handler)](https://pypi.org/project/a2a-handler/)
 [![PyPI - Status](https://img.shields.io/pypi/status/a2a-handler)](https://pypi.org/project/a2a-handler/)
 [![Pepy total downloads](https://img.shields.io/pepy/dt/a2a-handler?label=total%20downloads)](https://pepy.tech/projects/a2a-handler)

{a2a_handler-0.1.24 → a2a_handler-0.1.26}/README.md

@@ -1,7 +1,7 @@
 # Handler
 
 [![CI](https://github.com/alDuncanson/handler/actions/workflows/ci.yml/badge.svg)](https://github.com/alDuncanson/handler/actions/workflows/ci.yml)
-[![A2A Protocol](https://img.shields.io/badge/A2A_Protocol-v0.3.0-blue)](https://a2a-protocol.org/latest/)
+[![A2A Protocol](https://img.shields.io/badge/A2A_Protocol-v1.0.0-blue)](https://a2a-protocol.org/latest/)
 [![PyPI version](https://img.shields.io/pypi/v/a2a-handler)](https://pypi.org/project/a2a-handler/)
 [![PyPI - Status](https://img.shields.io/pypi/status/a2a-handler)](https://pypi.org/project/a2a-handler/)
 [![Pepy total downloads](https://img.shields.io/pepy/dt/a2a-handler?label=total%20downloads)](https://pepy.tech/projects/a2a-handler)

a2a_handler-0.1.26/pyproject.toml

@@ -0,0 +1,95 @@
+[project]
+name = "a2a-handler"
+version = "0.1.26"
+description = "An A2A Protocol client TUI and CLI."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "GPL-3.0-or-later"
+license-files = ["LICENSE"]
+keywords = [
+    "a2a",
+    "a2a-protocol",
+    "agent",
+    "agent-to-agent",
+    "ai",
+    "cli",
+    "tui",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "a2a-sdk[http-server]>=1.0.0,<2.0.0",
+    "click>=8.0.0",
+    "google-adk[mcp]>=2.5.0",
+    "httpx>=0.27.0",
+    "litellm>=1.0.0",
+    "python-dotenv>=1.0.0",
+    "rich>=13.0.0",
+    "textual>=0.47.0",
+    "uvicorn>=0.30.0",
+    "textual-serve>=1.1.0",
+    "mcp[cli]>=1.27.1,<2",
+    "truststore>=0.9.0",
+    "platformdirs>=4.0.0",
+]
+
+[[project.authors]]
+name = "Al Duncanson"
+email = "alDuncanson@proton.me"
+
+[project.urls]
+Homepage = "https://github.com/alDuncanson/handler"
+Repository = "https://github.com/alDuncanson/handler"
+Documentation = "https://github.com/alDuncanson/handler/tree/main/docs"
+Issues = "https://github.com/alDuncanson/handler/issues"
+Changelog = "https://github.com/alDuncanson/handler/releases"
+
+[project.scripts]
+handler = "a2a_handler.cli:main"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.8.0",
+    "textual-dev>=1.8.0",
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "ty>=0.0.1a27",
+    "pytest-cov>=7.1.0",
+    "pytest-textual-snapshot>=1.0.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.15,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = "src"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff.lint.per-file-ignores]
+"src/a2a_handler/cli/__init__.py" = ["E402"]
+
+[tool.coverage.run]
+source = ["a2a_handler"]
+
+[tool.coverage.report]
+show_missing = true
+skip_empty = true
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.",
+]

a2a_handler-0.1.24/pyproject.toml → a2a_handler-0.1.26/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "a2a-handler"
-version = "0.1.24"
+version = "0.1.26"
 description = "An A2A Protocol client TUI and CLI."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -32,9 +32,9 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "a2a-sdk>=0.3.24,<1.0.0",
+    "a2a-sdk[http-server]>=1.0.0,<2.0.0",
     "click>=8.0.0",
-    "google-adk>=2.0.0",
+    "google-adk[mcp]>=2.5.0",
     "httpx>=0.27.0",
     "litellm>=1.0.0",
     "python-dotenv>=1.0.0",
@@ -42,7 +42,7 @@ dependencies = [
     "textual>=0.47.0",
     "uvicorn>=0.30.0",
     "textual-serve>=1.1.0",
-    "mcp[cli]>=1.27.1",
+    "mcp[cli]>=1.27.1,<2",
     "truststore>=0.9.0",
     "platformdirs>=4.0.0",
 ]

{a2a_handler-0.1.24 → a2a_handler-0.1.26}/src/a2a_handler/cli/_helpers.py

@@ -8,8 +8,8 @@ import httpx
 import click
 from a2a.client.errors import (
     A2AClientError,
-    A2AClientHTTPError,
     A2AClientTimeoutError,
+    AgentCardResolutionError,
 )
 
 from a2a_handler.auth import (
@@ -162,15 +162,11 @@ def handle_client_error(e: Exception, agent_url: str, output: Output | None) ->
         message = "Request timed out"
         error_code = "request_timeout"
         suggestion = "Retry the request or increase timeout settings"
-    elif isinstance(e, A2AClientHTTPError):
-        log.error("A2A client error: %s", e)
-        if "connection" in str(e).lower():
-            message = f"Connection failed: Is the server running at {agent_url}?"
-            error_code = "connection_failed"
-            suggestion = "Verify the agent URL and that the server is reachable"
-        else:
-            message = str(e)
-            error_code = "a2a_http_error"
+    elif isinstance(e, AgentCardResolutionError):
+        log.error("Agent card resolution failed for %s: %s", agent_url, e)
+        message = f"Could not resolve agent card: {e}"
+        error_code = "agent_card_resolution_error"
+        suggestion = "Verify the agent URL and that the server exposes an agent card"
         details = {"agent_url": agent_url}
     elif isinstance(e, A2AClientError):
         log.error("A2A client error: %s", e)

{a2a_handler-0.1.24 → a2a_handler-0.1.26}/src/a2a_handler/cli/card.py

@@ -8,7 +8,7 @@ from a2a.types import AgentCard
 
 from a2a_handler.common import Output, get_logger
 from a2a_handler.common.input_validation import InputValidationError, validate_agent_url
-from a2a_handler.service import A2AService
+from a2a_handler.service import A2AService, to_json_dict
 from a2a_handler.validation import (
     ValidationResult,
     ValidationSource,
@@ -90,7 +90,7 @@ def _format_agent_card(card_data: object, output: Output) -> None:
     """Format and display an agent card as JSON."""
     card_dict: dict[str, Any]
     if isinstance(card_data, AgentCard):
-        card_dict = card_data.model_dump(exclude_none=True)
+        card_dict = to_json_dict(card_data)
     elif isinstance(card_data, dict):
         card_dict = {str(key): value for key, value in card_data.items()}
     else:

{a2a_handler-0.1.24 → a2a_handler-0.1.26}/src/a2a_handler/cli/message.py

@@ -2,12 +2,13 @@
 
 import asyncio
 import json
+from collections.abc import Sequence
 from dataclasses import replace
 from typing import Any
 from typing import Optional
 
 import click
-from a2a.types import DataPart, FilePart, Message, Part, Role, TextPart
+from a2a.types import Message, Part, Role
 
 from a2a_handler.auth import (
     AuthCredentials,
@@ -28,10 +29,16 @@ from a2a_handler.service import (
     A2AService,
     A2AResponse,
     StreamEvent,
+    part_data,
+    part_file,
+    part_kind,
+    part_text,
     protocol_dump,
     response_context_id,
     response_state,
     response_task_id,
+    state_label,
+    to_json_dict,
 )
 from a2a_handler.session import get_session, update_session
 
@@ -409,7 +416,7 @@ def _format_response_text(response: A2AResponse) -> str:
     lines: list[str] = []
     state = response_state(response)
     if state:
-        lines.append(f"State: {state.value}")
+        lines.append(f"State: {state_label(state)}")
     context_id = response_context_id(response)
     if context_id:
         lines.append(f"Context ID: {context_id}")
@@ -435,7 +442,7 @@ def _format_response_parts(response: A2AResponse) -> str:
 
     if not formatted_parts and response.history:
         for message in response.history:
-            if message.role == Role.agent:
+            if message.role == Role.ROLE_AGENT:
                 formatted = _format_message_parts(message)
                 if formatted:
                     formatted_parts.append(formatted)
@@ -448,10 +455,10 @@ def _format_stream_event_text(event: StreamEvent) -> str:
     if event.message:
         return _format_message_parts(event.message)
 
-    if event.status and event.status.status and event.status.status.message:
+    if event.status and event.status.status.HasField("message"):
         return _format_message_parts(event.status.status.message)
 
-    if event.artifact and event.artifact.artifact:
+    if event.artifact and event.artifact.artifact.parts:
         return _format_parts(event.artifact.artifact.parts)
 
     if event.event_type == "task" and event.task:
@@ -466,7 +473,7 @@ def _format_stream_event_summaries(event: StreamEvent) -> list[str]:
 
     if event.state:
         summaries.append(
-            _format_event_summary("task", event.state.value, event.task_id)
+            _format_event_summary("task", state_label(event.state), event.task_id)
         )
 
     parts = _stream_event_parts(event)
@@ -481,39 +488,40 @@ def _format_stream_event_summaries(event: StreamEvent) -> list[str]:
 
 def _stream_event_parts(event: StreamEvent) -> list[Part]:
     """Return the parts carried by a stream event, if any."""
-    if event.message and event.message.role == Role.agent:
-        return event.message.parts or []
-    if event.status and event.status.status and event.status.status.message:
+    if event.message and event.message.role == Role.ROLE_AGENT:
+        return list(event.message.parts)
+    if event.status and event.status.status.HasField("message"):
         message = event.status.status.message
-        if message.role == Role.agent:
-            return message.parts or []
-    if event.artifact and event.artifact.artifact:
-        return event.artifact.artifact.parts or []
+        if message.role == Role.ROLE_AGENT:
+            return list(message.parts)
+    if event.artifact and event.artifact.artifact.parts:
+        return list(event.artifact.artifact.parts)
     return []
 
 
 def _format_part_event_summaries(part: Part, task_id: str | None) -> list[str]:
     """Summarize a stream part without rendering its full content."""
-    root = part.root
-    if isinstance(root, TextPart):
+    kind = part_kind(part)
+    if kind == "text":
         return [_format_event_summary("message", "text", task_id)]
-    if isinstance(root, DataPart):
-        if _is_tool_call_data(root.data):
+    if kind == "data":
+        data = part_data(part)
+        if _is_tool_call_data(data):
             return [
                 _format_event_summary(
-                    "tool call", str(root.data.get("name", "unknown")), task_id
+                    "tool call", str(data.get("name", "unknown")), task_id
                 )
             ]
-        if _is_tool_response_data(root.data):
+        if _is_tool_response_data(data):
             return [
                 _format_event_summary(
-                    "tool result", str(root.data.get("name", "unknown")), task_id
+                    "tool result", str(data.get("name", "unknown")), task_id
                 )
             ]
         return [_format_event_summary("message", "data", task_id)]
-    if isinstance(root, FilePart):
+    if kind == "file":
         return [_format_event_summary("message", "file", task_id)]
-    return [_format_event_summary("message", getattr(root, "kind", "part"), task_id)]
+    return [_format_event_summary("message", kind, task_id)]
 
 
 def _format_event_summary(kind: str, detail: str, task_id: str | None) -> str:
@@ -542,12 +550,12 @@ def _stream_text_delta(emitted_text: str, event_text: str) -> str:
 
 def _format_message_parts(message: Message) -> str:
     """Format a protocol message's parts, skipping echoed user messages."""
-    if message.role != Role.agent:
+    if message.role != Role.ROLE_AGENT:
         return ""
     return _format_parts(message.parts)
 
 
-def _format_parts(parts: list[Part] | None) -> str:
+def _format_parts(parts: Sequence[Part] | None) -> str:
     """Format A2A message/artifact parts for human-readable CLI output."""
     if not parts:
         return ""
@@ -562,50 +570,46 @@ def _format_parts(parts: list[Part] | None) -> str:
 
 def _format_part(part: Part) -> str:
     """Format a single A2A part for human-readable CLI output."""
-    root = part.root
-    if isinstance(root, TextPart):
-        return root.text
-    if isinstance(root, DataPart):
-        return _format_data_part(root)
-    if isinstance(root, FilePart):
-        return _format_file_part(root)
+    kind = part_kind(part)
+    if kind == "text":
+        return part_text(part)
+    if kind == "data":
+        return _format_data_part(part_data(part))
+    if kind == "file":
+        return _format_file_part(part)
 
-    return "```json\n" + json.dumps(part.model_dump(mode="json"), indent=2) + "\n```"
+    return "```json\n" + json.dumps(to_json_dict(part), indent=2) + "\n```"
 
 
-def _format_data_part(part: DataPart) -> str:
+def _format_data_part(data: Any) -> str:
     """Format structured data parts while hiding internal tool chatter."""
-    data = part.data
     if _is_tool_call_data(data) or _is_tool_response_data(data):
         return ""
     return "```json\n" + json.dumps(data, indent=2, default=str) + "\n```"
 
 
-def _is_tool_call_data(data: dict[str, Any]) -> bool:
+def _is_tool_call_data(data: Any) -> bool:
     """Return whether a data part looks like an internal tool call."""
-    return {"id", "name", "args"}.issubset(data)
+    return isinstance(data, dict) and {"id", "name", "args"}.issubset(data)
 
 
-def _is_tool_response_data(data: dict[str, Any]) -> bool:
+def _is_tool_response_data(data: Any) -> bool:
     """Return whether a data part looks like an internal tool response."""
-    return {"id", "name", "response"}.issubset(data)
+    return isinstance(data, dict) and {"id", "name", "response"}.issubset(data)
 
 
-def _format_file_part(part: FilePart) -> str:
+def _format_file_part(part: Part) -> str:
     """Format file parts without dumping inline bytes into the terminal."""
-    file_part = part.file
-    name = getattr(file_part, "name", None) or "unnamed file"
-    mime_type = getattr(file_part, "mime_type", None)
-    uri = getattr(file_part, "uri", None)
-    inline_bytes = getattr(file_part, "bytes", None)
+    info = part_file(part)
+    name = info.get("name") or "unnamed file"
 
     details = [name]
-    if mime_type:
-        details.append(mime_type)
-    if uri:
-        details.append(uri)
-    elif inline_bytes:
-        details.append(f"inline bytes, {len(inline_bytes)} base64 chars")
+    if info.get("media_type"):
+        details.append(info["media_type"])
+    if info.get("uri"):
+        details.append(info["uri"])
+    elif info.get("num_bytes"):
+        details.append(f"inline bytes, {info['num_bytes']} bytes")
     return "[file: " + ", ".join(details) + "]"
 
 
@@ -617,7 +621,7 @@ def _stream_event_dump(event: StreamEvent) -> dict[str, object]:
     if event.task_id:
         data["taskId"] = event.task_id
     if event.state:
-        data["state"] = event.state.value
+        data["state"] = state_label(event.state)
     if event.text:
         data["text"] = event.text
     if event.message:

{a2a_handler-0.1.24 → a2a_handler-0.1.26}/src/a2a_handler/mcp/server.py

@@ -28,6 +28,7 @@ from a2a_handler.service import (
     push_config_dump,
     response_context_id,
     response_task_id,
+    to_json_dict,
 )
 from a2a_handler.session import (
     clear_session,
@@ -220,7 +221,7 @@ def create_mcp_server() -> FastMCP:
             service = A2AService(http_client, agent_url, credentials=credentials)
             card = await service.get_card()
 
-            return card.model_dump(exclude_none=True)
+            return to_json_dict(card)
 
     @mcp.tool()
     async def send_message(

{a2a_handler-0.1.24 → a2a_handler-0.1.26}/src/a2a_handler/server/__init__.py

@@ -60,13 +60,9 @@ def run_server(
     agent = create_llm_agent(model=effective_model)
     agent_card = build_agent_card(agent, host, port, require_auth=require_auth)
 
-    streaming_enabled = (
-        agent_card.capabilities.streaming if agent_card.capabilities else False
-    )
-    push_notifications_enabled = (
-        agent_card.capabilities.push_notifications if agent_card.capabilities else False
-    )
-    auth_enabled = agent_card.security_schemes is not None
+    streaming_enabled = bool(agent_card.capabilities.streaming)
+    push_notifications_enabled = bool(agent_card.capabilities.push_notifications)
+    auth_enabled = bool(agent_card.security_schemes)
 
     logger.info(
         "Agent card capabilities: streaming=%s, push_notifications=%s, auth=%s",

{a2a_handler-0.1.24 → a2a_handler-0.1.26}/src/a2a_handler/server/app.py

@@ -5,15 +5,16 @@ from collections.abc import AsyncIterator, Awaitable, Callable
 from contextlib import asynccontextmanager
 
 import httpx
-from a2a.server.apps import A2AStarletteApplication
+from a2a.server.context import ServerCallContext
 from a2a.server.request_handlers import DefaultRequestHandler
+from a2a.server.routes import create_agent_card_routes, create_jsonrpc_routes
 from a2a.server.tasks import (
     BasePushNotificationSender,
     InMemoryPushNotificationConfigStore,
     InMemoryTaskStore,
 )
-from a2a.types import AgentCard, InvalidParamsError, PushNotificationConfig
-from a2a.utils.errors import ServerError
+from a2a.types import AgentCard, TaskPushNotificationConfig
+from a2a.utils.errors import InvalidParamsError
 from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor
 from google.adk.agents.llm_agent import Agent
 from google.adk.artifacts.in_memory_artifact_service import InMemoryArtifactService
@@ -48,7 +49,8 @@ class ValidatingPushNotificationConfigStore(InMemoryPushNotificationConfigStore)
     async def set_info(
         self,
         task_id: str,
-        notification_config: PushNotificationConfig,
+        notification_config: TaskPushNotificationConfig,
+        context: ServerCallContext,
     ) -> None:
         """Validate webhook settings before storing push configuration."""
         try:
@@ -57,13 +59,11 @@ class ValidatingPushNotificationConfigStore(InMemoryPushNotificationConfigStore)
             if notification_config.token:
                 reject_control_chars(notification_config.token, "webhook_token")
         except InputValidationError as error:
-            raise ServerError(
-                error=InvalidParamsError(
-                    message=f"{error.code}: {error.message}",
-                )
+            raise InvalidParamsError(
+                message=f"{error.code}: {error.message}",
             ) from error
 
-        await super().set_info(task_id, notification_config)
+        await super().set_info(task_id, notification_config, context)
 
 
 def generate_api_key() -> str:
@@ -186,6 +186,7 @@ def create_a2a_application(
     request_handler = DefaultRequestHandler(
         agent_executor=agent_executor,
         task_store=task_store,
+        agent_card=agent_card,
         push_config_store=push_notification_config_store,
         push_sender=push_notification_sender,
     )
@@ -196,13 +197,13 @@ def create_a2a_application(
             Middleware(APIKeyAuthMiddleware, api_key=api_key)  # type: ignore[arg-type]
         )
 
-    async def setup_a2a_routes(application: Starlette) -> None:
-        a2a_starlette_app = A2AStarletteApplication(
-            agent_card=agent_card,
-            http_handler=request_handler,
-        )
-        a2a_starlette_app.add_routes_to_app(application)
-        logger.info("A2A routes configured with push notification support")
+    # Serve the agent card plus a JSON-RPC endpoint. ``enable_v0_3_compat``
+    # lets legacy v0.3 clients call the same endpoint as v1.0 clients.
+    routes = [
+        *create_agent_card_routes(agent_card),
+        *create_jsonrpc_routes(request_handler, rpc_url="/", enable_v0_3_compat=True),
+    ]
+    logger.info("A2A routes configured with push notification support")
 
     async def cleanup_http_client() -> None:
         await http_client.aclose()
@@ -210,12 +211,11 @@ def create_a2a_application(
 
     @asynccontextmanager
     async def lifespan(application: Starlette) -> AsyncIterator[None]:
-        await setup_a2a_routes(application)
         try:
             yield
         finally:
             await cleanup_http_client()
 
-    application = Starlette(middleware=middleware, lifespan=lifespan)
+    application = Starlette(routes=routes, middleware=middleware, lifespan=lifespan)
 
     return application

{a2a_handler-0.1.24 → a2a_handler-0.1.26}/src/a2a_handler/server/card.py

@@ -5,10 +5,17 @@ from importlib.metadata import version as package_version
 from a2a.types import (
     AgentCapabilities,
     AgentCard,
+    AgentInterface,
     AgentSkill,
     APIKeySecurityScheme,
-    In,
+    SecurityRequirement,
     SecurityScheme,
+    StringList,
+)
+from a2a.utils.constants import (
+    PROTOCOL_VERSION_0_3,
+    PROTOCOL_VERSION_1_0,
+    TransportProtocol,
 )
 from google.adk.agents.llm_agent import Agent
 
@@ -25,6 +32,9 @@ def build_agent_card(
 ) -> AgentCard:
     """Build an AgentCard with streaming and push notification capabilities.
 
+    The card advertises both A2A v1.0 and v0.3 JSON-RPC interfaces so that
+    both current and legacy clients can connect to the built-in server.
+
     Args:
         agent: The ADK agent
         host: Host address for the RPC URL
@@ -111,30 +121,44 @@ def build_agent_card(
 
     logger.debug("Building agent card with RPC URL: %s", rpc_endpoint_url)
 
-    security_schemes: dict[str, SecurityScheme] | None = None
-    security: list[dict[str, list[str]]] | None = None
+    # Advertise both protocol versions on the same JSON-RPC endpoint so v0.3
+    # clients keep working alongside v1.0 clients.
+    supported_interfaces = [
+        AgentInterface(
+            url=rpc_endpoint_url,
+            protocol_binding=TransportProtocol.JSONRPC.value,
+            protocol_version=PROTOCOL_VERSION_1_0,
+        ),
+        AgentInterface(
+            url=rpc_endpoint_url,
+            protocol_binding=TransportProtocol.JSONRPC.value,
+            protocol_version=PROTOCOL_VERSION_0_3,
+        ),
+    ]
+
+    card_kwargs: dict = {
+        "name": agent.name,
+        "description": agent.description or "Handler A2A agent",
+        "version": package_version("a2a-handler"),
+        "supported_interfaces": supported_interfaces,
+        "capabilities": agent_capabilities,
+        "skills": skills,
+        "default_input_modes": ["text/plain"],
+        "default_output_modes": ["text/plain"],
+    }
 
     if require_auth:
-        api_key_scheme = SecurityScheme(
-            root=APIKeySecurityScheme(
-                type="apiKey",
-                name="X-API-Key",
-                in_=In.header,
+        card_kwargs["security_schemes"] = {
+            "apiKey": SecurityScheme(
+                api_key_security_scheme=APIKeySecurityScheme(
+                    name="X-API-Key",
+                    location="header",
+                )
             )
-        )
-        security_schemes = {"apiKey": api_key_scheme}
-        security = [{"apiKey": []}]
+        }
+        card_kwargs["security_requirements"] = [
+            SecurityRequirement(schemes={"apiKey": StringList()})
+        ]
         logger.info("API key authentication enabled")
 
-    return AgentCard(
-        name=agent.name,
-        description=agent.description or "Handler A2A agent",
-        url=rpc_endpoint_url,
-        version=package_version("a2a-handler"),
-        capabilities=agent_capabilities,
-        skills=skills,
-        default_input_modes=["text/plain"],
-        default_output_modes=["text/plain"],
-        security_schemes=security_schemes,
-        security=security,
-    )
+    return AgentCard(**card_kwargs)