Struct AcpAgent 

pub struct AcpAgent { /* private fields */ }

Available on crate feature process and non-target_family=wasm only.

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.

Shutdown

When the protocol connection finishes cleanly (a connect_with foreground returns, or the agent closes its stdout), AcpAgent drains pending output, closes the agent’s stdin, and waits briefly (one second) for the agent to exit on its own, as the ACP stdio transport specifies. A nonzero exit observed during that wait is reported as an error. If the agent is still running afterwards, it is terminated:

• On Unix, the spawned process group (which includes agents started through wrapper commands such as npx and uvx) is sent SIGTERM, then SIGKILL if it has not exited within two more seconds. Because the SDK requested this termination, the resulting exit status is not reported as an error.
• On Windows, the process is killed.

Dropping an active connection (cancellation) cannot wait, so it kills the process immediately; on Unix it sends SIGKILL to the whole process group.

Nonzero process exits include a bounded stderr tail in the returned error. Collection waits only for a bounded shutdown period; if stderr EOF does not arrive, bytes already captured are still reported.

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 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);
    });

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

fn into_channel_and_future(self) -> (Channel, Option<ConnectionDriver>)

Spawns the agent and returns a driver that supports graceful finish.

A finite foreground (Builder::connect_with) requests finish after handing off its output. The line transport then drains and closes the agent’s stdin, and the driver waits for the agent to exit, escalating as described in AcpAgent’s shutdown documentation, instead of being dropped (which would kill the agent without closing stdin first).

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

Connect this component to another component.

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.