Crate agent_client_protocol_cookbook 

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

Modules

building_an_agent

Pattern: Building an agent.

connecting_as_client

Pattern: Connecting as a client.

custom_message_handlers

Pattern: Custom message handlers.

filtering_tools

Pattern: Filtering which tools are available.

global_mcp_server

Pattern: Global MCP server in handler chain.

one_shot_prompt

Pattern: You Only Prompt Once.

per_session_mcp_server

Pattern: Per-session MCP server with workspace context.

reusable_components

Pattern: Defining reusable components.

running_proxies_with_conductor

Pattern: Running proxies with the conductor.

v2_one_shot_prompt

Pattern: One prompt with the draft protocol v2 lifecycle.