Cookbook of common patterns for building ACP components.

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

• 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 agent_client_protocol::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 Client.builder() to build connections.

• [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 Proxy.builder() to build proxy connections.

Important: Proxies don't run standalone—they need the agent-client-protocol-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 ConnectTo for composition
• [running_proxies_with_conductor] - Run your proxy with an agent

Building Agents

An agent receives prompts and generates responses. Use Agent.builder() to build agent connections.

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