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
- Read installation and support for dependency, runtime, platform, feature, and Rust-version status.
- Read concepts to understand runtime, session, run, tool-host, and host ownership.
- Choose or implement a provider.
- Register only the tools and capabilities the host intends to grant.
- Optionally wire hooks for observation and pre-tool denial.
- Consume events and cancellation and persist session snapshots as needed.
- Review the security model and threat model before enabling sensitive operations.
Current capability map
| Capability | Current SDK contract |
|---|---|
| Final answer | Session::complete returns a typed RunOutcome |
| Streaming | Session::start returns a bounded, ordered RunEvent stream; always take Run::outcome as authoritative |
| Providers | Public ModelProvider trait and deterministic ScriptedProvider |
| Tools | Public Tool trait, registry, prepare/resource-aware parallel execution, progress, host input, scoped authorization |
| Tool host | Provider-free ToolHost for the same registry, approvals, and hooks without a model loop |
| Sessions | One mutable run at a time, explicit history inspection, reset, provider replacement, reasoning changes |
| Steering | Run::steer and retractable Run::steer_retractable / Run::retract_steering |
| Cancellation | Shared cooperative token, run cancellation handle, runtime shutdown, and safe run-drop fallback |
| Compaction | Host-supplied Compactor, optional automatic policy, explicit manual compaction |
| Hooks | hooks module: observer, pre-tool gate, bounded envelopes, host labels |
| Usage | Optional ProviderRequestUsageRecorder for physical request accounting |
| Persistence | Versioned JSON SessionSnapshot and InMemorySessionStore, with no SQLite requirement |
| Security | No sensitive capability by default; workspace, policy, approval handler, provider, and tools are host supplied |
| Diagnostics | Secret-free-by-contract configuration snapshot, subject to adapter redaction obligations |
Examples
The repository contains compiling examples for:
- simple completion
- streaming
- custom providers
- custom tools
- cancellation
- image history
- snapshots
- questionnaires and approvals
Run one from a repository checkout:
cargo run -p rho-sdk --example simple_completionThe 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.