Cookbook of common patterns for building ACP components.

This crate contains guides and examples for the three main things you can build with sacp:

• Clients - Connect to an existing agent and send prompts
• Proxies - Sit between client and agent to add capabilities (like MCP tools)
• Agents - Respond to prompts with AI-powered responses

See the sacp::concepts module for detailed explanations of the concepts behind the API.

Building Clients

A client connects to an agent, sends requests, and handles responses. Use ClientToAgent as your link type.

• [one_shot_prompt] - Send a single prompt and get a response (simplest pattern)
• [connecting_as_client] - More details on connection setup and permission handling

Building Proxies

A proxy sits between client and agent, intercepting and optionally modifying messages. The most common use case is adding MCP tools. Use ProxyToConductor as your link type.

Important: Proxies don't run standalone—they need the sacp-conductor to orchestrate the connection between client, proxies, and agent. See [running_proxies_with_conductor] for how to put the pieces together.

• [global_mcp_server] - Add tools that work across all sessions
• [per_session_mcp_server] - Add tools with session-specific state
• [filtering_tools] - Enable or disable tools dynamically
• [reusable_components] - Package your proxy as a Component for composition
• [running_proxies_with_conductor] - Run your proxy with an agent

Building Agents

An agent receives prompts and generates responses. Use AgentToClient as your link type.

• [building_an_agent] - Handle initialization, sessions, and prompts
• [reusable_components] - Package your agent as a Component
• [custom_message_handlers] - Fine-grained control over message routing