Struct AcpAgent 

pub struct AcpAgent { /* private fields */ }

A component representing an external ACP agent running in a separate process.

AcpAgent implements the ConnectTo trait for spawning and communicating with external agents or proxies via stdio. It handles process spawning, stream setup, and byte stream serialization automatically. This is the primary way to connect to agents that run as separate executables.

The launch configuration is independent from ACP wire-schema types and can be parsed from command-line strings or JSON configurations. On Unix, dropping an active connection terminates the spawned process group, including agents started through wrapper commands such as npx and uvx.

Use Cases

• External agents: Connect to agents written in any language (Python, Node.js, Rust, etc.)
• Proxy chains: Spawn intermediate proxies that transform or intercept messages
• Conductor components: Use with the conductor to build proxy chains
• Subprocess isolation: Run potentially untrusted code in a separate process

Examples

Parse from a command string:

let agent = AcpAgent::from_str("python my_agent.py --verbose").unwrap();

Parse from JSON:

let agent = AcpAgent::from_str(r#"{"command": "python", "args": ["my_agent.py"], "env": {"RUST_LOG": "info"}}"#).unwrap();

Implementations

impl AcpAgent

pub fn new(config: AcpAgentConfig) -> Self

Create an ACP agent from its process-launch configuration.

pub fn claude_agent() -> Self

Create an ACP agent for the Claude Agent adapter. Just runs npx -y @agentclientprotocol/claude-agent-acp@latest.

pub fn codex() -> Self

Create an ACP agent for the Codex adapter. Just runs npx -y @agentclientprotocol/codex-acp@latest.

pub fn config(&self) -> &AcpAgentConfig

Get the process-launch configuration.

pub fn into_config(self) -> AcpAgentConfig

Convert into the process-launch configuration.

pub fn with_debug<F>(self, callback: F) -> Self

where F: Fn(&str, LineDirection) + Send + Sync + 'static,

Add a debug callback that will be invoked for each line sent/received.

The callback receives the line content and the direction (stdin/stdout/stderr). This is useful for logging, debugging, or monitoring agent communication. Exceptionally long stderr lines are truncated to keep memory usage bounded.

Example

let agent = AcpAgent::from_str("python my_agent.py")
    .unwrap()
    .with_debug(|line, direction| {
        eprintln!("{:?}: {}", direction, line);
    });

pub fn spawn_process( &self, ) -> Result<(ChildStdin, ChildStdout, ChildStderr, Child), Error>

Spawn the configured process and return its stdio streams and raw child handle.

This is a low-level escape hatch. The caller owns the returned child process and is responsible for terminating it. Connections created through crate::ConnectTo instead install a guard that tears down the spawned process group on Unix.

impl AcpAgent

pub fn from_args<I, T>(args: I) -> Result<Self, Error>

where I: IntoIterator<Item = T>, T: ToString,

Create an AcpAgent from an iterator of command-line arguments.

Leading arguments of the form NAME=value are parsed as environment variables. The first non-env argument is the command, and the rest are arguments.

Example

let agent = AcpAgent::from_args([
    "RUST_LOG=debug",
    "cargo",
    "run",
    "-p",
    "my-crate",
]).unwrap();

Trait Implementations

impl<Counterpart: AcpAgentCounterpartRole> ConnectTo<Counterpart> for AcpAgent

async fn connect_to( self, client: impl ConnectTo<Counterpart::Counterpart>, ) -> Result<(), Error>

Connect this component to another component.

fn into_channel_and_future(self) -> (Channel, BoxFuture<'static, Result<()>>)

where Self: Sized,

Convert this component into a channel endpoint and connection future.

impl Debug for AcpAgent

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromStr for AcpAgent

type Err = Error

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.