refactor(client)!: reorganize ClientFactory API

Author: ishymko

itk/main.py

@@ -12,7 +12,7 @@
 
 from pyproto import instruction_pb2
 
-from a2a.client import ClientConfig, ClientFactory
+from a2a.client import ClientConfig, create_client
 from a2a.compat.v0_3 import a2a_v0_3_pb2_grpc
 from a2a.compat.v0_3.grpc_handler import CompatGrpcHandler
 from a2a.server.agent_execution import AgentExecutor, RequestContext
@@ -128,10 +128,7 @@ async def handle_call_agent(call: instruction_pb2.CallAgent) -> list[str]:
     )
 
     try:
-        client = await ClientFactory.connect(
-            call.agent_card_uri,
-            client_config=config,
-        )
+        client = await create_client(call.agent_card_uri, client_config=config)
 
         # Wrap nested instruction
         async with client:

samples/cli.py

@@ -9,7 +9,7 @@
 import grpc
 import httpx
 
-from a2a.client import A2ACardResolver, ClientConfig, ClientFactory
+from a2a.client import A2ACardResolver, ClientConfig, create_client
 from a2a.types import Message, Part, Role, SendMessageRequest, TaskState
 
 
@@ -79,7 +79,7 @@ async def main() -> None:
         print('\n✓ Agent Card Found:')
         print(f'  Name: {card.name}')
 
-    client = await ClientFactory.connect(card, client_config=config)
+    client = await create_client(card, client_config=config)
 
     actual_transport = getattr(client, '_transport', client)
     print(f'  Picked Transport: {actual_transport.__class__.__name__}')

src/a2a/client/__init__.py

@@ -12,7 +12,11 @@
     ClientCallContext,
     ClientConfig,
 )
-from a2a.client.client_factory import ClientFactory, minimal_agent_card
+from a2a.client.client_factory import (
+    ClientFactory,
+    create_client,
+    minimal_agent_card,
+)
 from a2a.client.errors import (
     A2AClientError,
     A2AClientTimeoutError,
@@ -36,6 +40,7 @@
     'ClientFactory',
     'CredentialService',
     'InMemoryContextCredentialStore',
+    'create_client',
     'create_text_message_object',
     'minimal_agent_card',
 ]

src/a2a/client/client_factory.py

@@ -56,35 +56,146 @@
 
 
 class ClientFactory:
-    """ClientFactory is used to generate the appropriate client for the agent.
+    """Factory for creating clients that communicate with A2A agents.
 
-    The factory is configured with a `ClientConfig` and optionally a list of
-    `Consumer`s to use for all generated `Client`s. The expected use is:
-
-    .. code-block:: python
+    The factory is configured with a `ClientConfig` and optionally custom
+    transport producers registered via `register`. Example usage:
 
         factory = ClientFactory(config)
-        # Optionally register custom client implementations
-        factory.register('my_customer_transport', NewCustomTransportClient)
-        # Then with an agent card make a client with additional interceptors
+        # Optionally register custom transport implementations
+        factory.register('my_custom_transport', custom_transport_producer)
+        # Create a client from an AgentCard
         client = factory.create(card, interceptors)
+        # Or resolve an AgentCard from a URL and create a client
+        client = await factory.create_from_url('https://example.com')
 
-    Now the client can be used consistently regardless of the transport. This
+    The client can be used consistently regardless of the transport. This
     aligns the client configuration with the server's capabilities.
     """
 
     def __init__(
         self,
         config: ClientConfig,
     ):
-        client = config.httpx_client or httpx.AsyncClient()
-        client.headers.setdefault(VERSION_HEADER, PROTOCOL_VERSION_CURRENT)
-        config.httpx_client = client
+        httpx_client = config.httpx_client or httpx.AsyncClient()
+        httpx_client.headers.setdefault(
+            VERSION_HEADER, PROTOCOL_VERSION_CURRENT
+        )
+        config.httpx_client = httpx_client
 
         self._config = config
+        self._httpx_client = httpx_client
         self._registry: dict[str, TransportProducer] = {}
         self._register_defaults(config.supported_protocol_bindings)
 
+    def register(self, label: str, generator: TransportProducer) -> None:
+        """Register a new transport producer for a given transport label."""
+        self._registry[label] = generator
+
+    def create(
+        self,
+        card: AgentCard,
+        interceptors: list[ClientCallInterceptor] | None = None,
+    ) -> Client:
+        """Create a new `Client` for the provided `AgentCard`.
+
+        Args:
+          card: An `AgentCard` defining the characteristics of the agent.
+          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.
+
+        Returns:
+          A `Client` object.
+
+        Raises:
+          If there is no valid matching of the client configuration with the
+          server configuration, a `ValueError` is raised.
+        """
+        client_set = self._config.supported_protocol_bindings or [
+            TransportProtocol.JSONRPC
+        ]
+        transport_protocol = None
+        selected_interface = None
+        if self._config.use_client_preference:
+            for protocol_binding in client_set:
+                selected_interface = ClientFactory._find_best_interface(
+                    list(card.supported_interfaces),
+                    protocol_bindings=[protocol_binding],
+                )
+                if selected_interface:
+                    transport_protocol = protocol_binding
+                    break
+        else:
+            for supported_interface in card.supported_interfaces:
+                if supported_interface.protocol_binding in client_set:
+                    transport_protocol = supported_interface.protocol_binding
+                    selected_interface = ClientFactory._find_best_interface(
+                        list(card.supported_interfaces),
+                        protocol_bindings=[transport_protocol],
+                    )
+                    break
+        if not transport_protocol or not selected_interface:
+            raise ValueError('no compatible transports found.')
+        if transport_protocol not in self._registry:
+            raise ValueError(f'no client available for {transport_protocol}')
+
+        transport = self._registry[transport_protocol](
+            card, selected_interface.url, self._config
+        )
+
+        if selected_interface.tenant:
+            transport = TenantTransportDecorator(
+                transport, selected_interface.tenant
+            )
+
+        return BaseClient(
+            card,
+            self._config,
+            transport,
+            interceptors or [],
+        )
+
+    async def create_from_url(
+        self,
+        url: str,
+        interceptors: list[ClientCallInterceptor] | None = None,
+        relative_card_path: str | None = None,
+        resolver_http_kwargs: dict[str, Any] | None = None,
+        signature_verifier: Callable[[AgentCard], None] | None = None,
+    ) -> Client:
+        """Create a `Client` by resolving an `AgentCard` from a URL.
+
+        Resolves the agent card from the given URL using the factory's
+        configured httpx client, then creates a client via `create`.
+
+        If the agent card is already available, use `create` directly
+        instead.
+
+        Args:
+          url: The base URL of the agent. The agent card will be fetched
+            from `<url>/.well-known/agent-card.json` by default.
+          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: The relative path when resolving the agent
+            card. See `A2ACardResolver.get_agent_card` for details.
+          resolver_http_kwargs: Dictionary of arguments to provide to the
+            httpx client when resolving the agent card.
+          signature_verifier: A callable used to verify the agent card's
+            signatures.
+
+        Returns:
+          A `Client` object.
+        """
+        resolver = A2ACardResolver(self._httpx_client, url)
+        card = await resolver.get_agent_card(
+            relative_card_path=relative_card_path,
+            http_kwargs=resolver_http_kwargs,
+            signature_verifier=signature_verifier,
+        )
+        return self.create(card, interceptors)
+
     def _register_defaults(self, supported: list[str]) -> None:
         # Empty support list implies JSON-RPC only.
 
@@ -252,141 +363,47 @@ def _find_best_interface(
 
         return best_gt_1_0 or best_ge_0_3 or best_no_version
 
-    @classmethod
-    async def connect(  # noqa: PLR0913
-        cls,
-        agent: str | AgentCard,
-        client_config: ClientConfig | 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,
-        signature_verifier: Callable[[AgentCard], None] | 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.
-
-          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.
-          signature_verifier: A callable used to verify the agent card's signatures.
-
-        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,
-                        signature_verifier=signature_verifier,
-                    )
-            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,
-                    signature_verifier=signature_verifier,
-                )
-        else:
-            card = agent
-        factory = cls(client_config)
-        for label, generator in (extra_transports or {}).items():
-            factory.register(label, generator)
-        return factory.create(card, interceptors)
-
-    def register(self, label: str, generator: TransportProducer) -> None:
-        """Register a new transport producer for a given transport label."""
-        self._registry[label] = generator
-
-    def create(
-        self,
-        card: AgentCard,
-        interceptors: list[ClientCallInterceptor] | None = None,
-    ) -> Client:
-        """Create a new `Client` for the provided `AgentCard`.
-
-        Args:
-          card: An `AgentCard` defining the characteristics of the agent.
-          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.
 
-        Returns:
-          A `Client` object.
-
-        Raises:
-          If there is no valid matching of the client configuration with the
-          server configuration, a `ValueError` is raised.
-        """
-        client_set = self._config.supported_protocol_bindings or [
-            TransportProtocol.JSONRPC
-        ]
-        transport_protocol = None
-        selected_interface = None
-        if self._config.use_client_preference:
-            for protocol_binding in client_set:
-                selected_interface = ClientFactory._find_best_interface(
-                    list(card.supported_interfaces),
-                    protocol_bindings=[protocol_binding],
-                )
-                if selected_interface:
-                    transport_protocol = protocol_binding
-                    break
-        else:
-            for supported_interface in card.supported_interfaces:
-                if supported_interface.protocol_binding in client_set:
-                    transport_protocol = supported_interface.protocol_binding
-                    selected_interface = ClientFactory._find_best_interface(
-                        list(card.supported_interfaces),
-                        protocol_bindings=[transport_protocol],
-                    )
-                    break
-        if not transport_protocol or not selected_interface:
-            raise ValueError('no compatible transports found.')
-        if transport_protocol not in self._registry:
-            raise ValueError(f'no client available for {transport_protocol}')
-
-        transport = self._registry[transport_protocol](
-            card, selected_interface.url, self._config
-        )
-
-        if selected_interface.tenant:
-            transport = TenantTransportDecorator(
-                transport, selected_interface.tenant
-            )
-
-        return BaseClient(
-            card,
-            self._config,
-            transport,
-            interceptors or [],
+async def create_client(  # noqa: PLR0913
+    agent: str | AgentCard,
+    client_config: ClientConfig | None = None,
+    interceptors: list[ClientCallInterceptor] | None = None,
+    relative_card_path: str | None = None,
+    resolver_http_kwargs: dict[str, Any] | None = None,
+    signature_verifier: Callable[[AgentCard], None] | None = None,
+) -> Client:
+    """Create a `Client` for an agent from a URL or `AgentCard`.
+
+    Convenience function that constructs a `ClientFactory` internally.
+    For reusing a factory across multiple agents or registering custom
+    transports, use `ClientFactory` directly instead.
+
+    Args:
+      agent: The base URL of the agent, or an `AgentCard` to use
+        directly.
+      client_config: Optional `ClientConfig`. A default config is
+        created if not provided.
+      interceptors: A list of interceptors to use for each request.
+      relative_card_path: The relative path when resolving the agent
+        card. Only used when `agent` is a URL.
+      resolver_http_kwargs: Dictionary of arguments to provide to the
+        httpx client when resolving the agent card.
+      signature_verifier: A callable used to verify the agent card's
+        signatures.
+
+    Returns:
+      A `Client` object.
+    """
+    factory = ClientFactory(client_config or ClientConfig())
+    if isinstance(agent, str):
+        return await factory.create_from_url(
+            agent,
+            interceptors=interceptors,
+            relative_card_path=relative_card_path,
+            resolver_http_kwargs=resolver_http_kwargs,
+            signature_verifier=signature_verifier,
         )
+    return factory.create(agent, interceptors)
 
 
 def minimal_agent_card(