Crate sacp 

sacp – the Symposium Agent Client Protocol (ACP) SDK

sacp is a Rust SDK for building Agent-Client Protocol (ACP) applications. ACP is a protocol for communication between AI agents and their clients (IDEs, CLIs, etc.), enabling features like tool use, permission requests, and streaming responses.

What can you build with sacp?

• Clients that talk to ACP agents (like building your own Claude Code interface)
• Proxies that add capabilities to existing agents (like adding custom tools via MCP)
• Agents that respond to prompts with AI-powered responses

Quick Start: Connecting to an Agent

The most common use case is connecting to an existing ACP agent as a client. Here’s a minimal example that initializes a connection, creates a session, and sends a prompt:

use sacp::ClientToAgent;
use sacp::schema::{InitializeRequest, ProtocolVersion};

ClientToAgent::builder()
    .name("my-client")
    .run_until(transport, async |cx| {
        // Step 1: Initialize the connection
        cx.send_request(InitializeRequest::new(ProtocolVersion::LATEST))
            .block_task().await?;

        // Step 2: Create a session and send a prompt
        cx.build_session_cwd()?
            .block_task()
            .run_until(async |mut session| {
                session.send_prompt("What is 2 + 2?")?;
                let response = session.read_to_string().await?;
                println!("{}", response);
                Ok(())
            })
            .await
    })
    .await

For a complete working example, see yolo_one_shot_client.rs.

Cookbook

The sacp_cookbook crate contains practical guides and examples:

• Connecting as a client
• Global MCP server
• Per-session MCP server with workspace context
• Building agents and reusable components
• Running proxies with the conductor

Core Concepts

The concepts module provides detailed explanations of how sacp works, including connections, sessions, callbacks, ordering guarantees, and more.

Related Crates

• sacp-tokio - Tokio utilities for spawning agent processes
• sacp-conductor - Binary for running proxy chains

Re-exports

pub use link::AgentToClient;

pub use link::ClientToAgent;

pub use link::HasDefaultPeer;

pub use link::HasPeer;

pub use link::JrLink;

pub use link::ProxyToConductor;

pub use peer::AgentPeer;

pub use peer::ClientPeer;

pub use peer::ConductorPeer;

pub use peer::JrPeer;

pub use component::Component;

pub use component::DynComponent;

Modules

component

Component abstraction for agents and proxies Component abstraction for agents and proxies.

concepts

Core concepts for understanding and using sacp Core concepts for understanding and using sacp.

cookbook

Cookbook of common patterns for building ACP components Cookbook of common patterns for building ACP components.

handler

JSON-RPC handler types for building custom message handlers Handler types for building custom JSON-RPC message handlers.

jsonrpcmsg

JSON-RPC message types.

link

Link types for JSON-RPC connections Link types for ACP and related protocols.

mcp

MCP declarations (minimal)

mcp_server

MCP server support for providing MCP tools over ACP MCP server support for providing MCP tools over ACP.

peer

Peer types for JSON-RPC connections Peer types for ACP and related protocols.

schema

ACP protocol schema types - all message types, requests, responses, and supporting types ACP protocol schema types and message implementations.

util

Utility functions and types

Macros

on_receive_message

This macro is used for the value of the to_future_hack parameter of JrConnectionBuilder::on_receive_message and JrConnectionBuilder::on_receive_message_from.

on_receive_notification

This macro is used for the value of the to_future_hack parameter of JrConnectionBuilder::on_receive_notification and JrConnectionBuilder::on_receive_notification_from.

on_receive_request

This macro is used for the value of the to_future_hack parameter of JrConnectionBuilder::on_receive_request and JrConnectionBuilder::on_receive_request_from.

tool_fn

This is a hack that must be given as the final argument of McpServerBuilder::tool_fn when defining stateless concurrent tools. See tool_fn_mut! for the gory details.

tool_fn_mut

This is a hack that must be given as the final argument of McpServerBuilder::tool_fn when defining tools. Look away, lest ye be blinded by its vileness!

Structs

ActiveSession

Active session struct that lets you send prompts and receive updates.

Blocking

Marker type indicating the session builder will block the current task.

ByteStreams

A component that communicates over byte streams (stdin/stdout, sockets, pipes, etc.).

ChainResponder

Chains two responders to run in parallel.

Channel

A channel endpoint representing one side of a bidirectional message channel.

Error

JSON-RPC error object.

JrConnection

A JSON-RPC connection with an active transport.

JrConnectionBuilder

A JSON-RPC connection that can act as either a server, client, or both.

JrConnectionCx

Trait for types that can provide transport for JSON-RPC messages.

JrRequestCx

The context to respond to an incoming request.

JrResponse

Represents a pending response of type R from an outgoing request.

Lines

A component that communicates over line streams.

McpAcpTransport

The mcp_acp_transport capability - indicates support for MCP-over-ACP bridging.

NonBlocking

Marker type indicating the session builder will not block the current task.

NullHandler

Null handler that accepts no messages.

NullResponder

A no-op responder that completes immediately.

SessionBuilder

Session builder for a new session request. Allows you to add MCP servers or set other details for this session.

UntypedMessage

An incoming JSON message without any typing. Can be a request or a notification.

Enums

AgentNotification

All possible notifications that an agent can send to a client.

AgentRequest

All possible requests that an agent can send to a client.

AgentResponse

All possible responses that an agent can send to a client.

ClientNotification

All possible notifications that a client can send to an agent.

ClientRequest

All possible requests that a client can send to an agent.

ClientResponse

All possible responses that a client can send to an agent.

ErrorCode

Predefined error codes for common JSON-RPC and ACP-specific errors.

Handled

Return type from JrHandler; indicates whether the request was handled or not.

MessageCx

An enum capturing an in-flight request or notification. In the case of a request, also includes the context used to respond to the request.

SessionMessage

Incoming message from the agent

Traits

IntoHandled

Trait for converting handler return values into Handled.

JrMessage

Common bounds for any JSON-RPC message.

JrMessageHandler

Handlers process incoming JSON-RPC messages on a JrConnection.

JrNotification

A struct that represents a notification (JSON-RPC message that does not expect a response).

JrRequest

A struct that represents a request (JSON-RPC message expecting a response).

JrResponder

A responder runs background tasks alongside a connection.

JrResponsePayload

Defines the “payload” of a successful response to a JSON-RPC request.

MetaCapability

Trait for capabilities stored in the _meta.symposium object.

MetaCapabilityExt

Extension trait for checking and modifying capabilities in InitializeRequest.

SessionBlockState

Trait for marker types that indicate blocking vs blocking API. See SessionBuilder::block_task.

Type Aliases

BoxFuture

An owned dynamically typed Future for use in cases where you can’t statically type your result or need to add some indirection.

Derive Macros

JrNotification

Derive macro for implementing JrNotification and JrMessage traits.

JrRequest

Derive macro for implementing JrRequest and JrMessage traits.

JrResponsePayload

Derive macro for implementing JrResponsePayload trait.