Struct ClientBuilder 

pub struct ClientBuilder { /* private fields */ }

Builder for A2aClient.

Start with ClientBuilder::new (URL) or ClientBuilder::from_card (agent card auto-configuration).

Implementations

impl ClientBuilder

pub fn build(self) -> ClientResult<A2aClient>

Validates configuration and constructs the A2aClient.

Errors

• ClientError::InvalidEndpoint if the endpoint URL is malformed.
• ClientError::Transport if the selected transport cannot be initialized.

pub async fn build_grpc(self) -> ClientResult<A2aClient>

Validates configuration and constructs a gRPC-backed A2aClient.

Unlike build, this method is async because gRPC transport requires establishing a connection.

Errors

• ClientError::InvalidEndpoint if the endpoint URL is malformed.
• ClientError::Transport if the gRPC connection fails.

impl ClientBuilder

pub fn new(endpoint: impl Into<String>) -> Self

Creates a builder targeting endpoint.

The endpoint is passed directly to the selected transport; it should be the full base URL of the agent (e.g. http://localhost:8080).

pub fn from_card(card: &AgentCard) -> ClientResult<Self>

Creates a builder pre-configured from an AgentCard, preferring the bindings in ClientConfig::preferred_bindings order.

Errors

Returns ClientError::InvalidEndpoint if the card has no interfaces.

pub fn from_card_preferring( card: &AgentCard, preferences: &[String], ) -> ClientResult<Self>

Creates a builder from an AgentCard, choosing the first interface whose binding appears in preferences.

preferences is the client’s order, not the card’s: the first preference the agent actually offers wins. When the agent offers none of them, the card’s first interface is used, because an agent that speaks only bindings this caller did not rank is still worth talking to — and failing to connect would be a worse answer than connecting over something unranked.

Why this exists

ClientConfig::preferred_bindings has documented exactly this since it was introduced — “the client tries each in order, selecting the first one supported by the target agent’s card” — and nothing read the field. from_card took supported_interfaces.first(), which is the agent’s first choice, inverting the preference the field describes. A caller who ranked GRPC first and met a card listing [JSONRPC, GRPC] silently got JSONRPC.

Logs a warning (via tracing, if enabled) when the agent’s protocol version is outside the supported range.

Errors

Returns ClientError::InvalidEndpoint if the card has no interfaces.

pub const fn with_timeout(self, timeout: Duration) -> Self

Sets the per-request timeout for non-streaming calls.

pub const fn with_stream_connect_timeout(self, timeout: Duration) -> Self

Sets the timeout for establishing SSE stream connections.

Once the stream is established, this timeout no longer applies. Defaults to 30 seconds.

pub const fn with_connection_timeout(self, timeout: Duration) -> Self

Sets the TCP connection timeout (DNS + handshake).

Defaults to 10 seconds. Prevents hanging for the OS default (~2 min) when the server is unreachable.

pub const fn with_max_response_size(self, max_bytes: usize) -> Self

Sets the maximum size in bytes of a buffered (non-streaming) response body. Responses exceeding the cap fail with a transport error instead of being buffered without bound.

Defaults to 32 MiB.

pub fn with_protocol_binding(self, binding: impl Into<String>) -> Self

Sets the protocol binding, overriding any derived from the agent card.

When this builder came from ClientBuilder::from_card and the card advertises binding, the endpoint and tenant move to that interface too. A card gives each binding its own URL, so binding and endpoint are a pair: setting only the binding left the client speaking the new protocol to the old one’s port — a card offering JSONRPC at :1111 and GRPC at :2222 produced gRPC-against-:1111, with no error.

If the card does not advertise binding — or the builder came from ClientBuilder::new — only the binding changes and the endpoint is left as the caller set it. There is nothing to resolve against, and the caller is assumed to know their own URL.

Ordering: this re-resolves the tenant from the card, so call ClientBuilder::with_tenant after this to override it.

pub fn with_accepted_output_modes(self, modes: Vec<String>) -> Self

Sets the accepted output modes sent in SendMessage configurations.

pub const fn with_history_length(self, length: u32) -> Self

Sets the history length to request in task responses.

pub fn with_tenant(self, tenant: impl Into<String>) -> Self

Sets the default tenant for multi-tenancy.

When set, this tenant is included in all requests unless overridden per-request. Automatically populated from AgentInterface.tenant when building via ClientBuilder::from_card.

pub const fn with_return_immediately(self, val: bool) -> Self

Sets return_immediately for SendMessage calls.

pub fn with_custom_transport(self, transport: impl Transport) -> Self

Provides a fully custom transport implementation.

Overrides the transport that would normally be built from the endpoint URL and protocol preference.

pub const fn without_tls(self) -> Self

Disables TLS (plain HTTP only).

pub const fn with_retry_policy(self, policy: RetryPolicy) -> Self

Sets a retry policy for transient failures.

When set, the client automatically retries requests that fail with transient errors (connection errors, timeouts, HTTP 429/502/503/504) using exponential backoff.

Example

use a2a_protocol_client::{ClientBuilder, RetryPolicy};

let client = ClientBuilder::new("http://localhost:8080")
    .with_retry_policy(RetryPolicy::default())
    .build()?;

pub fn with_interceptor<I: CallInterceptor>(self, interceptor: I) -> Self

Adds an interceptor to the chain.

Interceptors are run in the order they are added.

Trait Implementations

impl Debug for ClientBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.