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) -> Result<A2aClient, ClientError>

Validates configuration and constructs the A2aClient.

Binding names are matched ignoring ASCII case, as card selection matches them. When the builder came from a card and the chosen interface cannot be constructed here — gRPC (which needs build_grpc), a binding this SDK does not implement, or a malformed URL — the card’s next compatible interface is tried, in from_card_preferring’s order, and its endpoint and tenant are used. A binding set with with_protocol_binding is never substituted.

Errors

• ClientError::InvalidEndpoint if the endpoint URL is malformed.
• ClientError::Transport if the selected transport cannot be initialized; after fallbacks, it names every interface tried.

pub async fn build_grpc(self) -> Result<A2aClient, ClientError>

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>) -> ClientBuilder

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) -> Result<ClientBuilder, ClientError>

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

Selection follows from_card_preferring.

Errors

Returns ClientError::InvalidEndpoint if the card has no interfaces, or none for this SDK’s A2A protocol major.

pub fn from_card_preferring( card: &AgentCard, preferences: &[String], ) -> Result<ClientBuilder, ClientError>

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

Only interfaces whose protocolVersion has this SDK’s major (1; an empty version counts, and a leading v is allowed) are considered. An agent that also serves v0.3 often lists that endpoint first; it speaks another protocol, so it is skipped rather than connected to.

Binding names compare ignoring ASCII case. 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.

The remaining compatible interfaces are kept, in the same order, as fallbacks: build moves to the next one when the chosen interface cannot be constructed (a gRPC interface needs build_grpc, a binding this SDK does not implement, a malformed URL).

Errors

Returns ClientError::InvalidEndpoint if the card has no interfaces, or none for this SDK’s A2A protocol major; the message lists what the card offers. Earlier releases accepted such a card with a warning, and it failed at the first call instead.

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

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

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

Sets the timeout for establishing a stream: until the response headers arrive, or for reading the error body when the answer is not a stream. Defaults to 30 seconds.

It no longer bounds the wait for the first event — use with_stream_first_event_timeout for that. If you set this short to fail fast on a silent agent, set that one to the same value.

pub const fn with_stream_first_event_timeout( self, timeout: Duration, ) -> ClientBuilder

Sets how long an established stream may wait for its first data — an event or a keep-alive comment — before it fails with ClientError::Timeout.

Defaults to 5 minutes; see DEFAULT_STREAM_FIRST_EVENT_TIMEOUT for why.

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

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_stream_idle_timeout( self, timeout: Option<Duration>, ) -> ClientBuilder

Sets how long an established stream may receive no data at all — events and keep-alive comments alike — before it fails with ClientError::Timeout. None disables the bound.

Defaults to 5 minutes; see ClientConfig::stream_idle_timeout for how it applies per transport and DEFAULT_STREAM_IDLE_TIMEOUT for why that value.

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

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 const fn with_max_event_size(self, max_bytes: usize) -> ClientBuilder

Sets the largest single stream event accepted, in bytes; larger events are refused and skipped. Defaults to 16 MiB. See ClientConfig::max_event_size.

pub fn chosen_interface(&self) -> Option<&AgentInterface>

The card interface this builder will connect to, when it came from one.

from_card takes the first interface whose binding the caller prefers, else the card’s first, and with_protocol_binding can move it. This is the outcome of those rules, so a caller who needs a constructor the builder does not drive itself — a WebSocketTransport (behind the websocket feature) for with_custom_transport, or build_grpc (behind the grpc feature) rather than build — reads the endpoint and binding here instead of re-implementing the preference.

None when the builder came from ClientBuilder::new, and after with_protocol_binding named a binding the card does not advertise: the endpoint is then whatever the caller set, which is not a card interface.

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

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 const fn with_grpc_bare_address_scheme( self, scheme: GrpcBareAddressScheme, ) -> ClientBuilder

Sets how a bare host:port gRPC interface address is dialled.

A card’s gRPC url is a gRPC target with no scheme. The default (GrpcBareAddressScheme::HttpsExceptLoopback) uses TLS for every host except loopback; a deployment whose plaintext gRPC lives on a private network sets GrpcBareAddressScheme::Http. Only build_grpc (behind the grpc feature) reads this; an address that already carries a scheme is unaffected.

pub fn with_grpc_tls_config(self, tls: ClientTlsConfig) -> ClientBuilder

Sets the TLS configuration build_grpc (behind the grpc feature) uses for an https:// endpoint, explicit or chosen by the bare-address policy: a private CA, a client certificate, or a server name that differs from the host. Without it the server is verified against the bundled Mozilla roots. The type is re-exported as transport::grpc::ClientTlsConfig.

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

Sets the accepted output modes sent in SendMessage configurations.

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

Sets the history length to request in task responses.

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

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) -> ClientBuilder

Sets return_immediately for SendMessage calls.

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

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) -> ClientBuilder

Disables TLS (plain HTTP only).

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

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 const fn with_peer_honouring_idempotency( self, honours: bool, ) -> ClientBuilder

Asserts that the peer honours idempotency keys on message/send.

Only needed when the client was not built from an agent card: from_card reads the advertisement itself.

What this changes, and what it costs to get wrong

SendMessage is not retried after an ambiguous failure — a connection dropped after the request bytes went out — because the send may have executed. A key the server deduplicates on removes that ambiguity, so a keyed send becomes retryable. Setting this for a peer that does not honour the key re-introduces exactly the double execution the rule exists to prevent: the key rides in Message.metadata, which A2A defines as free-form, so a server that has never heard of the extension ignores it and runs the send again.

Assert it only for a peer you know implements https://a2a-rust.com/extensions/idempotency/v1.

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

where I: CallInterceptor,

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<(), Error>

Formats the value using the given formatter.