1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
//! The roles in ACP: clients, agents, proxies, and conductors.
//!
//! The Agent-Client Protocol defines how AI agents communicate with the
//! applications that use them. Understanding the four roles helps you choose
//! the right approach for what you're building.
//!
//! # Clients
//!
//! A **client** is an application that wants to use an AI agent. Examples include:
//!
//! - IDEs like VS Code or JetBrains
//! - Command-line tools
//! - Web applications
//! - Automation scripts
//!
//! Clients send prompts to agents and receive responses. They can also handle
//! requests from the agent (like permission requests or tool approvals).
//!
//! # Agents
//!
//! An **agent** is an AI-powered service that responds to prompts. Examples include:
//!
//! - Claude Code
//! - Custom agents built with language models
//!
//! Agents receive prompts, process them (typically by calling an LLM), and stream
//! back responses. They may also request permissions, invoke tools, or ask for
//! user input during processing.
//!
//! # Proxies
//!
//! A **proxy** sits between a client and an agent, intercepting and potentially
//! modifying messages in both directions. Proxies are useful for:
//!
//! - Adding tools via MCP (Model Context Protocol) servers
//! - Injecting system prompts or context
//! - Logging and debugging
//! - Filtering or transforming messages
//!
//! Proxies can be chained - you can have multiple proxies between a client and
//! an agent, each adding its own capabilities.
//!
//! # Conductors
//!
//! A **conductor** orchestrates a chain of proxies with a final agent. It:
//!
//! - Spawns and manages proxy processes
//! - Routes messages through the chain
//! - Handles initialization and shutdown
//!
//! The [`agent-client-protocol-conductor`] crate provides a conductor implementation. Most users
//! don't need to implement conductors themselves - they just configure which
//! proxies to use.
//!
//! # Message Flow
//!
//! Messages flow through the system like this:
//!
//! ```text
//! Client <-> Proxy 1 <-> Proxy 2 <-> ... <-> Agent
//! ^ ^
//! | |
//! +------ Conductor manages -------+
//! ```
//!
//! Each arrow represents a bidirectional connection. Requests flow toward the
//! agent, responses flow back toward the client, and notifications can flow
//! in either direction.
//!
//! # Next Steps
//!
//! Now that you understand the roles, see [Connections and Links](super::connections)
//! to learn how to establish connections in code.
//!
//! [`agent-client-protocol-conductor`]: https://crates.io/crates/agent-client-protocol-conductor