refactor: cleanup legacy agent card paths (#750)

- Remove `/agent/authenticatedExtendedCard` and
`/.well-known/agent.json` support.
- Remove `A2AException` - it doesn't exist on `main` and it was some
intermediate `1.0-dev` state during development.

Re #701

Author: ishymko

src/a2a/server/apps/jsonrpc/fastapi_app.py

@@ -30,8 +30,6 @@
 from a2a.utils.constants import (
     AGENT_CARD_WELL_KNOWN_PATH,
     DEFAULT_RPC_URL,
-    EXTENDED_AGENT_CARD_PATH,
-    PREV_AGENT_CARD_WELL_KNOWN_PATH,
 )
 
 
@@ -137,15 +135,13 @@ def add_routes_to_app(
         app: FastAPI,
         agent_card_url: str = AGENT_CARD_WELL_KNOWN_PATH,
         rpc_url: str = DEFAULT_RPC_URL,
-        extended_agent_card_url: str = EXTENDED_AGENT_CARD_PATH,
     ) -> None:
         """Adds the routes to the FastAPI application.
 
         Args:
             app: The FastAPI application to add the routes to.
             agent_card_url: The URL for the agent card endpoint.
             rpc_url: The URL for the A2A JSON-RPC endpoint.
-            extended_agent_card_url: The URL for the authenticated extended agent card endpoint.
         """
         app.post(
             rpc_url,
@@ -165,40 +161,24 @@ def add_routes_to_app(
         )(self._handle_requests)
         app.get(agent_card_url)(self._handle_get_agent_card)
 
-        if agent_card_url == AGENT_CARD_WELL_KNOWN_PATH:
-            # For backward compatibility, serve the agent card at the deprecated path as well.
-            # TODO: remove in a future release
-            app.get(PREV_AGENT_CARD_WELL_KNOWN_PATH)(
-                self._handle_get_agent_card
-            )
-
-        if self.agent_card.capabilities.extended_agent_card:
-            app.get(extended_agent_card_url)(
-                self._handle_get_authenticated_extended_agent_card
-            )
-
     def build(
         self,
         agent_card_url: str = AGENT_CARD_WELL_KNOWN_PATH,
         rpc_url: str = DEFAULT_RPC_URL,
-        extended_agent_card_url: str = EXTENDED_AGENT_CARD_PATH,
         **kwargs: Any,
     ) -> FastAPI:
         """Builds and returns the FastAPI application instance.
 
         Args:
             agent_card_url: The URL for the agent card endpoint.
             rpc_url: The URL for the A2A JSON-RPC endpoint.
-            extended_agent_card_url: The URL for the authenticated extended agent card endpoint.
             **kwargs: Additional keyword arguments to pass to the FastAPI constructor.
 
         Returns:
             A configured FastAPI application instance.
         """
         app = A2AFastAPI(**kwargs)
 
-        self.add_routes_to_app(
-            app, agent_card_url, rpc_url, extended_agent_card_url
-        )
+        self.add_routes_to_app(app, agent_card_url, rpc_url)
 
         return app

src/a2a/server/apps/jsonrpc/jsonrpc_app.py

@@ -47,11 +47,9 @@
 from a2a.utils.constants import (
     AGENT_CARD_WELL_KNOWN_PATH,
     DEFAULT_RPC_URL,
-    EXTENDED_AGENT_CARD_PATH,
-    PREV_AGENT_CARD_WELL_KNOWN_PATH,
 )
 from a2a.utils.errors import (
-    A2AException,
+    A2AError,
     MethodNotImplementedError,
     UnsupportedOperationError,
 )
@@ -247,7 +245,7 @@ def __init__(  # noqa: PLR0913
     def _generate_error_response(
         self,
         request_id: str | int | None,
-        error: Exception | JSONRPCError | A2AException,
+        error: Exception | JSONRPCError | A2AError,
     ) -> JSONResponse:
         """Creates a Starlette JSONResponse for a JSON-RPC error.
 
@@ -260,7 +258,7 @@ def _generate_error_response(
         Returns:
             A `JSONResponse` object formatted as a JSON-RPC error response.
         """
-        if not isinstance(error, A2AException | JSONRPCError):
+        if not isinstance(error, A2AError | JSONRPCError):
             error = InternalError(message=str(error))
 
         response_data = build_error_response(request_id, error)
@@ -578,14 +576,6 @@ async def _handle_get_agent_card(self, request: Request) -> JSONResponse:
         Returns:
             A JSONResponse containing the agent card data.
         """
-        if request.url.path == PREV_AGENT_CARD_WELL_KNOWN_PATH:
-            logger.warning(
-                "Deprecated agent card endpoint '%s' accessed. "
-                "Please use '%s' instead. This endpoint will be removed in a future version.",
-                PREV_AGENT_CARD_WELL_KNOWN_PATH,
-                AGENT_CARD_WELL_KNOWN_PATH,
-            )
-
         card_to_serve = self.agent_card
         if self.card_modifier:
             card_to_serve = await maybe_await(self.card_modifier(card_to_serve))
@@ -597,62 +587,18 @@ async def _handle_get_agent_card(self, request: Request) -> JSONResponse:
             )
         )
 
-    async def _handle_get_authenticated_extended_agent_card(
-        self, request: Request
-    ) -> JSONResponse:
-        """Handles GET requests for the authenticated extended agent card."""
-        logger.warning(
-            'HTTP GET for authenticated extended card has been called by a client. '
-            'This endpoint is deprecated in favor of agent/authenticatedExtendedCard JSON-RPC method and will be removed in a future release.'
-        )
-        if not self.agent_card.capabilities.extended_agent_card:
-            return JSONResponse(
-                {'error': 'Extended agent card not supported or not enabled.'},
-                status_code=404,
-            )
-
-        card_to_serve = self.extended_agent_card
-
-        if self.extended_card_modifier:
-            context = self._context_builder.build(request)
-            # If no base extended card is provided, pass the public card to the modifier
-            base_card = card_to_serve if card_to_serve else self.agent_card
-            card_to_serve = await maybe_await(
-                self.extended_card_modifier(base_card, context)
-            )
-
-        if card_to_serve:
-            return JSONResponse(
-                MessageToDict(
-                    card_to_serve,
-                    preserving_proto_field_name=False,
-                )
-            )
-        # If capabilities.extended_agent_card is true, but no
-        # extended_agent_card was provided, and no modifier produced a card,
-        # return a 404.
-        return JSONResponse(
-            {
-                'error': 'Authenticated extended agent card is supported but not configured on the server.'
-            },
-            status_code=404,
-        )
-
     @abstractmethod
     def build(
         self,
         agent_card_url: str = AGENT_CARD_WELL_KNOWN_PATH,
         rpc_url: str = DEFAULT_RPC_URL,
-        extended_agent_card_url: str = EXTENDED_AGENT_CARD_PATH,
         **kwargs: Any,
     ) -> FastAPI | Starlette:
         """Builds and returns the JSONRPC application instance.
 
         Args:
             agent_card_url: The URL for the agent card endpoint.
             rpc_url: The URL for the A2A JSON-RPC endpoint.
-            extended_agent_card_url: The URL for the authenticated extended
-              agent card endpoint.
             **kwargs: Additional keyword arguments to pass to the FastAPI constructor.
 
         Returns:

src/a2a/server/apps/jsonrpc/starlette_app.py

@@ -32,8 +32,6 @@
 from a2a.utils.constants import (
     AGENT_CARD_WELL_KNOWN_PATH,
     DEFAULT_RPC_URL,
-    EXTENDED_AGENT_CARD_PATH,
-    PREV_AGENT_CARD_WELL_KNOWN_PATH,
 )
 
 
@@ -101,19 +99,17 @@ def routes(
         self,
         agent_card_url: str = AGENT_CARD_WELL_KNOWN_PATH,
         rpc_url: str = DEFAULT_RPC_URL,
-        extended_agent_card_url: str = EXTENDED_AGENT_CARD_PATH,
     ) -> list[Route]:
         """Returns the Starlette Routes for handling A2A requests.
 
         Args:
             agent_card_url: The URL path for the agent card endpoint.
             rpc_url: The URL path for the A2A JSON-RPC endpoint (POST requests).
-            extended_agent_card_url: The URL for the authenticated extended agent card endpoint.
 
         Returns:
             A list of Starlette Route objects.
         """
-        app_routes = [
+        return [
             Route(
                 rpc_url,
                 self._handle_requests,
@@ -128,74 +124,43 @@ def routes(
             ),
         ]
 
-        if agent_card_url == AGENT_CARD_WELL_KNOWN_PATH:
-            # For backward compatibility, serve the agent card at the deprecated path as well.
-            # TODO: remove in a future release
-            app_routes.append(
-                Route(
-                    PREV_AGENT_CARD_WELL_KNOWN_PATH,
-                    self._handle_get_agent_card,
-                    methods=['GET'],
-                    name='deprecated_agent_card',
-                )
-            )
-
-        # TODO: deprecated endpoint to be removed in a future release
-        if self.agent_card.capabilities.extended_agent_card:
-            app_routes.append(
-                Route(
-                    extended_agent_card_url,
-                    self._handle_get_authenticated_extended_agent_card,
-                    methods=['GET'],
-                    name='authenticated_extended_agent_card',
-                )
-            )
-        return app_routes
-
     def add_routes_to_app(
         self,
         app: Starlette,
         agent_card_url: str = AGENT_CARD_WELL_KNOWN_PATH,
         rpc_url: str = DEFAULT_RPC_URL,
-        extended_agent_card_url: str = EXTENDED_AGENT_CARD_PATH,
     ) -> None:
         """Adds the routes to the Starlette application.
 
         Args:
             app: The Starlette application to add the routes to.
             agent_card_url: The URL path for the agent card endpoint.
             rpc_url: The URL path for the A2A JSON-RPC endpoint (POST requests).
-            extended_agent_card_url: The URL for the authenticated extended agent card endpoint.
         """
         routes = self.routes(
             agent_card_url=agent_card_url,
             rpc_url=rpc_url,
-            extended_agent_card_url=extended_agent_card_url,
         )
         app.routes.extend(routes)
 
     def build(
         self,
         agent_card_url: str = AGENT_CARD_WELL_KNOWN_PATH,
         rpc_url: str = DEFAULT_RPC_URL,
-        extended_agent_card_url: str = EXTENDED_AGENT_CARD_PATH,
         **kwargs: Any,
     ) -> Starlette:
         """Builds and returns the Starlette application instance.
 
         Args:
             agent_card_url: The URL path for the agent card endpoint.
             rpc_url: The URL path for the A2A JSON-RPC endpoint (POST requests).
-            extended_agent_card_url: The URL for the authenticated extended agent card endpoint.
             **kwargs: Additional keyword arguments to pass to the Starlette constructor.
 
         Returns:
             A configured Starlette application instance.
         """
         app = Starlette(**kwargs)
 
-        self.add_routes_to_app(
-            app, agent_card_url, rpc_url, extended_agent_card_url
-        )
+        self.add_routes_to_app(app, agent_card_url, rpc_url)
 
         return app

src/a2a/server/request_handlers/jsonrpc_handler.py

@@ -33,7 +33,7 @@
 )
 from a2a.utils import proto_utils
 from a2a.utils.errors import (
-    A2AException,
+    A2AError,
     AuthenticatedExtendedCardNotConfiguredError,
     ContentTypeNotSupportedError,
     InternalError,
@@ -54,7 +54,7 @@
 logger = logging.getLogger(__name__)
 
 
-EXCEPTION_MAP: dict[type[A2AException], type[JSONRPCError]] = {
+EXCEPTION_MAP: dict[type[A2AError], type[JSONRPCError]] = {
     TaskNotFoundError: JSONRPCError,
     TaskNotCancelableError: JSONRPCError,
     PushNotificationNotSupportedError: JSONRPCError,
@@ -68,7 +68,7 @@
     MethodNotFoundError: JSONRPCError,
 }
 
-ERROR_CODE_MAP: dict[type[A2AException], int] = {
+ERROR_CODE_MAP: dict[type[A2AError], int] = {
     TaskNotFoundError: -32001,
     TaskNotCancelableError: -32002,
     PushNotificationNotSupportedError: -32003,
@@ -94,7 +94,7 @@ def _build_error_response(
 ) -> dict[str, Any]:
     """Build a JSON-RPC error response dict."""
     jsonrpc_error: JSONRPCError
-    if isinstance(error, A2AException):
+    if isinstance(error, A2AError):
         error_type = type(error)
         model_class = EXCEPTION_MAP.get(error_type, JSONRPCInternalError)
         code = ERROR_CODE_MAP.get(error_type, -32603)

src/a2a/server/request_handlers/response_helpers.py

@@ -25,7 +25,7 @@
     SendMessageResponse as SendMessageResponseProto,
 )
 from a2a.utils.errors import (
-    A2AException,
+    A2AError,
     AuthenticatedExtendedCardNotConfiguredError,
     ContentTypeNotSupportedError,
     InternalError,
@@ -40,7 +40,7 @@
 )
 
 
-EXCEPTION_MAP: dict[type[A2AException], type[JSONRPCError]] = {
+EXCEPTION_MAP: dict[type[A2AError], type[JSONRPCError]] = {
     TaskNotFoundError: JSONRPCError,
     TaskNotCancelableError: JSONRPCError,
     PushNotificationNotSupportedError: JSONRPCError,
@@ -54,7 +54,7 @@
     InternalError: JSONRPCInternalError,
 }
 
-ERROR_CODE_MAP: dict[type[A2AException], int] = {
+ERROR_CODE_MAP: dict[type[A2AError], int] = {
     TaskNotFoundError: -32001,
     TaskNotCancelableError: -32002,
     PushNotificationNotSupportedError: -32003,
@@ -69,7 +69,7 @@
 
 
 # Tuple of all A2AError types for isinstance checks
-_A2A_ERROR_TYPES: tuple[type, ...] = (A2AException,)
+_A2A_ERROR_TYPES: tuple[type, ...] = (A2AError,)
 
 
 # Result types for handler responses
@@ -81,7 +81,7 @@
     | TaskPushNotificationConfig
     | StreamResponse
     | SendMessageResponseProto
-    | A2AException
+    | A2AError
     | JSONRPCError
     | list[TaskPushNotificationConfig]
     | ListTasksResponse
@@ -91,21 +91,21 @@
 
 def build_error_response(
     request_id: str | int | None,
-    error: A2AException | JSONRPCError,
+    error: A2AError | JSONRPCError,
 ) -> dict[str, Any]:
     """Build a JSON-RPC error response dict.
 
     Args:
         request_id: The ID of the request that caused the error.
-        error: The A2AException or JSONRPCError object.
+        error: The A2AError or JSONRPCError object.
 
     Returns:
         A dict representing the JSON-RPC error response.
     """
     jsonrpc_error: JSONRPCError
     if isinstance(error, JSONRPCError):
         jsonrpc_error = error
-    elif isinstance(error, A2AException):
+    elif isinstance(error, A2AError):
         error_type = type(error)
         model_class = EXCEPTION_MAP.get(error_type, JSONRPCInternalError)
         code = ERROR_CODE_MAP.get(error_type, -32603)
@@ -145,7 +145,7 @@ def prepare_response_object(
             result = MessageToDict(response, preserving_proto_field_name=False)
         return JSONRPC20Response(result=result, _id=request_id).data
 
-    if isinstance(response, A2AException | JSONRPCError):
+    if isinstance(response, A2AError | JSONRPCError):
         return build_error_response(request_id, response)
 
     # If response is not an expected success type and not an error,