Configuration Reference

Complete reference of all configuration options across a2a-rust crates.

Server Configuration

RequestHandlerBuilder

Option	Type	Default	Description
`with_agent_card`	`AgentCard`	None	Discovery card for `/.well-known/agent-card.json`
`with_task_store`	`impl TaskStore`	`InMemoryTaskStore`	Custom task storage backend
`with_task_store_config`	`TaskStoreConfig`	1hr TTL, 10k capacity	TTL and capacity for default store
`with_push_config_store`	`impl PushConfigStore`	`InMemoryPushConfigStore`	Custom push config storage
`with_push_sender`	`impl PushSender`	None	Webhook delivery implementation
`with_interceptor`	`impl ServerInterceptor`	Empty chain	Server middleware
`with_executor_timeout`	`Duration`	1 hour	Max time for executor completion (`DEFAULT_EXECUTOR_TIMEOUT`); `without_executor_timeout()` removes the bound
`with_event_queue_capacity`	`usize`	256	Bounded channel size per stream. Increased from 64 to push the per-event cost inflection from ~52 to ~252 events. Increase further for tasks producing >250 events.
`with_max_event_size`	`usize`	16 MiB	Max serialized SSE event size
`with_max_concurrent_streams`	`usize`	1,024	Limit concurrent SSE connections (pass `usize::MAX` to disable)
`with_metrics`	`impl Metrics`	`NoopMetrics`	Metrics observer for handler activity
`with_handler_limits`	`HandlerLimits`	See below	Configurable validation limits
`allow_undeclared_input_modes()`	—	Off	Accept message parts whose `mediaType` the card's input modes do not declare; by default, when the card declares any, such a part is refused with `ContentTypeNotSupportedError`

HandlerLimits

Field	Type	Default	Description
`max_id_length`	`usize`	1,024	Maximum task/context ID length
`max_metadata_size`	`usize`	1 MiB	Maximum serialized metadata size
`max_cancellation_tokens`	`usize`	10,000	Cleanup sweep threshold
`max_token_age`	`Duration`	1 hour	Stale token eviction age
`push_delivery_timeout`	`Duration`	5s	Per-webhook delivery timeout
`push_delivery_budget`	`Duration`	30s	Total push-delivery time per event, across all configs
`executor_drain_timeout`	`Duration`	5s	Bound on the blocking path's wait for the queue to close after the executor finished; also how long a continuation waits for a parked (`input-required`/`auth-required`) turn's executor to return
`max_artifacts_per_task`	`usize`	1,000	Maximum artifacts per task (prevents O(n²) serialization)
`max_context_locks`	`usize`	10,000	Max per-context locks before cleanup
`max_push_configs_per_task`	`usize`	100	Maximum push configs per task (uniform across store backends)
`max_parts_per_artifact`	`usize`	10,000	Maximum parts a single artifact may accumulate
`max_total_push_configs`	`usize`	100,000	Global push-config ceiling across all tasks
`subscribe_reattach_interval`	`Duration`	250ms	How often an idle `SubscribeToTask` stream re-checks whether its task finished, once the turn's queue closed
`subscribe_max_idle`	`Duration`	5 min	How long a `SubscribeToTask` stream waits on a parked task before ending; the client resubscribes
`subscribe_replay_limit`	`usize`	1,000	Maximum logged events a `Last-Event-ID` resumption replays. The offset is client-supplied, so the cap bounds the read; every replayed frame carries its own `id:`, so a truncated replay is resumable
`subscribe_replay_catchup`	`Duration`	2s	How long a resuming stream waits for the event log to catch up with what was already broadcast. Zero disables the wait; on expiry the shortfall is logged and counted under `event_log_catchup`

Build-time validation: max_id_length, max_metadata_size, and push_delivery_timeout must be non-zero. Zero values are rejected by RequestHandlerBuilder::build().

TaskStoreConfig

Field	Type	Default	Description
`max_capacity`	`Option<usize>`	10,000	Maximum stored tasks; oldest terminal tasks evicted on overflow
`task_ttl`	`Option<Duration>`	1 hour	TTL for completed/failed tasks
`eviction_interval`	`u64`	64	Writes between automatic eviction sweeps
`max_page_size`	`u32`	1,000	Maximum tasks per page in list queries
`max_events_per_task`	`Option<usize>`	512	Events one task's log keeps for `Last-Event-ID` resumption; `None` removes the bound
`idempotency_key_ttl`	`Option<Duration>`	24 hours	How long an idempotency key is honoured, matching the SQL stores' one day; `None` keeps keys forever

InMemoryPushConfigStore

Constructor	Default	Description
`::new()`	100	Default max push configs per task
`::with_max_configs_per_task(N)`	—	Custom per-task push config limit

DispatchConfig

Shared configuration for JSON-RPC, REST, and Axum dispatchers. Pass to JsonRpcDispatcher::with_config(), RestDispatcher::with_config(), or A2aRouter::with_config().

Field	Type	Default	Description
`max_request_body_size`	`usize`	4 MiB	Larger bodies return 413
`body_read_timeout`	`Duration`	30s	Slow loris protection
`max_query_string_length`	`usize`	4,096	REST only; longer queries return 414
`sse_keep_alive_interval`	`Duration`	30s	Periodic keep-alive comment interval for SSE streams
`sse_channel_capacity`	`usize`	64	SSE response body channel buffer size
`max_batch_size`	`usize`	100	Maximum requests in a JSON-RPC batch
`require_version_header`	`bool`	true	Reject a data-plane request with no `A2A-Version` header as `VersionNotSupported` (spec §3.6.2: absent means 0.3)

GrpcConfig

Configuration for the gRPC dispatcher (requires grpc feature).

Field	Type	Default	Description
`max_message_size`	`usize`	4 MiB	Maximum inbound/outbound message size
`concurrency_limit`	`usize`	256	Max concurrent gRPC requests per connection
`stream_channel_capacity`	`usize`	64	Bounded channel for streaming responses
`require_version_header`	`bool`	true	Reject a call with no `a2a-version` metadata as `VersionNotSupported`

PushRetryPolicy

Configurable retry policy for HttpPushSender. Pass via HttpPushSender::with_retry_policy().

Field	Type	Default	Description
`max_attempts`	`usize`	3	Maximum delivery attempts
`backoff`	`Vec<Duration>`	`[1s, 2s]`	Backoff durations between retries

RateLimitConfig

Field	Type	Default	Description
`requests_per_window`	`u64`	100	Max requests per caller per window
`window_secs`	`u64`	60	Window duration in seconds
`trusted_proxy_hops`	`usize`	0	How many `X-Forwarded-For` hops to trust (0 = ignore XFF entirely)
`max_buckets`	`usize`	10,000	Hard bound on tracked caller buckets (fail-closed when full)

Limits for a Server (Server::bind(addr).await?.with_config(config)). The three shutdown phases run in order — completion_grace, then task_grace, then drain_timeout — and the gRPC and WebSocket dispatchers' serve_with_shutdown take the same three through their own with_completion_grace, with_task_grace and with_drain_timeout.

Field	Type	Default	Description
`max_connections`	`Option<usize>`	None	Ceiling on connections served at once; `None` is unbounded
`completion_grace`	`Duration`	5s	On shutdown, how long in-flight tasks get to finish on their own before they are cancelled (`DEFAULT_COMPLETION_GRACE`)
`task_grace`	`Duration`	10s	How long cancelled tasks get to cancel what they delegated and write a terminal event (`DEFAULT_TASK_GRACE`)
`drain_timeout`	`Duration`	15s	How long connections get to finish before they are reported abandoned (`DEFAULT_DRAIN_TIMEOUT`)
`header_read_timeout`	`Option<Duration>`	30s	How long a peer may take to send complete request headers; `None` disables
`idle_timeout`	`Option<Duration>`	75s	How long a connection may carry no traffic before it is closed; `None` disables

Internal Limits

Limit	Value	Description
Event queue type	`broadcast`	Fan-out to multiple subscribers; a reader that falls behind the ring receives a `streamLagged` error and its stream ends (no silent gap)
Rate limiter cleanup interval	256 checks	Stale buckets (from departed callers) evicted every 256 `check()` calls
Rate limiter window CAS	Lock-free	Window transitions use `compare_exchange` to avoid TOCTOU races
Credential store poisoning	Fail-fast	`InMemoryCredentialsStore` panics on poisoned locks rather than returning `None`

Client Configuration

ClientBuilder

Option	Type	Default	Description
`with_protocol_binding`	`impl Into<String>`	`"JSONRPC"` (`new`); the card's interface chosen by `preferred_bindings` (`from_card`)	Transport: `"JSONRPC"`, `"HTTP+JSON"` (alias `"REST"`), or `"GRPC"` — the last needs `build_grpc()`; `build()` refuses it
`with_timeout`	`Duration`	30s	Per-request timeout
`with_connection_timeout`	`Duration`	10s	TCP connection timeout
`with_stream_connect_timeout`	`Duration`	30s	Establishing a stream: until the response headers (gRPC: until the call is accepted)
`with_stream_first_event_timeout`	`Duration`	5 min	Wait for a stream's first data (an event or a keep-alive) once established
`with_max_event_size`	`usize`	16 MiB	Largest single stream event accepted; larger ones are refused and skipped
`with_stream_idle_timeout`	`Option<Duration>`	5 min	Longest an established stream may receive nothing — keep-alive comments count — after its first data; `None` disables
`with_retry_policy`	`RetryPolicy`	None	Retry on transient errors with jittered backoff
`with_accepted_output_modes`	`Vec<String>`	`["text/plain", "application/json"]`	MIME types accepted
`with_history_length`	`u32`	None	Messages in responses
`with_return_immediately`	`bool`	false	Don't wait for completion
`with_tenant`	`impl Into<String>`	None (auto from `AgentCard`)	Tenant sent on every request (spec §8.3.2 rule 4); a per-request `tenant` overrides it
`with_grpc_bare_address_scheme`	`GrpcBareAddressScheme`	`HttpsExceptLoopback`	How `build_grpc` dials a card's bare `host:port` gRPC target: TLS except for loopback (default), always TLS, or always plaintext
`with_grpc_tls_config`	`ClientTlsConfig`	None (bundled Mozilla roots)	`grpc-tls` feature: the TLS settings `build_grpc` uses for an `https://` endpoint, explicit or policy-chosen — a private CA, a client certificate, or a server name that differs from the host
`with_interceptor`	`impl CallInterceptor`	Empty chain	Client middleware

GrpcTransportConfig

Configuration for the gRPC client transport (requires grpc feature). The struct is #[non_exhaustive]: build it with GrpcTransportConfig::default() and the with_* setters.

Field	Type	Default	Description
`timeout`	`Duration`	30s	Per-request timeout
`connect_timeout`	`Duration`	10s	Connection timeout
`max_message_size`	`usize`	4 MiB	Maximum message size
`stream_channel_capacity`	`usize`	64	Streaming response buffer
`bare_address_scheme`	`GrpcBareAddressScheme`	`HttpsExceptLoopback`	Scheme used for a bare `host:port` target (an `http://`/`https://` URL is used as-is)
`tls_config`	`Option<ClientTlsConfig>`	None (bundled Mozilla roots)	`grpc-tls` feature: pin a private CA or present a client certificate for `https://` endpoints

RetryPolicy

Field	Type	Default	Description
`max_retries`	`u32`	3	Maximum retry attempts
`initial_backoff`	`Duration`	500ms	Backoff before first retry
`max_backoff`	`Duration`	30s	Caps exponential growth
`backoff_multiplier`	`f64`	2.0	Multiplier per retry

SSE Parser Limits

Limit	Value	Description
Event size	16 MiB (`ClientBuilder::with_max_event_size`)	Largest single stream event; larger ones are refused with an error and skipped, and a line that outgrows it is refused as soon as it does (aligned with server)
Stream connect timeout	30s (`with_stream_connect_timeout`)	Until the response headers; the first event then has its own 5-minute bound

HTTP Caching (Agent Card)

Header	Default	Description
`Cache-Control`	`public, max-age=3600`	Configurable max-age (default 1 hour)
`ETag`	Auto-computed	Content hash
`Last-Modified`	Auto-set	Timestamp of last change

Feature Flags

`a2a-protocol-server`

Feature	Default	Description
`signing`	Off	Forwards `a2a-protocol-types/signing`; the server itself neither signs nor verifies the card it serves
`tracing`	On	Structured logging via `tracing` crate; `default-features = false` compiles it out
`tls-rustls`	Off	HTTPS delivery for the bundled push-notification sender
`sqlite`	Off	SQLite-backed task and push config stores via `sqlx`
`postgres`	Off	PostgreSQL-backed task and push config stores via `sqlx`
`websocket`	Off	WebSocket transport via `tokio-tungstenite`
`grpc`	Off	gRPC transport via `tonic` (plaintext listener)
`grpc-tls`	Off	TLS on the gRPC listener itself: `GrpcDispatcher::with_tls(ServerTlsConfig)` with a server identity and, optionally, a client CA for mutual TLS; implies `grpc`; the TLS types are re-exported from `dispatch::grpc`
`otel`	Off	OpenTelemetry metrics and spans via `opentelemetry-otlp` / `tracing-opentelemetry` (implies `tracing`)
`conformance`	Off	A harness that grades an `AgentExecutor` against the protocol's invariants
`axum`	Off	Axum framework integration (`A2aRouter`)
`auth-jwt`	Off	JWT bearer-token authentication (`JwtAuthInterceptor`)

`a2a-protocol-client`

Feature	Default	Description
`signing`	Off	Forwards `a2a-protocol-types/signing`; the client itself neither signs nor verifies anything
`tracing`	On	Structured logging via `tracing` crate; `default-features = false` compiles it out
`tls-rustls`	On	HTTPS via rustls (no OpenSSL dependency); `default-features = false` for a plaintext-only build
`websocket`	Off	WebSocket transport via `tokio-tungstenite`
`grpc`	Off	gRPC transport via `tonic` (plaintext; `https://` is refused with a message naming `grpc-tls`)
`grpc-tls`	Off	gRPC over TLS: implies `grpc` (not `tls-rustls`), verifies against the bundled Mozilla roots or a supplied `ClientTlsConfig` (re-exported from `transport::grpc`)
`testing`	Off	A scripted hostile peer (`testing::ScriptedPeer`) that stalls, cuts off, mis-frames or refuses on each binding, for testing code that calls agents

`a2a-protocol-types`

Feature	Default	Description
`signing`	Off	JWS/ES256 agent card signing (RFC 8785 canonicalization)
`proto`	Off	Canonical protobuf message types and the JSON⇄proto conversions (turned on by `grpc`)

`a2a-protocol-sdk` (umbrella)

Feature	Default	Description
`signing`	Off	Enables `signing` in all sub-crates
`tracing`	On	Enables `tracing` in client and server
`tls-rustls`	On	Enables `tls-rustls` in client and server
`grpc`	Off	Enables `grpc` in client and server
`grpc-tls`	Off	Enables `grpc-tls` in the client and the server: `https://` dialling on one side, `GrpcDispatcher::with_tls` on the other
`websocket`	Off	Enables `websocket` in client and server
`sqlite`	Off	Enables `sqlite` in the server
`postgres`	Off	Enables `postgres` in the server
`otel`	Off	Enables `otel` in the server
`axum`	Off	Enables `axum` in the server
`auth-jwt`	Off	Enables `auth-jwt` in the server

Environment Variables

Variable	Description
`RUST_LOG`	Log level filter (when the `tracing` feature is enabled — every crate's default — and a subscriber reads it)

Examples:

RUST_LOG=info              # Info and above
RUST_LOG=debug             # Debug and above
RUST_LOG=a2a_protocol_server=debug  # Debug for server crate only
RUST_LOG=a2a_protocol_server=trace,a2a_protocol_client=debug  # Per-crate levels

Next Steps

API Quick Reference — All public types at a glance
Pitfalls & Lessons Learned — Known issues and workarounds