Merge branch 'main' into restful

Author: mikeas1

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

@@ -16,6 +16,7 @@
     AGENT_CARD_WELL_KNOWN_PATH,
     DEFAULT_RPC_URL,
     EXTENDED_AGENT_CARD_PATH,
+    PREV_AGENT_CARD_WELL_KNOWN_PATH,
 )
 
 
@@ -89,6 +90,13 @@ def add_routes_to_app(
         )(self._handle_requests)
         app.get(agent_card_url)(self._handle_get_agent_card)
 
+        # add deprecated path only if the agent_card_url uses default well-known path
+        if agent_card_url == AGENT_CARD_WELL_KNOWN_PATH:
+            app.get(PREV_AGENT_CARD_WELL_KNOWN_PATH, include_in_schema=False)(
+                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

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,
@@ -52,6 +54,7 @@
     AGENT_CARD_WELL_KNOWN_PATH,
     DEFAULT_RPC_URL,
     EXTENDED_AGENT_CARD_PATH,
+    PREV_AGENT_CARD_WELL_KNOWN_PATH,
 )
 from a2a.utils.errors import MethodNotImplementedError
 
@@ -142,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
@@ -212,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
@@ -352,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)}'
@@ -436,10 +457,23 @@ async def _handle_get_agent_card(self, request: Request) -> JSONResponse:
             )
         )
 
+    async def handle_deprecated_agent_card_path(
+        self, request: Request
+    ) -> JSONResponse:
+        """Handles GET requests for the deprecated agent card endpoint."""
+        logger.warning(
+            f"Deprecated agent card endpoint '{PREV_AGENT_CARD_WELL_KNOWN_PATH}' accessed. Please use '{AGENT_CARD_WELL_KNOWN_PATH}' instead. This endpoint will be removed in a future version."
+        )
+        return await self._handle_get_agent_card(request)
+
     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

@@ -15,6 +15,7 @@
     AGENT_CARD_WELL_KNOWN_PATH,
     DEFAULT_RPC_URL,
     EXTENDED_AGENT_CARD_PATH,
+    PREV_AGENT_CARD_WELL_KNOWN_PATH,
 )
 
 
@@ -86,6 +87,18 @@ def routes(
             ),
         ]
 
+        # add deprecated path only if the agent_card_url uses default well-known path
+        if agent_card_url == AGENT_CARD_WELL_KNOWN_PATH:
+            app_routes.append(
+                Route(
+                    PREV_AGENT_CARD_WELL_KNOWN_PATH,
+                    self.handle_deprecated_agent_card_path,
+                    methods=['GET'],
+                    name='agent_card_path_deprecated',
+                )
+            )
+
+        # 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,26 @@ 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 is not configured'
+    """
+    The error message.
+    """
+
+
 class AuthorizationCodeOAuthFlow(A2ABaseModel):
     """
     Defines configuration details for the OAuth 2.0 Authorization Code flow.
@@ -375,6 +395,27 @@ class FileWithUri(A2ABaseModel):
     """
 
 
+class GetAuthenticatedExtendedCardRequest(A2ABaseModel):
+    """
+    Represents a JSON-RPC request for the `agent/getAuthenticatedExtendedCard` 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/getAuthenticatedExtendedCard'] = (
+        'agent/getAuthenticatedExtendedCard'
+    )
+    """
+    The method name. Must be 'agent/getAuthenticatedExtendedCard'.
+    """
+
+
 class GetTaskPushNotificationConfigParams(A2ABaseModel):
     """
     Defines parameters for fetching a specific push notification configuration for a task.
@@ -999,6 +1040,7 @@ class A2AError(
         | UnsupportedOperationError
         | ContentTypeNotSupportedError
         | InvalidAgentResponseError
+        | AuthenticatedExtendedCardNotConfiguredError
     ]
 ):
     root: (
@@ -1013,6 +1055,7 @@ class A2AError(
         | UnsupportedOperationError
         | ContentTypeNotSupportedError
         | InvalidAgentResponseError
+        | AuthenticatedExtendedCardNotConfiguredError
     )
     """
     A discriminated union of all standard JSON-RPC and A2A-specific error types.
@@ -1170,6 +1213,7 @@ class JSONRPCErrorResponse(A2ABaseModel):
         | UnsupportedOperationError
         | ContentTypeNotSupportedError
         | InvalidAgentResponseError
+        | AuthenticatedExtendedCardNotConfiguredError
     )
     """
     An object describing the error that occurred.
@@ -1625,6 +1669,7 @@ class A2ARequest(
         | TaskResubscriptionRequest
         | ListTaskPushNotificationConfigRequest
         | DeleteTaskPushNotificationConfigRequest
+        | GetAuthenticatedExtendedCardRequest
     ]
 ):
     root: (
@@ -1637,6 +1682,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 +1796,25 @@ class AgentCard(A2ABaseModel):
     """
 
 
+class GetAuthenticatedExtendedCardSuccessResponse(A2ABaseModel):
+    """
+    Represents a successful JSON-RPC response for the `agent/getAuthenticatedExtendedCard` 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 +1834,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 +1869,17 @@ class CancelTaskSuccessResponse(A2ABaseModel):
     """
 
 
+class GetAuthenticatedExtendedCardResponse(
+    RootModel[
+        JSONRPCErrorResponse | GetAuthenticatedExtendedCardSuccessResponse
+    ]
+):
+    root: JSONRPCErrorResponse | GetAuthenticatedExtendedCardSuccessResponse
+    """
+    Represents a JSON-RPC response for the `agent/getAuthenticatedExtendedCard` method.
+    """
+
+
 class GetTaskSuccessResponse(A2ABaseModel):
     """
     Represents a successful JSON-RPC response for the `tasks/get` method.
@@ -1889,6 +1965,7 @@ class JSONRPCResponse(
         | GetTaskPushNotificationConfigSuccessResponse
         | ListTaskPushNotificationConfigSuccessResponse
         | DeleteTaskPushNotificationConfigSuccessResponse
+        | GetAuthenticatedExtendedCardSuccessResponse
     ]
 ):
     root: (
@@ -1901,6 +1978,7 @@ class JSONRPCResponse(
         | GetTaskPushNotificationConfigSuccessResponse
         | ListTaskPushNotificationConfigSuccessResponse
         | DeleteTaskPushNotificationConfigSuccessResponse
+        | GetAuthenticatedExtendedCardSuccessResponse
     )
     """
     A discriminated union representing all possible JSON-RPC 2.0 responses

src/a2a/utils/__init__.py

@@ -9,6 +9,7 @@
     AGENT_CARD_WELL_KNOWN_PATH,
     DEFAULT_RPC_URL,
     EXTENDED_AGENT_CARD_PATH,
+    PREV_AGENT_CARD_WELL_KNOWN_PATH,
 )
 from a2a.utils.helpers import (
     append_artifact_to_task,
@@ -34,6 +35,7 @@
     'AGENT_CARD_WELL_KNOWN_PATH',
     'DEFAULT_RPC_URL',
     'EXTENDED_AGENT_CARD_PATH',
+    'PREV_AGENT_CARD_WELL_KNOWN_PATH',
     'append_artifact_to_task',
     'are_modalities_compatible',
     'build_text_artifact',

src/a2a/utils/constants.py

@@ -1,5 +1,6 @@
 """Constants for well-known URIs used throughout the A2A Python SDK."""
 
-AGENT_CARD_WELL_KNOWN_PATH = '/.well-known/agent.json'
+AGENT_CARD_WELL_KNOWN_PATH = '/.well-known/agent-card.json'
+PREV_AGENT_CARD_WELL_KNOWN_PATH = '/.well-known/agent.json'
 EXTENDED_AGENT_CARD_PATH = '/agent/authenticatedExtendedCard'
 DEFAULT_RPC_URL = '/'