OpenWorker Harness SDK for Rust
Embed an agent runtime in your Rust application, with model connections, tools, approvals and durable conversations. Use the same engine through a managed child process when your product needs that process boundary.
SDK overview · Desktop guide · Tools · Examples
Add the SDK
Use a pinned OpenWorker checkout and add the crate to your application's
Cargo.toml. These instructions use source dependencies; npm publication does
not publish a Rust crate. Use the checkout's pinned Rust toolchain.
[dependencies]
openworker-sdk = { path = "/absolute/path/to/openworker/harness/harness-sdk" }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
anyhow = "1"
A tool-free agent running in-process with Sandbox::Off can start without a
separate helper. Managed processes and profiles with bound tools still need the
matching helper. Build it from the same checkout when adding those capabilities:
cargo +1.96.0 build --manifest-path /absolute/path/to/openworker/harness/Cargo.toml \
--locked -p openworker-sdk --bin openworker-harness
Pass its absolute path with .executable(path) (openworker-harness.exe on
Windows), or set OPENWORKER_EXECUTABLE. Existing bundled-helper discovery is
preserved. A harness started without a helper rejects later registration of a
profile with bound tools; restart with the matching helper to add them. Keep the
same execution configuration when resuming existing sessions.
Run your first agent
Save as src/main.rs. Set OPENAI_API_KEY privately in the process environment
and OPENWORKER_MODEL to an exact model ID available to your account. Cargo does
not load env files automatically.
use openworker_sdk::{Agent, Credentials, Harness, Model, ModelProvider, Sandbox};
use openworker_sdk::agents::RunStatus;
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let model = std::env::var("OPENWORKER_MODEL")?;
let harness = Harness::builder()
.state_dir(std::env::current_dir()?.join(".openworker-state"))
.sandbox(Sandbox::Off)
.start().await?;
let outcome = async {
harness.set_model_provider(ModelProvider::responses("OpenAI")
.base_url(std::env::var("OPENWORKER_MODEL_URL")
.unwrap_or_else(|_| "https://api.openai.com/v1".into()))
.credentials(Credentials::from_env("OPENAI_API_KEY").memory_only()))
.await?;
let agent = harness.create_agent(Agent::new("first-agent-v1")
.instructions("Give concise, helpful answers.")
.default_model(Model::new("OpenAI", model))
.tools([] as [&str; 0]).planning(false).memory(false).scheduling(false))
.await?;
let session = agent.new_session().await?;
let result = session.run("Suggest three names for a file-organizing app.").await?;
anyhow::ensure!(matches!(result.status, RunStatus::Completed),
"Run ended: {:?}", result.status);
println!("{}", result.final_output.unwrap_or_default());
Ok::<(), anyhow::Error>(())
}.await;
harness.shutdown().await?;
outcome
}
cargo +1.96.0 run
OPENWORKER_MODEL_URL optionally selects another Responses-compatible endpoint.
Rust embeds the harness by default. This text-only example exposes no tools and
explicitly selects Sandbox::Off. App callbacks keep the application's privileges.
For isolated shell/file execution, configure OpenShell.
Use HarnessClient::managed_stdio or the custom host interfaces only when you
need an explicit process boundary; see the native host guide.
Add the next capability
| You want to… | Start here |
|---|---|
| Register native or app-owned tools | Tools and MCP · Tools SDK |
| Handle streaming, approvals and cancellation | Streaming · Sessions |
| Use local models or rotate credentials | Models and credentials |
| Add teams, memory or scheduling | Sessions and teams |
| Add guardrails or inspect traces | Guardrails · Observability |
| Deploy a service | Deployment options |
Integration contract
- Define agents once and create a session per conversation. Persist its reference
and call
agent.resume_session(reference)after restart. - Definitions persist and are immutable. Use a new agent name when changing its instructions, tools or approvals; identical registration is idempotent.
- Credentials resolve in the Rust application process.
memory_only()requires supplying them again after app restart. Keep keys out of instructions and files available to agent tools. - A workspace selects the working directory and supported path-policy scope. Arbitrary callbacks retain application privileges; it is not an OS sandbox.
- Treat interruptions as requests for a real app/user decision. Dropping an event
stream does not cancel execution; call
session.cancel()explicitly. - Reconcile unknown tool outcomes before retrying, and keep state outside tool-readable directories.
Generate full API documentation from the checkout with
cargo doc --manifest-path harness/Cargo.toml -p openworker-sdk --no-deps.
See versions and
troubleshooting before upgrading an app.