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)
• [v2_one_shot_prompt] - Send a draft-v2 prompt and wait for the independent idle update
• [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() for stable protocol v1 proxy connections. With the core SDK's unstable_protocol_v2 feature, use Proxy.v2() for a draft-v2-only proxy, or Proxy.protocol_router() to expose separate strict v1 and v2 implementations as one component.

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