Skip to content

Rust SDK ​

rho-sdk is Rho's embeddable, headless Rust agent runtime. It provides provider-neutral messages, sessions, completion and streaming runs, custom provider and tool extension points, cancellation, retractable steering, host input, compaction, workspace policy, approvals, lifecycle hooks, provider-free tool hosts, usage recording, diagnostics, and versioned snapshots.

The crate is published on crates.io. These pages document the current public API and compatibility policy. For release-to-release changes, use the SDK changelog.

Start here ​

  1. Read installation and support for dependency, runtime, platform, feature, and Rust-version status.
  2. Read concepts to understand runtime, session, run, tool-host, and host ownership.
  3. Choose or implement a provider.
  4. Register only the tools and capabilities the host intends to grant.
  5. Optionally wire hooks for observation and pre-tool denial.
  6. Consume events and cancellation and persist session snapshots as needed.
  7. Review the security model and threat model before enabling sensitive operations.

Current capability map ​

CapabilityCurrent SDK contract
Final answerSession::complete returns a typed RunOutcome
StreamingSession::start returns a bounded, ordered RunEvent stream; always take Run::outcome as authoritative
ProvidersPublic ModelProvider trait and deterministic ScriptedProvider
ToolsPublic Tool trait, registry, prepare/resource-aware parallel execution, progress, host input, scoped authorization
Tool hostProvider-free ToolHost for the same registry, approvals, and hooks without a model loop
SessionsOne mutable run at a time, explicit history inspection, reset, provider replacement, reasoning changes
SteeringRun::steer and retractable Run::steer_retractable / Run::retract_steering
CancellationShared cooperative token, run cancellation handle, runtime shutdown, and safe run-drop fallback
CompactionHost-supplied Compactor, optional automatic policy, explicit manual compaction
Hookshooks module: observer, pre-tool gate, bounded envelopes, host labels
Decisionsdecision module: typed noul, choice, and score questions; DecisionModel trait; text-model adapter. See decisions
UsageOptional ProviderRequestUsageRecorder for physical request accounting
PersistenceVersioned JSON SessionSnapshot and InMemorySessionStore, with no SQLite requirement
SecurityNo sensitive capability by default; workspace, policy, approval handler, provider, and tools are host supplied
DiagnosticsSecret-free-by-contract configuration snapshot, subject to adapter redaction obligations

Examples ​

The repository contains compiling examples for:

Run one from a repository checkout:

bash
cargo run -p rho-sdk --example simple_completion

The crate README mirrors these examples and covers ToolHost, retractable steering, and hook labels.

Historical material ​

These pages record the 1.0 cutover. Prefer the guide and changelog for current behavior.