feat: support for authenticated extended card method

Author: kthota-g

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

@@ -89,6 +89,7 @@ def add_routes_to_app(
         )(self._handle_requests)
         app.get(agent_card_url)(self._handle_get_agent_card)
 
+        # TODO: deprecated endpoint to be removed in a future release
         if self.agent_card.supports_authenticated_extended_card:
             app.get(extended_agent_card_url)(
                 self._handle_get_authenticated_extended_agent_card

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

@@ -32,13 +32,15 @@
     AgentCard,
     CancelTaskRequest,
     DeleteTaskPushNotificationConfigRequest,
+    GetAuthenticatedExtendedCardRequest,
     GetTaskPushNotificationConfigRequest,
     GetTaskRequest,
     InternalError,
     InvalidRequestError,
     JSONParseError,
     JSONRPCError,
     JSONRPCErrorResponse,
+    JSONRPCRequest,
     JSONRPCResponse,
     ListTaskPushNotificationConfigRequest,
     SendMessageRequest,
@@ -142,7 +144,9 @@ def __init__(
         self.agent_card = agent_card
         self.extended_agent_card = extended_agent_card
         self.handler = JSONRPCHandler(
-            agent_card=agent_card, request_handler=http_handler
+            agent_card=agent_card,
+            request_handler=http_handler,
+            extended_agent_card=extended_agent_card,
         )
         if (
             self.agent_card.supports_authenticated_extended_card
@@ -212,7 +216,16 @@ async def _handle_requests(self, request: Request) -> Response:  # noqa: PLR0911
 
         try:
             body = await request.json()
+            if isinstance(body, dict):
+                request_id = body.get('id')
+
+            # First, validate the basic JSON-RPC structure. This is crucial
+            # because the A2ARequest model is a discriminated union where some
+            # request types have default values for the 'method' field
+            JSONRPCRequest.model_validate(body)
+
             a2a_request = A2ARequest.model_validate(body)
+
             call_context = self._context_builder.build(request)
 
             request_id = a2a_request.root.id
@@ -352,6 +365,13 @@ async def _process_non_streaming_request(
                         context,
                     )
                 )
+            case GetAuthenticatedExtendedCardRequest():
+                handler_result = (
+                    await self.handler.get_authenticated_extended_card(
+                        request_obj,
+                        context,
+                    )
+                )
             case _:
                 logger.error(
                     f'Unhandled validated request type: {type(request_obj)}'
@@ -440,6 +460,10 @@ 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.supports_authenticated_extended_card:
             return JSONResponse(
                 {'error': 'Extended agent card not supported or not enabled.'},

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

@@ -86,6 +86,7 @@ def routes(
             ),
         ]
 
+        # TODO: deprecated endpoint to be removed in a future release
         if self.agent_card.supports_authenticated_extended_card:
             app_routes.append(
                 Route(

src/a2a/server/request_handlers/jsonrpc_handler.py

@@ -7,12 +7,16 @@
 from a2a.server.request_handlers.response_helpers import prepare_response_object
 from a2a.types import (
     AgentCard,
+    AuthenticatedExtendedCardNotConfiguredError,
     CancelTaskRequest,
     CancelTaskResponse,
     CancelTaskSuccessResponse,
     DeleteTaskPushNotificationConfigRequest,
     DeleteTaskPushNotificationConfigResponse,
     DeleteTaskPushNotificationConfigSuccessResponse,
+    GetAuthenticatedExtendedCardRequest,
+    GetAuthenticatedExtendedCardResponse,
+    GetAuthenticatedExtendedCardSuccessResponse,
     GetTaskPushNotificationConfigRequest,
     GetTaskPushNotificationConfigResponse,
     GetTaskPushNotificationConfigSuccessResponse,
@@ -57,15 +61,18 @@ def __init__(
         self,
         agent_card: AgentCard,
         request_handler: RequestHandler,
+        extended_agent_card: AgentCard | None = None,
     ):
         """Initializes the JSONRPCHandler.
 
         Args:
             agent_card: The AgentCard describing the agent's capabilities.
             request_handler: The underlying `RequestHandler` instance to delegate requests to.
+            extended_agent_card: An optional, distinct Extended AgentCard to be served
         """
         self.agent_card = agent_card
         self.request_handler = request_handler
+        self.extended_agent_card = extended_agent_card
 
     async def on_message_send(
         self,
@@ -395,3 +402,31 @@ async def delete_push_notification_config(
                     id=request.id, error=e.error if e.error else InternalError()
                 )
             )
+
+    async def get_authenticated_extended_card(
+        self,
+        request: GetAuthenticatedExtendedCardRequest,
+        context: ServerCallContext | None = None,
+    ) -> GetAuthenticatedExtendedCardResponse:
+        """Handles the 'agent/authenticatedExtendedCard' JSON-RPC method.
+
+        Args:
+            request: The incoming `GetAuthenticatedExtendedCardRequest` object.
+            context: Context provided by the server.
+
+        Returns:
+            A `GetAuthenticatedExtendedCardResponse` object containing the config or a JSON-RPC error.
+        """
+        if self.extended_agent_card is None:
+            return GetAuthenticatedExtendedCardResponse(
+                root=JSONRPCErrorResponse(
+                    id=request.id,
+                    error=AuthenticatedExtendedCardNotConfiguredError(),
+                )
+            )
+
+        return GetAuthenticatedExtendedCardResponse(
+            root=GetAuthenticatedExtendedCardSuccessResponse(
+                id=request.id, result=self.extended_agent_card
+            )
+        )

src/a2a/types.py

@@ -172,6 +172,27 @@ class AgentSkill(A2ABaseModel):
     """
 
 
+class AuthenticatedExtendedCardNotConfiguredError(A2ABaseModel):
+    """
+    An A2A-specific error indicating that the agent does not have an
+    Authenticated Extended Card configured
+    """
+
+    code: Literal[-32007] = -32007
+    """
+    The error code for when an authenticated extended card is not configured.
+    """
+    data: Any | None = None
+    """
+    A primitive or structured value containing additional information about the error.
+    This may be omitted.
+    """
+    message: str | None = 'Authenticated Extended Card not configured'
+    """
+    The error message.
+    """
+
+
 class AuthorizationCodeOAuthFlow(A2ABaseModel):
     """
     Defines configuration details for the OAuth 2.0 Authorization Code flow.
@@ -375,6 +396,27 @@ class FileWithUri(A2ABaseModel):
     """
 
 
+class GetAuthenticatedExtendedCardRequest(A2ABaseModel):
+    """
+    Represents a JSON-RPC request for the `agent/authenticatedExtendedCard` method.
+    """
+
+    id: str | int
+    """
+    The identifier for this request.
+    """
+    jsonrpc: Literal['2.0'] = '2.0'
+    """
+    The version of the JSON-RPC protocol. MUST be exactly "2.0".
+    """
+    method: Literal['agent/authenticatedExtendedCard'] = (
+        'agent/authenticatedExtendedCard'
+    )
+    """
+    The method name. Must be 'agent/authenticatedExtendedCard'.
+    """
+
+
 class GetTaskPushNotificationConfigParams(A2ABaseModel):
     """
     Defines parameters for fetching a specific push notification configuration for a task.
@@ -999,6 +1041,7 @@ class A2AError(
         | UnsupportedOperationError
         | ContentTypeNotSupportedError
         | InvalidAgentResponseError
+        | AuthenticatedExtendedCardNotConfiguredError
     ]
 ):
     root: (
@@ -1013,6 +1056,7 @@ class A2AError(
         | UnsupportedOperationError
         | ContentTypeNotSupportedError
         | InvalidAgentResponseError
+        | AuthenticatedExtendedCardNotConfiguredError
     )
     """
     A discriminated union of all standard JSON-RPC and A2A-specific error types.
@@ -1170,6 +1214,7 @@ class JSONRPCErrorResponse(A2ABaseModel):
         | UnsupportedOperationError
         | ContentTypeNotSupportedError
         | InvalidAgentResponseError
+        | AuthenticatedExtendedCardNotConfiguredError
     )
     """
     An object describing the error that occurred.
@@ -1625,6 +1670,7 @@ class A2ARequest(
         | TaskResubscriptionRequest
         | ListTaskPushNotificationConfigRequest
         | DeleteTaskPushNotificationConfigRequest
+        | GetAuthenticatedExtendedCardRequest
     ]
 ):
     root: (
@@ -1637,6 +1683,7 @@ class A2ARequest(
         | TaskResubscriptionRequest
         | ListTaskPushNotificationConfigRequest
         | DeleteTaskPushNotificationConfigRequest
+        | GetAuthenticatedExtendedCardRequest
     )
     """
     A discriminated union representing all possible JSON-RPC 2.0 requests supported by the A2A specification.
@@ -1750,6 +1797,25 @@ class AgentCard(A2ABaseModel):
     """
 
 
+class GetAuthenticatedExtendedCardSuccessResponse(A2ABaseModel):
+    """
+    Represents a successful JSON-RPC response for the `agent/authenticatedExtendedCard` method.
+    """
+
+    id: str | int | None = None
+    """
+    The identifier established by the client.
+    """
+    jsonrpc: Literal['2.0'] = '2.0'
+    """
+    The version of the JSON-RPC protocol. MUST be exactly "2.0".
+    """
+    result: AgentCard
+    """
+    The result is an Agent Card object.
+    """
+
+
 class Task(A2ABaseModel):
     """
     Represents a single, stateful operation or conversation between a client and an agent.
@@ -1769,7 +1835,7 @@ class Task(A2ABaseModel):
     """
     id: str
     """
-    A unique identifier for the task, generated by the client for a new task or provided by the agent.
+    A unique identifier for the task, generated by the server for a new task.
     """
     kind: Literal['task'] = 'task'
     """
@@ -1804,6 +1870,17 @@ class CancelTaskSuccessResponse(A2ABaseModel):
     """
 
 
+class GetAuthenticatedExtendedCardResponse(
+    RootModel[
+        JSONRPCErrorResponse | GetAuthenticatedExtendedCardSuccessResponse
+    ]
+):
+    root: JSONRPCErrorResponse | GetAuthenticatedExtendedCardSuccessResponse
+    """
+    Represents a JSON-RPC response for the `agent/authenticatedExtendedCard` method.
+    """
+
+
 class GetTaskSuccessResponse(A2ABaseModel):
     """
     Represents a successful JSON-RPC response for the `tasks/get` method.
@@ -1889,6 +1966,7 @@ class JSONRPCResponse(
         | GetTaskPushNotificationConfigSuccessResponse
         | ListTaskPushNotificationConfigSuccessResponse
         | DeleteTaskPushNotificationConfigSuccessResponse
+        | GetAuthenticatedExtendedCardSuccessResponse
     ]
 ):
     root: (
@@ -1901,6 +1979,7 @@ class JSONRPCResponse(
         | GetTaskPushNotificationConfigSuccessResponse
         | ListTaskPushNotificationConfigSuccessResponse
         | DeleteTaskPushNotificationConfigSuccessResponse
+        | GetAuthenticatedExtendedCardSuccessResponse
     )
     """
     A discriminated union representing all possible JSON-RPC 2.0 responses

tests/server/request_handlers/test_jsonrpc_handler.py

@@ -27,11 +27,15 @@
     AgentCapabilities,
     AgentCard,
     Artifact,
+    AuthenticatedExtendedCardNotConfiguredError,
     CancelTaskRequest,
     CancelTaskSuccessResponse,
     DeleteTaskPushNotificationConfigParams,
     DeleteTaskPushNotificationConfigRequest,
     DeleteTaskPushNotificationConfigSuccessResponse,
+    GetAuthenticatedExtendedCardRequest,
+    GetAuthenticatedExtendedCardResponse,
+    GetAuthenticatedExtendedCardSuccessResponse,
     GetTaskPushNotificationConfigParams,
     GetTaskPushNotificationConfigRequest,
     GetTaskPushNotificationConfigResponse,
@@ -1189,3 +1193,59 @@ async def test_on_delete_push_notification_error(self) -> None:
         # Assert
         self.assertIsInstance(response.root, JSONRPCErrorResponse)
         self.assertEqual(response.root.error, UnsupportedOperationError())  # type: ignore
+
+    async def test_get_authenticated_extended_card_success(self) -> None:
+        """Test successful retrieval of the authenticated extended agent card."""
+        # Arrange
+        mock_request_handler = AsyncMock(spec=DefaultRequestHandler)
+        mock_extended_card = AgentCard(
+            name='Extended Card',
+            description='More details',
+            url='http://agent.example.com/api',
+            version='1.1',
+            capabilities=AgentCapabilities(),
+            default_input_modes=['text/plain'],
+            default_output_modes=['application/json'],
+            skills=[],
+        )
+        handler = JSONRPCHandler(
+            self.mock_agent_card,
+            mock_request_handler,
+            extended_agent_card=mock_extended_card,
+        )
+        request = GetAuthenticatedExtendedCardRequest(id='ext-card-req-1')
+        call_context = ServerCallContext(state={'foo': 'bar'})
+
+        # Act
+        response: GetAuthenticatedExtendedCardResponse = (
+            await handler.get_authenticated_extended_card(request, call_context)
+        )
+
+        # Assert
+        self.assertIsInstance(
+            response.root, GetAuthenticatedExtendedCardSuccessResponse
+        )
+        self.assertEqual(response.root.id, 'ext-card-req-1')
+        self.assertEqual(response.root.result, mock_extended_card)
+
+    async def test_get_authenticated_extended_card_not_configured(self) -> None:
+        """Test error when authenticated extended agent card is not configured."""
+        # Arrange
+        mock_request_handler = AsyncMock(spec=DefaultRequestHandler)
+        handler = JSONRPCHandler(
+            self.mock_agent_card, mock_request_handler, extended_agent_card=None
+        )
+        request = GetAuthenticatedExtendedCardRequest(id='ext-card-req-2')
+        call_context = ServerCallContext(state={'foo': 'bar'})
+
+        # Act
+        response: GetAuthenticatedExtendedCardResponse = (
+            await handler.get_authenticated_extended_card(request, call_context)
+        )
+
+        # Assert
+        self.assertIsInstance(response.root, JSONRPCErrorResponse)
+        self.assertEqual(response.root.id, 'ext-card-req-2')
+        self.assertIsInstance(
+            response.root.error, AuthenticatedExtendedCardNotConfiguredError
+        )