Trait Protocol

Source

pub trait Protocol:
    Sealed
    + Copy
    + Debug
    + Default
    + Send
    + Sync
    + 'static {
    type RequestId: Clone + Debug + Display + Eq + Hash + Serialize + Into<RawJsonRpcId> + Send + Sync + 'static;
    type Connection<Counterpart: Role>: Clone + Send + Sync + Into<ConnectionTo<Counterpart>> + 'static;
}

Expand description

The protocol version of a request handle or builder, as a type.

The request handles (Responder, ResponseRouter, SentRequest, PreparedRequest and Dispatch) and the connection Builder take a protocol marker as their last type parameter. It selects the request ID type their id() returns and the connection type builder callbacks receive:

Marker	`RequestId`	`Connection<Counterpart>`
`Raw` (the default)	`RawJsonRpcId`	`ConnectionTo`
`V1`	`v1::schema::RequestId`	`v1::ConnectionTo`
`V2` (`unstable_protocol_v2`)	`v2::schema::RequestId`	`v2::ConnectionTo`

Typed handlers on Client.v1(), Agent.v1() and Proxy.v1(), and requests sent through v1::ConnectionTo, use V1.
Typed handlers on Client.v2(), Agent.v2() and Proxy.v2(), and requests sent through v2::ConnectionTo, use V2.
Everything that is not tied to one version uses Raw: the HandleDispatchFrom layer, MatchDispatch, builders whose version guard is disabled, and requests sent through ConnectionTo.

The v1 and v2 modules name the typed handles: v1::Responder<T> is Responder<T, V1>, v2::SentRequest<T> is SentRequest<T, V2>, v1::Builder<Host> is Builder<Host, .., V1>, and so on.

Every handle also has raw_id(), which returns the wire ID as a RawJsonRpcId whatever the marker. A Raw handle converts to a typed one with into_protocol, and any handle converts back with into_raw.

use agent_client_protocol::{RawJsonRpcId, Responder, V1, v1::schema};

fn log_request(responder: &Responder<schema::PromptResponse, V1>) {
    let id: &schema::RequestId = responder.id();
    let wire_id: &RawJsonRpcId = responder.raw_id();
    assert_eq!(RawJsonRpcId::from(id.clone()), *wire_id);
}

fn log_raw_request(responder: &Responder<schema::PromptResponse>) {
    // `Responder<T>` is `Responder<T, Raw>`.
    let id: &RawJsonRpcId = responder.id();
}

Generic code can accept handles of any version:

use agent_client_protocol::{Protocol, Responder, v1::schema};

fn reject<P: Protocol>(responder: Responder<schema::PromptResponse, P>) -> agent_client_protocol::Result<()> {
    responder.respond_with_error(agent_client_protocol::Error::invalid_params())
}

This trait is sealed: the SDK defines one marker per supported protocol version, plus Raw.

Required Associated Types§

Source

type RequestId: Clone + Debug + Display + Eq + Hash + Serialize + Into<RawJsonRpcId> + Send + Sync + 'static

The request ID type of this protocol version.

Source

type Connection<Counterpart: Role>: Clone + Send + Sync + Into<ConnectionTo<Counterpart>> + 'static

The connection type that builder callbacks receive for Counterpart.

Every connection type converts back to the version-neutral ConnectionTo with Into, so code generic over P can reach the raw connection:

use agent_client_protocol::{Agent, ConnectionTo, Protocol};

fn raw<P: Protocol>(connection: P::Connection<Agent>) -> ConnectionTo<Agent> {
    connection.into()
}