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;
# async
Applications that do not have a MicroClaw YAML file can configure the provider directly:
use ;
# async
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
MicroClawruntime and reuse it across Agents. - Use an Agent profile for stable identity, prompt, Skills, and tool policy.
- Treat each
RunHandleas one execution with ordered events, controls, and one authoritative terminalRunResult. - Branch on
RuntimeErrorCoderather than parsing error messages. - Preserve event sequence numbers when projecting runs into a UI or protocol.
- Call
Runtime::shutdown().awaitto 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.