Struct Agent

Source

pub struct Agent;

Expand description

The agent role - typically an LLM that responds to prompts.

Agents receive prompts from clients and respond with answers, potentially invoking tools along the way.

Implementations§

Source §

impl Agent

Source

pub fn v1(self) -> Builder<Agent>

Create an agent builder that uses the ACP protocol v1 API.

Callbacks receive a v1::ConnectionTo and typed handlers receive v1 request handles. With the unstable_protocol_v2 feature, use Agent::v2 for a protocol v2 agent, or Agent::protocol_router to serve both.

Source

pub fn v2(self) -> Builder<Agent>

Available on crate feature unstable_protocol_v2 only.

Create an agent builder that uses the ACP protocol v2 API.

This builder selects protocol v2 for clients requesting v2 or a newer version. A request for exactly v2 must be a valid v2 initialize request. A request for a newer version is accepted with what parses under v2: unparsable capabilities and _meta are dropped, and a missing or malformed info is replaced by an implementation named unknown with version unknown. Use Self::protocol_router with a v1 implementation for v1 clients.

The client may repeat initialize after the previous one completed and before it sends any other request. Each repeat is negotiated like the first one and dispatched to the initialize handler, and the latest successful one is authoritative. A repeat requesting a version below v2 gets -32022 (Unsupported protocol version), as a first request would. A repeat after any other request or while an initialize is in flight is rejected with -32600. A repeat that fails keeps the previous initialization in place. Requests with a null id are rejected with -32600.

An initialized agent without a handler for tool_call/cancel or terminal/cancel answers them with -32602 (Invalid params), not -32601 (Method not found): the spec answers a request for an unknown or non-cancellable tool call or terminal with -32602, and an agent that handles neither method cancels nothing. A typed handler or a catch-all handler for these requests takes precedence.

Requires the unstable_protocol_v2 crate feature.

Source

pub fn protocol_router(self) -> AgentProtocolRouter

Available on crate feature unstable_protocol_v2 only.

Create a router that chooses between configured protocol implementations.

Add implementations with AgentProtocolRouter::with_v1 and AgentProtocolRouter::with_v2. The resulting router reads the initial initialize request and selects a version-specific implementation. A request for v2 or newer selects the v2 implementation. With a v1 implementation configured, everything else, including a request below v1 and a missing or malformed first request, is handed unchanged to the v1 implementation, so a v1 client sees exactly the behavior of the v1 implementation alone (including v1’s fallback-to-latest rule). A v2-only router rejects a request below v2 with -32022. The router does not convert traffic after initialization.

The selected implementation owns the connection. A repeated initialize is forwarded to it and is never re-routed, so it is negotiated like a first request against the selected version alone. A v2 implementation answers a repeat requesting v1 with -32022 listing only v2, since the connection cannot switch to the v1 API, and the v2 initialization stays in effect. A v1 implementation selects v1 for a repeat requesting a newer version. A first initialize with a null id that would select v2 is rejected with -32600, like any other invalid first request.

A rejected first message, including a version mismatch (-32022), leaves the connection uninitialized and open: the client may send initialize again, for example after correcting its parameters. Notifications before initialization are ignored.

Requires the unstable_protocol_v2 crate feature while protocol v2 stabilizes.