feat: Add a ClientFactory.connect() method for easy client creation (#509)

# Description

This PR adds a convenience method for constructing a Client from either
an AgentCard URL or an AgentCard directly. The goal is to reduce the
number of lines of code required for simple client creation, but still
enabling more advanced handled of client construction.

Usage example:

```python
my_agent_url =  'https://travel-agent.example.com'
client = await ClientFactory.connect(my_agent_url)
await client.send_message(...)
```

Release-As: 0.3.10

---------

Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>

Author: mikeas1

.github/actions/spelling/allow.txt

@@ -1,3 +1,4 @@
+AAgent
 ACard
 AClient
 ACMRTUXB

src/a2a/client/client_factory.py

@@ -3,10 +3,12 @@
 import logging
 
 from collections.abc import Callable
+from typing import Any
 
 import httpx
 
 from a2a.client.base_client import BaseClient
+from a2a.client.card_resolver import A2ACardResolver
 from a2a.client.client import Client, ClientConfig, Consumer
 from a2a.client.middleware import ClientCallInterceptor
 from a2a.client.transports.base import ClientTransport
@@ -101,6 +103,71 @@ def _register_defaults(
                 GrpcTransport.create,
             )
 
+    @classmethod
+    async def connect(  # noqa: PLR0913
+        cls,
+        agent: str | AgentCard,
+        client_config: ClientConfig | None = None,
+        consumers: list[Consumer] | None = None,
+        interceptors: list[ClientCallInterceptor] | None = None,
+        relative_card_path: str | None = None,
+        resolver_http_kwargs: dict[str, Any] | None = None,
+        extra_transports: dict[str, TransportProducer] | None = None,
+    ) -> Client:
+        """Convenience method for constructing a client.
+
+        Constructs a client that connects to the specified agent. Note that
+        creating multiple clients via this method is less efficient than
+        constructing an instance of ClientFactory and reusing that.
+
+        .. code-block:: python
+
+            # This will search for an AgentCard at /.well-known/agent-card.json
+            my_agent_url = 'https://travel.agents.example.com'
+            client = await ClientFactory.connect(my_agent_url)
+
+
+        Args:
+          agent: The base URL of the agent, or the AgentCard to connect to.
+          client_config: The ClientConfig to use when connecting to the agent.
+          consumers: A list of `Consumer` methods to pass responses to.
+          interceptors: A list of interceptors to use for each request. These
+            are used for things like attaching credentials or http headers
+            to all outbound requests.
+          relative_card_path: If the agent field is a URL, this value is used as
+            the relative path when resolving the agent card. See
+            A2AAgentCardResolver.get_agent_card for more details.
+          resolver_http_kwargs: Dictionary of arguments to provide to the httpx
+            client when resolving the agent card. This value is provided to
+            A2AAgentCardResolver.get_agent_card as the http_kwargs parameter.
+          extra_transports: Additional transport protocols to enable when
+            constructing the client.
+
+        Returns:
+          A `Client` object.
+        """
+        client_config = client_config or ClientConfig()
+        if isinstance(agent, str):
+            if not client_config.httpx_client:
+                async with httpx.AsyncClient() as client:
+                    resolver = A2ACardResolver(client, agent)
+                    card = await resolver.get_agent_card(
+                        relative_card_path=relative_card_path,
+                        http_kwargs=resolver_http_kwargs,
+                    )
+            else:
+                resolver = A2ACardResolver(client_config.httpx_client, agent)
+                card = await resolver.get_agent_card(
+                    relative_card_path=relative_card_path,
+                    http_kwargs=resolver_http_kwargs,
+                )
+        else:
+            card = agent
+        factory = cls(client_config)
+        for label, generator in (extra_transports or {}).items():
+            factory.register(label, generator)
+        return factory.create(card, consumers, interceptors)
+
     def register(self, label: str, generator: TransportProducer) -> None:
         """Register a new transport producer for a given transport label."""
         self._registry[label] = generator

tests/client/test_client_factory.py

@@ -1,5 +1,7 @@
 """Tests for the ClientFactory."""
 
+from unittest.mock import AsyncMock, MagicMock, patch
+
 import httpx
 import pytest
 
@@ -103,3 +105,158 @@ 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.asyncio
+async def test_client_factory_connect_with_agent_card(
+    base_agent_card: AgentCard,
+):
+    """Verify that connect works correctly when provided with an AgentCard."""
+    client = await ClientFactory.connect(base_agent_card)
+    assert isinstance(client._transport, JsonRpcTransport)
+    assert client._transport.url == 'http://primary-url.com'
+
+
+@pytest.mark.asyncio
+async def test_client_factory_connect_with_url(base_agent_card: AgentCard):
+    """Verify that connect works correctly when provided with a URL."""
+    with patch('a2a.client.client_factory.A2ACardResolver') as mock_resolver:
+        mock_resolver.return_value.get_agent_card = AsyncMock(
+            return_value=base_agent_card
+        )
+
+        agent_url = 'http://example.com'
+        client = await ClientFactory.connect(agent_url)
+
+        mock_resolver.assert_called_once()
+        assert mock_resolver.call_args[0][1] == agent_url
+        mock_resolver.return_value.get_agent_card.assert_awaited_once()
+
+        assert isinstance(client._transport, JsonRpcTransport)
+        assert client._transport.url == 'http://primary-url.com'
+
+
+@pytest.mark.asyncio
+async def test_client_factory_connect_with_url_and_client_config(
+    base_agent_card: AgentCard,
+):
+    """Verify connect with a URL and a pre-configured httpx client."""
+    with patch('a2a.client.client_factory.A2ACardResolver') as mock_resolver:
+        mock_resolver.return_value.get_agent_card = AsyncMock(
+            return_value=base_agent_card
+        )
+
+        agent_url = 'http://example.com'
+        mock_httpx_client = httpx.AsyncClient()
+        config = ClientConfig(httpx_client=mock_httpx_client)
+
+        client = await ClientFactory.connect(agent_url, client_config=config)
+
+        mock_resolver.assert_called_once_with(mock_httpx_client, agent_url)
+        mock_resolver.return_value.get_agent_card.assert_awaited_once()
+
+        assert isinstance(client._transport, JsonRpcTransport)
+        assert client._transport.url == 'http://primary-url.com'
+
+
+@pytest.mark.asyncio
+async def test_client_factory_connect_with_resolver_args(
+    base_agent_card: AgentCard,
+):
+    """Verify connect passes resolver arguments correctly."""
+    with patch('a2a.client.client_factory.A2ACardResolver') as mock_resolver:
+        mock_resolver.return_value.get_agent_card = AsyncMock(
+            return_value=base_agent_card
+        )
+
+        agent_url = 'http://example.com'
+        relative_path = '/card'
+        http_kwargs = {'headers': {'X-Test': 'true'}}
+
+        # The resolver args are only passed if an httpx_client is provided in config
+        config = ClientConfig(httpx_client=httpx.AsyncClient())
+
+        await ClientFactory.connect(
+            agent_url,
+            client_config=config,
+            relative_card_path=relative_path,
+            resolver_http_kwargs=http_kwargs,
+        )
+
+        mock_resolver.return_value.get_agent_card.assert_awaited_once_with(
+            relative_card_path=relative_path,
+            http_kwargs=http_kwargs,
+        )
+
+
+@pytest.mark.asyncio
+async def test_client_factory_connect_resolver_args_without_client(
+    base_agent_card: AgentCard,
+):
+    """Verify resolver args are ignored if no httpx_client is provided."""
+    with patch('a2a.client.client_factory.A2ACardResolver') as mock_resolver:
+        mock_resolver.return_value.get_agent_card = AsyncMock(
+            return_value=base_agent_card
+        )
+
+        agent_url = 'http://example.com'
+        relative_path = '/card'
+        http_kwargs = {'headers': {'X-Test': 'true'}}
+
+        await ClientFactory.connect(
+            agent_url,
+            relative_card_path=relative_path,
+            resolver_http_kwargs=http_kwargs,
+        )
+
+        mock_resolver.return_value.get_agent_card.assert_awaited_once_with(
+            relative_card_path=relative_path,
+            http_kwargs=http_kwargs,
+        )
+
+
+@pytest.mark.asyncio
+async def test_client_factory_connect_with_extra_transports(
+    base_agent_card: AgentCard,
+):
+    """Verify that connect can register and use extra transports."""
+
+    class CustomTransport:
+        pass
+
+    def custom_transport_producer(*args, **kwargs):
+        return CustomTransport()
+
+    base_agent_card.preferred_transport = 'custom'
+    base_agent_card.url = 'custom://foo'
+
+    config = ClientConfig(supported_transports=['custom'])
+
+    client = await ClientFactory.connect(
+        base_agent_card,
+        client_config=config,
+        extra_transports={'custom': custom_transport_producer},
+    )
+
+    assert isinstance(client._transport, CustomTransport)
+
+
+@pytest.mark.asyncio
+async def test_client_factory_connect_with_consumers_and_interceptors(
+    base_agent_card: AgentCard,
+):
+    """Verify consumers and interceptors are passed through correctly."""
+    consumer1 = MagicMock()
+    interceptor1 = MagicMock()
+
+    with patch('a2a.client.client_factory.BaseClient') as mock_base_client:
+        await ClientFactory.connect(
+            base_agent_card,
+            consumers=[consumer1],
+            interceptors=[interceptor1],
+        )
+
+        mock_base_client.assert_called_once()
+        call_args = mock_base_client.call_args[0]
+        assert call_args[3] == [consumer1]
+        assert call_args[4] == [interceptor1]