Merge branch 'main' into fix-lint-issues

Author: holtskinner

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.3.1](https://github.com/a2aproject/a2a-python/compare/v0.3.0...v0.3.1) (2025-08-13)
+
+
+### Features
+
+* Add agent card as a route in rest adapter ([ba93053](https://github.com/a2aproject/a2a-python/commit/ba93053850a767a8959bc634883008fcc1366e09))
+
+
+### Bug Fixes
+
+* gracefully handle task exceptions in event consumer ([#383](https://github.com/a2aproject/a2a-python/issues/383)) ([2508a9b](https://github.com/a2aproject/a2a-python/commit/2508a9b8ec1a1bfdc61e9012b7d68b33082b3981))
+* openapi working in sub-app ([#324](https://github.com/a2aproject/a2a-python/issues/324)) ([dec4b48](https://github.com/a2aproject/a2a-python/commit/dec4b487514db6cbb25f0c6fa7e1275a1ab0ba71))
+* Pass `message_length` param in `get_task()` ([#384](https://github.com/a2aproject/a2a-python/issues/384)) ([b6796b9](https://github.com/a2aproject/a2a-python/commit/b6796b9e1432ef8499eff454f869edf4427fd704))
+* relax protobuf dependency version requirement ([#381](https://github.com/a2aproject/a2a-python/issues/381)) ([0f55f55](https://github.com/a2aproject/a2a-python/commit/0f55f554ba9f6bf53fa3d9a91f66939f36e1ef2e))
+* Use HasField for simple message retrieval for grpc transport ([#380](https://github.com/a2aproject/a2a-python/issues/380)) ([3032aa6](https://github.com/a2aproject/a2a-python/commit/3032aa660f6f3b72dc7dd8b49b0e2f4d432c7a22))
+
 ## [0.3.0](https://github.com/a2aproject/a2a-python/compare/v0.2.16...v0.3.0) (2025-07-31)
 
 

src/a2a/client/client_factory.py

@@ -91,7 +91,7 @@ def _register_defaults(
             if GrpcTransport is None:
                 raise ImportError(
                     'To use GrpcClient, its dependencies must be installed. '
-                    'You can install them with \'pip install "a2a-sdk[grpc]"\'',
+                    'You can install them with \'pip install "a2a-sdk[grpc]"\''
                 )
             self.register(
                 TransportProtocol.grpc,
@@ -124,20 +124,6 @@ def create(
           If there is no valid matching of the client configuration with the
           server configuration, a `ValueError` is raised.
         """
-        valid_transports = {member.value for member in TransportProtocol}
-        configured_transports = set(self._config.supported_transports)
-
-        invalid_transports = configured_transports.difference(valid_transports)
-        if invalid_transports:
-            invalid_str = ', '.join(
-                sorted(f"'{t}'" for t in invalid_transports)
-            )
-            valid_str = ', '.join(sorted(valid_transports))
-            raise ValueError(
-                f'Unsupported transport type(s) in ClientConfig: {invalid_str}. '
-                f'Valid types are: {valid_str}'
-            )
-
         server_preferred = card.preferred_transport or TransportProtocol.jsonrpc
         server_set = {server_preferred: card.url}
         if card.additional_interfaces:

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

@@ -1,15 +1,18 @@
 import logging
 
+from collections.abc import Callable
 from typing import TYPE_CHECKING, Any
 
 
 if TYPE_CHECKING:
     from fastapi import APIRouter, FastAPI, Request, Response
+    from fastapi.responses import JSONResponse
 
     _package_fastapi_installed = True
 else:
     try:
         from fastapi import APIRouter, FastAPI, Request, Response
+        from fastapi.responses import JSONResponse
 
         _package_fastapi_installed = True
     except ImportError:
@@ -23,6 +26,7 @@
 
 from a2a.server.apps.jsonrpc.jsonrpc_app import CallContextBuilder
 from a2a.server.apps.rest.rest_adapter import RESTAdapter
+from a2a.server.context import ServerCallContext
 from a2a.server.request_handlers.request_handler import RequestHandler
 from a2a.types import AgentCard
 from a2a.utils.constants import AGENT_CARD_WELL_KNOWN_PATH
@@ -39,11 +43,17 @@ class A2ARESTFastAPIApplication:
     (SSE).
     """
 
-    def __init__(
+    def __init__(  # noqa: PLR0913
         self,
         agent_card: AgentCard,
         http_handler: RequestHandler,
+        extended_agent_card: AgentCard | None = None,
         context_builder: CallContextBuilder | None = None,
+        card_modifier: Callable[[AgentCard], AgentCard] | None = None,
+        extended_card_modifier: Callable[
+            [AgentCard, ServerCallContext], AgentCard
+        ]
+        | None = None,
     ):
         """Initializes the A2ARESTFastAPIApplication.
 
@@ -56,6 +66,11 @@ def __init__(
             context_builder: The CallContextBuilder used to construct the
               ServerCallContext passed to the http_handler. If None, no
               ServerCallContext is passed.
+            card_modifier: An optional callback to dynamically modify the public
+              agent card before it is served.
+            extended_card_modifier: An optional callback to dynamically modify
+              the extended agent card before it is served. It receives the
+              call context.
         """
         if not _package_fastapi_installed:
             raise ImportError(
@@ -66,7 +81,10 @@ def __init__(
         self._adapter = RESTAdapter(
             agent_card=agent_card,
             http_handler=http_handler,
+            extended_agent_card=extended_agent_card,
             context_builder=context_builder,
+            card_modifier=card_modifier,
+            extended_card_modifier=extended_card_modifier,
         )
 
     def build(
@@ -95,7 +113,8 @@ def build(
 
         @router.get(f'{rpc_url}{agent_card_url}')
         async def get_agent_card(request: Request) -> Response:
-            return await self._adapter.handle_get_agent_card(request)
+            card = await self._adapter.handle_get_agent_card(request)
+            return JSONResponse(card)
 
         app.include_router(router)
         return app

src/a2a/server/apps/rest/rest_adapter.py

@@ -52,21 +52,34 @@ class RESTAdapter:
     manages response generation including Server-Sent Events (SSE).
     """
 
-    def __init__(
+    def __init__(  # noqa: PLR0913
         self,
         agent_card: AgentCard,
         http_handler: RequestHandler,
+        extended_agent_card: AgentCard | None = None,
         context_builder: CallContextBuilder | None = None,
+        card_modifier: Callable[[AgentCard], AgentCard] | None = None,
+        extended_card_modifier: Callable[
+            [AgentCard, ServerCallContext], AgentCard
+        ]
+        | None = None,
     ):
         """Initializes the RESTApplication.
 
         Args:
             agent_card: The AgentCard describing the agent's capabilities.
             http_handler: The handler instance responsible for processing A2A
               requests via http.
+            extended_agent_card: An optional, distinct AgentCard to be served
+              at the authenticated extended card endpoint.
             context_builder: The CallContextBuilder used to construct the
               ServerCallContext passed to the http_handler. If None, no
               ServerCallContext is passed.
+            card_modifier: An optional callback to dynamically modify the public
+              agent card before it is served.
+            extended_card_modifier: An optional callback to dynamically modify
+              the extended agent card before it is served. It receives the
+              call context.
         """
         if not _package_starlette_installed:
             raise ImportError(
@@ -75,9 +88,20 @@ def __init__(
                 ' optional dependencies, `a2a-sdk[http-server]`.'
             )
         self.agent_card = agent_card
+        self.extended_agent_card = extended_agent_card
+        self.card_modifier = card_modifier
+        self.extended_card_modifier = extended_card_modifier
         self.handler = RESTHandler(
             agent_card=agent_card, request_handler=http_handler
         )
+        if (
+            self.agent_card.supports_authenticated_extended_card
+            and self.extended_agent_card is None
+            and self.extended_card_modifier is None
+        ):
+            logger.error(
+                'AgentCard.supports_authenticated_extended_card is True, but no extended_agent_card was provided. The /agent/authenticatedExtendedCard endpoint will return 404.'
+            )
         self._context_builder = context_builder or DefaultCallContextBuilder()
 
     @rest_error_handler
@@ -108,33 +132,35 @@ async def event_generator(
             event_generator(method(request, call_context))
         )
 
-    @rest_error_handler
-    async def handle_get_agent_card(self, request: Request) -> JSONResponse:
+    async def handle_get_agent_card(
+        self, request: Request, call_context: ServerCallContext | None = None
+    ) -> dict[str, Any]:
         """Handles GET requests for the agent card endpoint.
 
         Args:
             request: The incoming Starlette Request object.
+            call_context: ServerCallContext
 
         Returns:
             A JSONResponse containing the agent card data.
         """
-        # The public agent card is a direct serialization of the agent_card
-        # provided at initialization.
-        return JSONResponse(
-            self.agent_card.model_dump(mode='json', exclude_none=True)
-        )
+        card_to_serve = self.agent_card
+        if self.card_modifier:
+            card_to_serve = self.card_modifier(card_to_serve)
+
+        return card_to_serve.model_dump(mode='json', exclude_none=True)
 
-    @rest_error_handler
     async def handle_authenticated_agent_card(
-        self, request: Request
-    ) -> JSONResponse:
+        self, request: Request, call_context: ServerCallContext | None = None
+    ) -> dict[str, Any]:
         """Hook for per credential agent card response.
 
         If a dynamic card is needed based on the credentials provided in the request
         override this method and return the customized content.
 
         Args:
             request: The incoming Starlette Request  object.
+            call_context: ServerCallContext
 
         Returns:
             A JSONResponse containing the authenticated card.
@@ -145,9 +171,18 @@ async def handle_authenticated_agent_card(
                     message='Authenticated card not supported'
                 )
             )
-        return JSONResponse(
-            self.agent_card.model_dump(mode='json', exclude_none=True)
-        )
+        card_to_serve = self.extended_agent_card
+
+        if not card_to_serve:
+            card_to_serve = self.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 = self.extended_card_modifier(base_card, context)
+
+        return card_to_serve.model_dump(mode='json', exclude_none=True)
 
     def routes(self) -> dict[tuple[str, str], Callable[[Request], Any]]:
         """Constructs a dictionary of API routes and their corresponding handlers.
@@ -201,6 +236,8 @@ def routes(self) -> dict[tuple[str, str], Callable[[Request], Any]]:
             ),
         }
         if self.agent_card.supports_authenticated_extended_card:
-            routes[('/v1/card', 'GET')] = self.handle_authenticated_agent_card
+            routes[('/v1/card', 'GET')] = functools.partial(
+                self._handle_request, self.handle_authenticated_agent_card
+            )
 
         return routes

tests/client/test_client_factory.py

@@ -103,32 +103,3 @@ def test_client_factory_no_compatible_transport(base_agent_card: AgentCard):
     factory = ClientFactory(config)
     with pytest.raises(ValueError, match='no compatible transports found'):
         factory.create(base_agent_card)
-
-
-@pytest.mark.parametrize(
-    ('invalid_transports', 'expected_match'),
-    [
-        (
-            ['invalid-transport'],
-            "Unsupported transport type\\(s\\) in ClientConfig: 'invalid-transport'",
-        ),
-        (
-            ['invalid-1', 'another-bad-one'],
-            "Unsupported transport type\\(s\\) in ClientConfig: 'another-bad-one', 'invalid-1'",
-        ),
-    ],
-)
-def test_client_factory_invalid_transport_in_config(
-    base_agent_card: AgentCard, invalid_transports, expected_match
-):
-    """Verify that the factory raises an error for unknown transport types."""
-    config = ClientConfig(
-        httpx_client=httpx.AsyncClient(),
-        supported_transports=[
-            TransportProtocol.jsonrpc,
-            *invalid_transports,
-        ],
-    )
-    factory = ClientFactory(config)
-    with pytest.raises(ValueError, match=expected_match):
-        factory.create(base_agent_card)

tests/integration/test_client_server_integration.py

@@ -1,5 +1,4 @@
 import asyncio
-
 from collections.abc import AsyncGenerator
 from typing import NamedTuple
 from unittest.mock import ANY, AsyncMock
@@ -8,7 +7,6 @@
 import httpx
 import pytest
 import pytest_asyncio
-
 from grpc.aio import Channel
 
 from a2a.client.transports import JsonRpcTransport, RestTransport
@@ -38,7 +36,6 @@
     TransportProtocol,
 )
 
-
 # --- Test Constants ---
 
 TASK_FROM_STREAM = Task(
@@ -130,7 +127,7 @@ def agent_card() -> AgentCard:
         default_input_modes=['text/plain'],
         default_output_modes=['text/plain'],
         preferred_transport=TransportProtocol.jsonrpc,
-        supports_authenticated_extended_card=True,
+        supports_authenticated_extended_card=False,
         additional_interfaces=[
             AgentInterface(
                 transport=TransportProtocol.http_json, url='http://testserver'
@@ -709,9 +706,7 @@ async def test_http_transport_get_card(
         transport_setup_fixture
     )
     transport = transport_setup.transport
-
-    # The transport starts with a minimal card, get_card() fetches the full one
-    transport.agent_card.supports_authenticated_extended_card = True
+    # Get the base card.
     result = await transport.get_card()
 
     assert result.name == agent_card.name
@@ -722,6 +717,33 @@ async def test_http_transport_get_card(
         await transport.close()
 
 
+@pytest.mark.asyncio
+async def test_http_transport_get_authenticated_card(
+    agent_card: AgentCard,
+    mock_request_handler: AsyncMock,
+) -> None:
+    agent_card.supports_authenticated_extended_card = True
+    extended_agent_card = agent_card.model_copy(deep=True)
+    extended_agent_card.name = 'Extended Agent Card'
+
+    app_builder = A2ARESTFastAPIApplication(
+        agent_card,
+        mock_request_handler,
+        extended_agent_card=extended_agent_card,
+    )
+    app = app_builder.build()
+    httpx_client = httpx.AsyncClient(transport=httpx.ASGITransport(app=app))
+
+    transport = RestTransport(httpx_client=httpx_client, agent_card=agent_card)
+    result = await transport.get_card()
+    assert result.name == extended_agent_card.name
+    assert transport.agent_card.name == extended_agent_card.name
+    assert transport._needs_extended_card is False
+
+    if hasattr(transport, 'close'):
+        await transport.close()
+
+
 @pytest.mark.asyncio
 async def test_grpc_transport_get_card(
     grpc_server_and_handler: tuple[str, AsyncMock],