refactor(client): remove URL resolution logic from transports (#732)

Rely on the `ClientFactory` to resolve proper URL and do not duplicate
logic in transports. `AgentCard` is still passed to transports as it's
used for capabilities inspection.

Make both `agent_card` and `url` mandatory, transports are mainly used
from the `ClientFactory` and `| None` are likely non-breaking leftovers.

Fixes #703

Author: ishymko

src/a2a/client/transports/jsonrpc.py

@@ -11,7 +11,6 @@
 from httpx_sse import SSEError, aconnect_sse
 from jsonrpc.jsonrpc2 import JSONRPC20Request, JSONRPC20Response
 
-from a2a.client.card_resolver import A2ACardResolver
 from a2a.client.errors import (
     A2AClientHTTPError,
     A2AClientJSONError,
@@ -50,31 +49,18 @@ class JsonRpcTransport(ClientTransport):
     def __init__(
         self,
         httpx_client: httpx.AsyncClient,
-        agent_card: AgentCard | None = None,
-        url: str | None = None,
+        agent_card: AgentCard,
+        url: str,
         interceptors: list[ClientCallInterceptor] | None = None,
         extensions: list[str] | None = None,
     ):
         """Initializes the JsonRpcTransport."""
-        if url:
-            self.url = url
-        elif agent_card:
-            if agent_card.supported_interfaces:
-                self.url = agent_card.supported_interfaces[0].url
-            else:
-                # Fallback or error if no interfaces?
-                # For compatibility we might check if 'url' attr exists (it does not on proto anymore)
-                raise ValueError('AgentCard has no supported interfaces')
-        else:
-            raise ValueError('Must provide either agent_card or url')
-
+        self.url = url
         self.httpx_client = httpx_client
         self.agent_card = agent_card
         self.interceptors = interceptors or []
         self.extensions = extensions
-        self._needs_extended_card = (
-            agent_card.capabilities.extended_agent_card if agent_card else True
-        )
+        self._needs_extended_card = agent_card.capabilities.extended_agent_card
 
     async def _apply_interceptors(
         self,
@@ -447,15 +433,6 @@ async def get_extended_agent_card(
 
         card = self.agent_card
 
-        if not card:
-            resolver = A2ACardResolver(self.httpx_client, self.url)
-            card = await resolver.get_agent_card(
-                http_kwargs=modified_kwargs,
-                signature_verifier=signature_verifier,
-            )
-            self.agent_card = card
-            self._needs_extended_card = card.capabilities.extended_agent_card
-
         if not card.capabilities.extended_agent_card:
             return card
 

src/a2a/client/transports/rest.py

@@ -10,7 +10,6 @@
 from google.protobuf.message import Message
 from httpx_sse import SSEError, aconnect_sse
 
-from a2a.client.card_resolver import A2ACardResolver
 from a2a.client.errors import (
     A2AClientHTTPError,
     A2AClientJSONError,
@@ -34,9 +33,6 @@
     Task,
     TaskPushNotificationConfig,
 )
-from a2a.utils.constants import (
-    TransportProtocol,
-)
 from a2a.utils.telemetry import SpanKind, trace_class
 
 
@@ -50,37 +46,17 @@ class RestTransport(ClientTransport):
     def __init__(
         self,
         httpx_client: httpx.AsyncClient,
-        agent_card: AgentCard | None = None,
-        url: str | None = None,
+        agent_card: AgentCard,
+        url: str,
         interceptors: list[ClientCallInterceptor] | None = None,
         extensions: list[str] | None = None,
     ):
         """Initializes the RestTransport."""
-        if url:
-            self.url = url
-        elif agent_card:
-            for interface in agent_card.supported_interfaces:
-                if interface.protocol_binding in (
-                    TransportProtocol.HTTP_JSON,
-                    TransportProtocol.JSONRPC,
-                ):
-                    self.url = interface.url
-                    break
-            else:
-                raise ValueError(
-                    f'AgentCard does not support {TransportProtocol.HTTP_JSON} '
-                    f'or {TransportProtocol.JSONRPC}'
-                )
-        else:
-            raise ValueError('Must provide either agent_card or url')
-        if self.url.endswith('/'):
-            self.url = self.url[:-1]
+        self.url = url.removesuffix('/')
         self.httpx_client = httpx_client
         self.agent_card = agent_card
         self.interceptors = interceptors or []
-        self._needs_extended_card = (
-            agent_card.capabilities.extended_agent_card if agent_card else True
-        )
+        self._needs_extended_card = agent_card.capabilities.extended_agent_card
         self.extensions = extensions
 
     async def _apply_interceptors(
@@ -416,15 +392,6 @@ async def get_extended_agent_card(
 
         card = self.agent_card
 
-        if not card:
-            resolver = A2ACardResolver(self.httpx_client, self.url)
-            card = await resolver.get_agent_card(
-                http_kwargs=modified_kwargs,
-                signature_verifier=signature_verifier,
-            )
-            self.agent_card = card
-            self._needs_extended_card = card.capabilities.extended_agent_card
-
         if not card.capabilities.extended_agent_card:
             return card
         _, modified_kwargs = await self._apply_interceptors(

tests/client/transports/test_jsonrpc_client.py

@@ -70,6 +70,7 @@ def transport(mock_httpx_client, agent_card):
     return JsonRpcTransport(
         httpx_client=mock_httpx_client,
         agent_card=agent_card,
+        url='http://test-agent.example.com',
     )
 
 
@@ -78,6 +79,7 @@ def transport_with_url(mock_httpx_client):
     """Creates a JsonRpcTransport with just a URL."""
     return JsonRpcTransport(
         httpx_client=mock_httpx_client,
+        agent_card=AgentCard(name='Dummy'),
         url='http://custom-url.example.com',
     )
 
@@ -113,41 +115,18 @@ def test_init_with_agent_card(self, mock_httpx_client, agent_card):
         transport = JsonRpcTransport(
             httpx_client=mock_httpx_client,
             agent_card=agent_card,
+            url='http://test-agent.example.com',
         )
         assert transport.url == 'http://test-agent.example.com'
         assert transport.agent_card == agent_card
 
-    def test_init_with_url(self, mock_httpx_client):
-        """Test initialization with a URL."""
-        transport = JsonRpcTransport(
-            httpx_client=mock_httpx_client,
-            url='http://custom-url.example.com',
-        )
-        assert transport.url == 'http://custom-url.example.com'
-        assert transport.agent_card is None
-
-    def test_init_url_takes_precedence(self, mock_httpx_client, agent_card):
-        """Test that explicit URL takes precedence over agent card URL."""
-        transport = JsonRpcTransport(
-            httpx_client=mock_httpx_client,
-            agent_card=agent_card,
-            url='http://override-url.example.com',
-        )
-        assert transport.url == 'http://override-url.example.com'
-
-    def test_init_requires_url_or_agent_card(self, mock_httpx_client):
-        """Test that initialization requires either URL or agent card."""
-        with pytest.raises(
-            ValueError, match='Must provide either agent_card or url'
-        ):
-            JsonRpcTransport(httpx_client=mock_httpx_client)
-
     def test_init_with_interceptors(self, mock_httpx_client, agent_card):
         """Test initialization with interceptors."""
         interceptor = MagicMock()
         transport = JsonRpcTransport(
             httpx_client=mock_httpx_client,
             agent_card=agent_card,
+            url='http://test-agent.example.com',
             interceptors=[interceptor],
         )
         assert transport.interceptors == [interceptor]
@@ -158,6 +137,7 @@ def test_init_with_extensions(self, mock_httpx_client, agent_card):
         transport = JsonRpcTransport(
             httpx_client=mock_httpx_client,
             agent_card=agent_card,
+            url='http://test-agent.example.com',
             extensions=extensions,
         )
         assert transport.extensions == extensions
@@ -466,6 +446,7 @@ async def test_interceptor_called(self, mock_httpx_client, agent_card):
         transport = JsonRpcTransport(
             httpx_client=mock_httpx_client,
             agent_card=agent_card,
+            url='http://test-agent.example.com',
             interceptors=[interceptor],
         )
 
@@ -505,6 +486,7 @@ async def test_extensions_added_to_request(
         transport = JsonRpcTransport(
             httpx_client=mock_httpx_client,
             agent_card=agent_card,
+            url='http://test-agent.example.com',
             extensions=extensions,
         )
 
@@ -548,6 +530,7 @@ async def test_send_message_streaming_server_error_propagates(
         client = JsonRpcTransport(
             httpx_client=mock_httpx_client,
             agent_card=agent_card,
+            url='http://test-agent.example.com',
         )
         request = create_send_message_request(text='Error stream')
 
@@ -577,41 +560,6 @@ async def empty_aiter():
         assert exc_info.value.status_code == 403
         mock_aconnect_sse.assert_called_once()
 
-    @pytest.mark.asyncio
-    async def test_get_card_no_card_provided_with_extensions(
-        self, mock_httpx_client: AsyncMock, agent_card: AgentCard
-    ):
-        """Test get_extended_agent_card with extensions set in Client when no card is initially provided.
-        Tests that the extensions are added to the HTTP GET request."""
-        extensions = [
-            'https://example.com/test-ext/v1',
-            'https://example.com/test-ext/v2',
-        ]
-        client = JsonRpcTransport(
-            httpx_client=mock_httpx_client,
-            url='http://test-agent.example.com',
-            extensions=extensions,
-        )
-        mock_response = AsyncMock(spec=httpx.Response)
-        mock_response.status_code = 200
-        mock_response.json.return_value = json_format.MessageToDict(agent_card)
-        mock_httpx_client.get.return_value = mock_response
-
-        agent_card.capabilities.extended_agent_card = False
-
-        await client.get_extended_agent_card()
-
-        mock_httpx_client.get.assert_called_once()
-        _, mock_kwargs = mock_httpx_client.get.call_args
-
-        _assert_extensions_header(
-            mock_kwargs,
-            {
-                'https://example.com/test-ext/v1',
-                'https://example.com/test-ext/v2',
-            },
-        )
-
     @pytest.mark.asyncio
     async def test_get_card_with_extended_card_support_with_extensions(
         self, mock_httpx_client: AsyncMock, agent_card: AgentCard
@@ -627,6 +575,7 @@ async def test_get_card_with_extended_card_support_with_extensions(
         client = JsonRpcTransport(
             httpx_client=mock_httpx_client,
             agent_card=agent_card,
+            url='http://test-agent.example.com',
             extensions=extensions,
         )
 

tests/client/transports/test_rest_client.py

@@ -65,7 +65,9 @@ async def test_send_message_streaming_timeout(
         mock_agent_card: MagicMock,
     ):
         client = RestTransport(
-            httpx_client=mock_httpx_client, agent_card=mock_agent_card
+            httpx_client=mock_httpx_client,
+            agent_card=mock_agent_card,
+            url='http://agent.example.com/api',
         )
         params = SendMessageRequest(
             message=create_text_message_object(content='Hello stream')
@@ -101,8 +103,9 @@ async def test_send_message_with_default_extensions(
         ]
         client = RestTransport(
             httpx_client=mock_httpx_client,
-            extensions=extensions,
             agent_card=mock_agent_card,
+            url='http://agent.example.com/api',
+            extensions=extensions,
         )
         params = SendMessageRequest(
             message=create_text_message_object(content='Hello')
@@ -146,6 +149,7 @@ async def test_send_message_streaming_with_new_extensions(
         client = RestTransport(
             httpx_client=mock_httpx_client,
             agent_card=mock_agent_card,
+            url='http://agent.example.com/api',
             extensions=extensions,
         )
         params = SendMessageRequest(
@@ -185,6 +189,7 @@ async def test_send_message_streaming_server_error_propagates(
         client = RestTransport(
             httpx_client=mock_httpx_client,
             agent_card=mock_agent_card,
+            url='http://agent.example.com/api',
         )
         request = SendMessageRequest(
             message=create_text_message_object(content='Error stream')
@@ -217,47 +222,6 @@ async def empty_aiter():
 
         mock_aconnect_sse.assert_called_once()
 
-    @pytest.mark.asyncio
-    async def test_get_card_no_card_provided_with_extensions(
-        self, mock_httpx_client: AsyncMock
-    ):
-        """Test get_extended_agent_card with extensions set in Client when no card is initially provided.
-        Tests that the extensions are added to the HTTP GET request."""
-        extensions = [
-            'https://example.com/test-ext/v1',
-            'https://example.com/test-ext/v2',
-        ]
-        client = RestTransport(
-            httpx_client=mock_httpx_client,
-            url='http://agent.example.com/api',
-            extensions=extensions,
-        )
-
-        agent_card = AgentCard(
-            name='Test Agent',
-            description='Test Agent Description',
-            version='1.0.0',
-            capabilities=AgentCapabilities(),
-        )
-
-        mock_response = AsyncMock(spec=httpx.Response)
-        mock_response.status_code = 200
-        mock_response.json.return_value = json_format.MessageToDict(agent_card)
-        mock_httpx_client.get.return_value = mock_response
-
-        await client.get_extended_agent_card()
-
-        mock_httpx_client.get.assert_called_once()
-        _, mock_kwargs = mock_httpx_client.get.call_args
-
-        _assert_extensions_header(
-            mock_kwargs,
-            {
-                'https://example.com/test-ext/v1',
-                'https://example.com/test-ext/v2',
-            },
-        )
-
     @pytest.mark.asyncio
     async def test_get_card_with_extended_card_support_with_extensions(
         self, mock_httpx_client: AsyncMock
@@ -281,6 +245,7 @@ async def test_get_card_with_extended_card_support_with_extensions(
         client = RestTransport(
             httpx_client=mock_httpx_client,
             agent_card=agent_card,
+            url='http://agent.example.com/api',
         )
 
         mock_response = AsyncMock(spec=httpx.Response)