Crate agentproc 

agentproc

Rust SDK for the AgentProc protocol — connect any agent CLI to a messaging platform via a process-based interface.

The SDK is the Rust sibling of the Python and Node SDKs, implementing the same wire protocol (0.4) and the same in-process executor mechanism (profile executor: field). One profile can run three ways depending on what the host has installed: Rust executor (in-process), Node executor (in-process), or a Python bridge script (spawn) — all producing the same observable NDJSON.

Quick start

use agentproc::{run, Profile, RunOptions};

let profile = Profile::from_path("profile.yaml")?;
let result = run(&profile, RunOptions::new("hello")).await?;
println!("{}", result.reply);

See spec/protocol.md in the agentproc repository for the protocol specification, including the in-process executor contract.

Re-exports

pub use executors::executor_names;

pub use executors::Executor;

pub use executors::ParseResult;

pub use executors::TurnHandlers;

pub use executors::UnknownExecutor;

Modules

executors

In-process executor registry and built-in executors.

history

Session history persistence.

Structs

Attachment

One element of the turn object’s attachments array.

PermissionRequest

A tool-permission request emitted by the agent (only when permission: true).

PermissionResponse

A permission response the bridge writes to the agent’s stdin as one NDJSON line (only when permission: true).

Profile

Normalised profile — the result of parsing a YAML file or building one programmatically. Field names mirror the wire-level profile schema in spec/protocol.md.

ProtocolError

Raised by an agent when it wants to signal a protocol-level error to the bridge (emitted as {"type":"error"} on stdout). Mirrors ProtocolError in the Python / Node SDKs.

RunOptions

Callbacks and inputs for a single run call.

RunResult

The outcome of a run.

SubstCtx

Placeholder context.

TurnInput

The turn object as read by an agent from its stdin (deserialized).

TurnObject

The turn object the bridge writes to the agent’s stdin as a single NDJSON line before the process reads its first byte.

Enums

AgentEvent

A parsed stdout event from the agent.

PartialRole

Distinguish assistant output from reasoning/thinking text on partial events.

PermissionBehavior

PermissionDecision

The decision returned by on_permission: allow (optionally with an updated tool input) or deny (with a reason).

PlaceholderError

Error returned by substitute when a placeholder value contains bytes that would be unsafe in a shell-style wrapper.

RunnerError

Runner / profile / executor errors. All SDK fallible APIs return this.

Constants

PROTOCOL_VERSION

Wire-protocol version string carried in the turn object. Opaque and non-comparable per the spec — agents MUST NOT order or range-check it.

Functions

build_base_env

Build the base child environment: infra set copied from parent.

expand_env_ref

Expand ${VAR} references in value against env. Unknown variables expand to the empty string (POSIX-shell semantics).

expand_env_ref_with_allowlist

Expand ${VAR} with an optional allowlist. When allowlist is Some, references to names not in the list expand to empty and on_blocked is called with a warning message.

parse_event

Parse one stdout line into a typed AgentEvent.

protocol_error

Construct a ProtocolError — convenience for agent handlers.

read_turn

Read exactly one NDJSON line (the turn object) from any reader.

run

Run a profile for one turn. Resolves the four-case executor rule:

substitute

Substitute {{PLACEHOLDER}} tokens in a string. Supported tokens: {{MESSAGE}}, {{SESSION_ID}}, {{SESSION_NAME}}, {{PROFILE_DIR}}.

Type Aliases

PermissionFuture

Alias for an async permission decision callback’s return type.