Merge branch 'main' into auto-update-a2a-types-e162c0c6c4f609d2f4eef9042466d176ec75ebda

holtskinner · web-flow · commit 3b581d171ef9 · 2025-07-29T20:54:36.000+01:00
diff --git a/src/a2a/server/apps/jsonrpc/fastapi_app.py b/src/a2a/server/apps/jsonrpc/fastapi_app.py
@@ -96,6 +96,7 @@ def add_routes_to_app(
                 self.handle_deprecated_agent_card_path
             )
 
+        # 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
diff --git a/src/a2a/server/apps/jsonrpc/jsonrpc_app.py b/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,
@@ -143,7 +145,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
@@ -213,7 +217,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
@@ -353,6 +366,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)}'
@@ -450,6 +470,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.'},
diff --git a/src/a2a/server/apps/jsonrpc/starlette_app.py b/src/a2a/server/apps/jsonrpc/starlette_app.py
@@ -98,6 +98,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(
diff --git a/src/a2a/server/request_handlers/jsonrpc_handler.py b/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
+            )
+        )
diff --git a/tests/server/request_handlers/test_jsonrpc_handler.py b/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
+        )
diff --git a/tests/server/test_integration.py b/tests/server/test_integration.py
@@ -836,7 +836,8 @@ def test_invalid_request_structure(client: TestClient):
         '/',
         json={
             # Missing required fields
-            'id': '123'
+            'id': '123',
+            'method': 'foo/bar',
         },
     )
     assert response.status_code == 200
diff --git a/tests/test_types.py b/tests/test_types.py
@@ -24,6 +24,9 @@
     FileWithUri,
     GetTaskPushNotificationConfigParams,
     GetTaskPushNotificationConfigRequest,
+    GetAuthenticatedExtendedCardRequest,
+    GetAuthenticatedExtendedCardResponse,
+    GetAuthenticatedExtendedCardSuccessResponse,
     GetTaskPushNotificationConfigResponse,
     GetTaskPushNotificationConfigSuccessResponse,
     GetTaskRequest,
@@ -968,6 +971,21 @@ def test_a2a_request_root_model() -> None:
     assert isinstance(a2a_req_task_resubscribe_req.root.params, TaskIdParams)
     assert a2a_req_task_resubscribe_req.root.method == 'tasks/resubscribe'
 
+    # GetAuthenticatedExtendedCardRequest
+    get_auth_card_req_data: dict[str, Any] = {
+        'jsonrpc': '2.0',
+        'method': 'agent/getAuthenticatedExtendedCard',
+        'id': 2,
+    }
+    a2a_req_get_auth_card = A2ARequest.model_validate(get_auth_card_req_data)
+    assert isinstance(
+        a2a_req_get_auth_card.root, GetAuthenticatedExtendedCardRequest
+    )
+    assert (
+        a2a_req_get_auth_card.root.method
+        == 'agent/getAuthenticatedExtendedCard'
+    )
+
     # Invalid method case
     invalid_req_data: dict[str, Any] = {
         'jsonrpc': '2.0',
@@ -1055,6 +1073,14 @@ def test_a2a_request_root_model_id_validation() -> None:
     with pytest.raises(ValidationError):
         A2ARequest.model_validate(task_resubscribe_req_data)
 
+    # GetAuthenticatedExtendedCardRequest
+    get_auth_card_req_data: dict[str, Any] = {
+        'jsonrpc': '2.0',
+        'method': 'agent/getAuthenticatedExtendedCard',
+    }
+    with pytest.raises(ValidationError):
+        A2ARequest.model_validate(get_auth_card_req_data)  # missing id
+
 
 def test_content_type_not_supported_error():
     # Test ContentTypeNotSupportedError
@@ -1544,11 +1570,11 @@ def test_camelCase() -> None:
         description='Just a hello world agent',
         url='http://localhost:9999/',
         version='1.0.0',
-        defaultInputModes=['text'],
-        defaultOutputModes=['text'],
+        defaultInputModes=['text'],  # type: ignore
+        defaultOutputModes=['text'],  # type: ignore
         capabilities=AgentCapabilities(streaming=True),
         skills=[skill],
-        supportsAuthenticatedExtendedCard=True,
+        supportsAuthenticatedExtendedCard=True,  # type: ignore
     )
 
     # Test setting an attribute via camelCase alias
@@ -1568,3 +1594,56 @@ def test_camelCase() -> None:
     assert agent_card.supports_authenticated_extended_card is False
     assert default_input_modes == ['text']
     assert agent_card.default_input_modes == ['text']
+
+
+def test_get_authenticated_extended_card_request() -> None:
+    req_data: dict[str, Any] = {
+        'jsonrpc': '2.0',
+        'method': 'agent/getAuthenticatedExtendedCard',
+        'id': 5,
+    }
+    req = GetAuthenticatedExtendedCardRequest.model_validate(req_data)
+    assert req.method == 'agent/getAuthenticatedExtendedCard'
+    assert req.id == 5
+    # This request has no params, so we don't check for that.
+
+    with pytest.raises(ValidationError):  # Wrong method literal
+        GetAuthenticatedExtendedCardRequest.model_validate(
+            {**req_data, 'method': 'wrong/method'}
+        )
+
+    with pytest.raises(ValidationError):  # Missing id
+        GetAuthenticatedExtendedCardRequest.model_validate(
+            {'jsonrpc': '2.0', 'method': 'agent/getAuthenticatedExtendedCard'}
+        )
+
+
+def test_get_authenticated_extended_card_response() -> None:
+    resp_data: dict[str, Any] = {
+        'jsonrpc': '2.0',
+        'result': MINIMAL_AGENT_CARD,
+        'id': 'resp-1',
+    }
+    resp = GetAuthenticatedExtendedCardResponse.model_validate(resp_data)
+    assert resp.root.id == 'resp-1'
+    assert isinstance(resp.root, GetAuthenticatedExtendedCardSuccessResponse)
+    assert isinstance(resp.root.result, AgentCard)
+    assert resp.root.result.name == 'TestAgent'
+
+    with pytest.raises(ValidationError):  # Result is not an AgentCard
+        GetAuthenticatedExtendedCardResponse.model_validate(
+            {'jsonrpc': '2.0', 'result': {'wrong': 'data'}, 'id': 1}
+        )
+
+    resp_data_err: dict[str, Any] = {
+        'jsonrpc': '2.0',
+        'error': JSONRPCError(**TaskNotFoundError().model_dump()),
+        'id': 'resp-1',
+    }
+    resp_err = GetAuthenticatedExtendedCardResponse.model_validate(
+        resp_data_err
+    )
+    assert resp_err.root.id == 'resp-1'
+    assert isinstance(resp_err.root, JSONRPCErrorResponse)
+    assert resp_err.root.error is not None
+    assert isinstance(resp_err.root.error, JSONRPCError)

Original file line number	Diff line number	Diff line change
`@@ -96,6 +96,7 @@ def add_routes_to_app(`
`96`	`96`	`self.handle_deprecated_agent_card_path`
`97`	`97`	`)`
`98`	`98`
	`99`	`+ # TODO: deprecated endpoint to be removed in a future release`
`99`	`100`	`if self.agent_card.supports_authenticated_extended_card:`
`100`	`101`	`app.get(extended_agent_card_url)(`
`101`	`102`	`self._handle_get_authenticated_extended_agent_card`
Original file line number	Diff line number	Diff line change
`@@ -98,6 +98,7 @@ def routes(`
`98`	`98`	`)`
`99`	`99`	`)`
`100`	`100`
	`101`	`+ # TODO: deprecated endpoint to be removed in a future release`
`101`	`102`	`if self.agent_card.supports_authenticated_extended_card:`
`102`	`103`	`app_routes.append(`
`103`	`104`	`Route(`