microclaw-sdk 0.31.0

Official Rust SDK for embedding MicroClaw agents, Skills, and Workers
Documentation

MicroClaw SDK

microclaw-sdk is the supported facade for embedding the MicroClaw run lifecycle in a Rust application. It exposes provider-neutral requests, events, controls, terminal results, Agent handles, and Worker contracts without pulling in Server, channel, Web, or desktop UI code.

The minimal preset is protocol-only, standard adds a host-provided RunExecutor, and full starts the same skilled Agent Engine used by Server and MicroClaw Code without exposing either product package. minimal does not compile the Agent Engine, HTTP clients, SQLite, Tokio, Typst, or OpenTelemetry.

Choose a feature set

Feature Use it when
minimal Your application only needs stable protocol, event, control, and Worker wire contracts
standard (default) Your application wants the Runtime, Agent, Run, control, and Local Worker lifecycle
remote-worker The host or executor communicates over the authenticated WebSocket Worker protocol
full You want the configured MicroClaw Agent Engine, including providers, tools, memory, Skills, MCP, hooks, and Subagents

Most first-time integrations should use full. The workspace minimum supported Rust version is 1.93.

The full preset provides a stable builder and validates selected Skills before a run starts:

use microclaw_sdk::MicroClaw;

# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let microclaw = MicroClaw::builder("microclaw.config.yaml")
    .caller_channel("my-app")
    .max_concurrent_runs(4)
    .build()
    .await?;
let agent = microclaw
    .agent("reviewer")
    .skill("code-review")
    .build()?;
let result = agent.run("Review this repository").result().await?;
println!("{}", result.final_text);
# Ok(())
# }

Applications that do not have a MicroClaw YAML file can configure the provider directly:

use microclaw_sdk::{FullRuntimeConfig, MicroClaw};

# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let config = FullRuntimeConfig::new("openai", "gpt-5", std::env::var("OPENAI_API_KEY")?);
let microclaw = MicroClaw::configure(config).build().await?;
# Ok(())
# }

Use microclaw.skills() to list available and unavailable Skills with diagnostics. A full host can install local, GitHub, or ClawHub Skills, enable or disable them, reload the catalog without a restart, and recoverably remove them with install_skill, set_skill_enabled, reload_skills, and remove_skill. See examples/managed_skills.rs for the complete lifecycle.

Durable work delegated by the Main Agent is available through delegated_tasks; active tasks can be cancelled with cancel_delegated_task. The typed DelegatedTaskStatus is forward-compatible with future Engine states. See examples/delegated_tasks.rs.

For smaller integrations, see examples/minimal_protocol.rs for protocol-only integration, examples/custom_executor.rs for a host executor, and examples/configured_skilled_agent.rs for the full configured Agent Engine.

A practical first integration should build one reusable runtime, run one local Agent, consume ordered events, branch on RuntimeErrorCode, verify cancellation, and shut down cleanly. Add managed Skills and remote Workers only after that baseline works. The SDK quickstart includes a compact acceptance checklist and common-failure guide.

Runtime contract

  • Build one MicroClaw runtime and reuse it across Agents.
  • Use an Agent profile for stable identity, prompt, Skills, and tool policy.
  • Treat each RunHandle as one execution with ordered events, controls, and one authoritative terminal RunResult.
  • Branch on RuntimeErrorCode rather than parsing error messages.
  • Preserve event sequence numbers when projecting runs into a UI or protocol.
  • Call Runtime::shutdown().await to stop accepting work and drain active runs.

Workers

LocalWorker uses the same Agent, Run, event, and control contracts. It exposes active and queued capacity, labels, health, draining, resume, and wait_for_idle() for graceful application shutdown. Worker::submit returns an explicit Unavailable error while draining or unavailable. The serialized WorkerCommand and WorkerFrame types use WORKER_PROTOCOL_VERSION for remote transports. Implement WorkerTransport and WorkerConnection, then call RemoteWorker::connect(...); remote runs return the same RunHandle used by local execution. Use RemoteWorker::connect_with_options(...) to bound reconnect attempts and tune backoff while retaining event replay, acknowledgement, duplicate suppression, and pending-control recovery. The remote-worker feature (included by full) provides WebSocketWorkerTransport and an authenticated WorkerHost for real network execution.

Guides