Struct AgentClientV2 

pub struct AgentClientV2 { /* private fields */ }

v2 agent client with connection multiplexing.

This client maintains a single bidirectional stream and multiplexes multiple requests over it using correlation IDs.

Features

• Connection multiplexing: Multiple concurrent requests over one connection
• Cancellation support: Cancel in-flight requests
• Flow control: Backpressure handling when agent is overloaded
• Health tracking: Monitor agent health status
• Metrics collection: Receive and forward agent metrics

Implementations

impl AgentClientV2

pub async fn new( agent_id: impl Into<String>, endpoint: impl Into<String>, timeout: Duration, ) -> Result<Self, AgentProtocolError>

Create a new v2 client.

pub fn set_metrics_callback(&mut self, callback: MetricsCallback)

Set the metrics callback for receiving agent metrics reports.

This callback is invoked whenever the agent sends a metrics report through the control stream. The callback should be fast and non-blocking.

pub fn set_config_update_callback(&mut self, callback: ConfigUpdateCallback)

Set the config update callback for handling agent config requests.

This callback is invoked whenever the agent sends a config update request through the control stream (e.g., requesting a reload, reporting errors).

pub async fn connect(&self) -> Result<(), AgentProtocolError>

Connect and perform handshake.

pub async fn send_request_headers( &self, correlation_id: &str, event: &RequestHeadersEvent, ) -> Result<AgentResponse, AgentProtocolError>

Send a request headers event and wait for response.

pub async fn send_request_body_chunk( &self, correlation_id: &str, event: &RequestBodyChunkEvent, ) -> Result<AgentResponse, AgentProtocolError>

Send a request body chunk event and wait for response.

For streaming body inspection, chunks are sent sequentially with increasing chunk_index. The agent responds after processing each chunk.

pub async fn send_response_headers( &self, correlation_id: &str, event: &ResponseHeadersEvent, ) -> Result<AgentResponse, AgentProtocolError>

Send a response headers event and wait for response.

Called when upstream response headers are received, allowing the agent to inspect/modify response headers before they’re sent to the client.

pub async fn send_response_body_chunk( &self, correlation_id: &str, event: &ResponseBodyChunkEvent, ) -> Result<AgentResponse, AgentProtocolError>

Send a response body chunk event and wait for response.

For streaming response body inspection, chunks are sent sequentially. The agent can inspect and optionally modify response body data.

pub async fn send_event<T: Serialize>( &self, event_type: EventType, event: &T, ) -> Result<AgentResponse, AgentProtocolError>

Send any event type and wait for response.

pub async fn ping(&self) -> Result<Duration, AgentProtocolError>

Send a ping and measure latency.

pub fn protocol_version(&self) -> u32

Get negotiated protocol version.

pub async fn capabilities(&self) -> Option<AgentCapabilities>

Get agent capabilities.

pub async fn is_connected(&self) -> bool

Check if client is connected.

pub async fn close(&self) -> Result<(), AgentProtocolError>

Close the connection.

pub async fn cancel_request( &self, correlation_id: &str, reason: CancelReason, ) -> Result<(), AgentProtocolError>

Cancel an in-flight request.

Sends a cancellation message to the agent and removes the request from the pending map. The agent should stop processing and clean up resources.

pub async fn cancel_all( &self, reason: CancelReason, ) -> Result<usize, AgentProtocolError>

Cancel all in-flight requests.

Used during shutdown or when the upstream connection fails.

pub async fn flow_state(&self) -> FlowState

Get current flow control state.

pub async fn can_accept_requests(&self) -> bool

Check if the agent is accepting new requests.

Returns false if the agent has requested a pause or is draining.

pub async fn wait_for_flow_control( &self, timeout: Duration, ) -> Result<(), AgentProtocolError>

Wait for flow control to allow new requests.

If the agent has requested a pause, this will wait until it resumes or the timeout expires.

pub async fn health_state(&self) -> i32

Get current health state.

Returns the numeric health state:

• 1: Healthy
• 2: Degraded
• 3: Draining
• 4: Unhealthy

pub async fn is_healthy(&self) -> bool

Check if the agent is healthy.

pub fn in_flight_count(&self) -> u64

Get the number of in-flight requests.

pub async fn send_configure( &self, config: Value, version: Option<String>, ) -> Result<(), AgentProtocolError>

Send a configuration update to the agent.

pub async fn send_shutdown( &self, reason: ShutdownReason, grace_period_ms: u64, ) -> Result<(), AgentProtocolError>

Request the agent to shut down.

pub async fn send_drain( &self, duration_ms: u64, reason: DrainReason, ) -> Result<(), AgentProtocolError>

Request the agent to drain (stop accepting new requests).

pub fn agent_id(&self) -> &str

Get agent identifier.