Add support for extended card modifier in the JSONRPChandler

Author: dmandar

src/a2a/server/request_handlers/jsonrpc_handler.py

@@ -1,6 +1,6 @@
 import logging
 
-from collections.abc import AsyncIterable
+from collections.abc import AsyncIterable, Callable
 
 from a2a.server.context import ServerCallContext
 from a2a.server.request_handlers.request_handler import RequestHandler
@@ -62,17 +62,25 @@ def __init__(
         agent_card: AgentCard,
         request_handler: RequestHandler,
         extended_agent_card: AgentCard | None = None,
+        extended_card_modifier: Callable[
+            [AgentCard, ServerCallContext], 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
+            extended_card_modifier: An optional callback to dynamically modify
+              the extended agent card before it is served. It receives the
+              call context.
         """
         self.agent_card = agent_card
         self.request_handler = request_handler
         self.extended_agent_card = extended_agent_card
+        self.extended_card_modifier = extended_card_modifier
 
     async def on_message_send(
         self,
@@ -417,16 +425,27 @@ async def get_authenticated_extended_card(
         Returns:
             A `GetAuthenticatedExtendedCardResponse` object containing the config or a JSON-RPC error.
         """
-        if self.extended_agent_card is None:
+        if (
+            self.extended_agent_card is None
+            and self.extended_card_modifier is None
+        ):
             return GetAuthenticatedExtendedCardResponse(
                 root=JSONRPCErrorResponse(
                     id=request.id,
                     error=AuthenticatedExtendedCardNotConfiguredError(),
                 )
             )
 
+        base_card = self.extended_agent_card
+        if base_card is None:
+            base_card = self.agent_card
+
+        card_to_serve = base_card
+        if self.extended_card_modifier and context:
+            card_to_serve = self.extended_card_modifier(base_card, context)
+
         return GetAuthenticatedExtendedCardResponse(
             root=GetAuthenticatedExtendedCardSuccessResponse(
-                id=request.id, result=self.extended_agent_card
+                id=request.id, result=card_to_serve
             )
         )

tests/server/request_handlers/test_jsonrpc_handler.py

@@ -1212,6 +1212,7 @@ async def test_get_authenticated_extended_card_success(self) -> None:
             self.mock_agent_card,
             mock_request_handler,
             extended_agent_card=mock_extended_card,
+            extended_card_modifier=None,
         )
         request = GetAuthenticatedExtendedCardRequest(id='ext-card-req-1')
         call_context = ServerCallContext(state={'foo': 'bar'})
@@ -1233,7 +1234,10 @@ async def test_get_authenticated_extended_card_not_configured(self) -> None:
         # Arrange
         mock_request_handler = AsyncMock(spec=DefaultRequestHandler)
         handler = JSONRPCHandler(
-            self.mock_agent_card, mock_request_handler, extended_agent_card=None
+            self.mock_agent_card,
+            mock_request_handler,
+            extended_agent_card=None,
+            extended_card_modifier=None,
         )
         request = GetAuthenticatedExtendedCardRequest(id='ext-card-req-2')
         call_context = ServerCallContext(state={'foo': 'bar'})
@@ -1249,3 +1253,50 @@ async def test_get_authenticated_extended_card_not_configured(self) -> None:
         self.assertIsInstance(
             response.root.error, AuthenticatedExtendedCardNotConfiguredError
         )
+
+    async def test_get_authenticated_extended_card_with_modifier(self) -> None:
+        """Test successful retrieval of a dynamically modified extended agent card."""
+        # Arrange
+        mock_request_handler = AsyncMock(spec=DefaultRequestHandler)
+        mock_base_card = AgentCard(
+            name='Base Card',
+            description='Base details',
+            url='http://agent.example.com/api',
+            version='1.0',
+            capabilities=AgentCapabilities(),
+            default_input_modes=['text/plain'],
+            default_output_modes=['application/json'],
+            skills=[],
+        )
+
+        def modifier(card: AgentCard, context: ServerCallContext) -> AgentCard:
+            modified_card = card.model_copy(deep=True)
+            modified_card.name = 'Modified Card'
+            modified_card.description = (
+                f'Modified for context: {context.state.get("foo")}'
+            )
+            return modified_card
+
+        handler = JSONRPCHandler(
+            self.mock_agent_card,
+            mock_request_handler,
+            extended_agent_card=mock_base_card,
+            extended_card_modifier=modifier,
+        )
+        request = GetAuthenticatedExtendedCardRequest(id='ext-card-req-mod')
+        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-mod')
+        modified_card = response.root.result
+        self.assertEqual(modified_card.name, 'Modified Card')
+        self.assertEqual(modified_card.description, 'Modified for context: bar')
+        self.assertEqual(modified_card.version, '1.0')