Skip to main content
The Rust SDK embeds Meerkat’s runtime directly in your application. Choose providers, tools and storage through feature flags and typed interfaces, from a small agent to a host with persistent sessions and runtime services. The CLI, other SDKs and service APIs use the same engine. A production Rust host composes PersistentSessionService with MeerkatMachine; the service is the session substrate and the machine owns runtime transitions. The direct EphemeralSessionService path remains useful for small embedded programs and tests that intentionally do not need runtime-backed persistence or delivery.

Method overview

Mob orchestration is layered on this facade by the separate meerkat-mob crate. The live feature composes meerkat-live into the runtime; direct adapter types remain owned by meerkat-live.

Installation

1

Add the dependency

2

Choose feature flags

The default feature set enables the Anthropic, OpenAI, and Gemini clients plus GitHub Copilot OAuth/backend support; add optional gates as needed:
Meerkat’s stores run on the SQLite that libsqlite3-sys bundles, whose defaults put every connection in the process behind process-wide locks. Build your application with LIBSQLITE3_FLAGS="-DSQLITE_DEFAULT_MEMSTATUS=0 -USQLITE_ENABLE_MEMORY_MANAGEMENT -DSQLITE_DISABLE_PAGECACHE_OVERFLOW_STATS" (for example in the [env] table of your workspace’s .cargo/config.toml), and call meerkat_sqlite::disable_memory_statistics_at_process_start() from the meerkat-sqlite crate as the first statement of main. See SQLite Lock Profile.

Quick start

Production surfaces (CLI, REST, RPC, MCP) use the runtime-backed path where PersistentSessionService is substrate and MeerkatMachine owns keep-alive, Queue/Steer routing, interruption, terminal publication, and archive. Start a native host with both halves: Use this dependency set for the persistent example. The explicit meerkat-store dependency supplies RealmBackend and realm_paths_in; transitive dependencies are not available as direct crate imports.
build_persistent_service() returns only the persistent service half. Its direct start_turn, interrupt, and archive methods intentionally return SessionError::Unsupported; a runtime-backed host must use the machine commit, interrupt, and retire protocols. Use the public helpers in meerkat::surface when building a native host, or use the ready-made RPC, REST, CLI, or MCP host.
For a direct embedded or testing flow that does not need machine-owned runtime semantics, use the ephemeral service: Before running the model turn below, make credentials available for its Claude model through a compatible configured auth binding or an Anthropic environment key. For a clean API-key setup:
A compatible existing binding can be used instead; another provider’s key does not authenticate this Claude request. Merely constructing the persistent host above does not make a model call or require this credential step.

Sessions

The examples below use the direct EphemeralSessionService lifecycle. The same request and result types are used inside production hosts, but persistent follow-up turns, interruption, and archive are machine-owned transitions and must not call these trait methods directly.

Multi-turn conversations

Append a System message at a turn boundary

system_prompt appends one ordinary ordered System message immediately before that turn. It may be used on any turn; prior System messages and the rest of the transcript remain unchanged.

Error handling


Direct agent APIs

Agent::run(...) and AgentBuilder are expert-level escape hatches. Prefer the persistent service plus machine composition for a production host, or the ephemeral session service for a deliberately direct embedded flow.

Running agents directly

Basic run

Run with event streaming

Text deltas are emitted by the model adapter, not by the run. Give one channel to both: build the adapter with build_llm_adapter_with_events and pass the same sender to run_with_events. With an adapter built by build_llm_adapter, which has no channel, the run delivers TextComplete, TurnCompleted and the tool events, and no TextDelta.
The adapter keeps its sender for as long as the agent lives, so the receiving loop ends when the agent is dropped, not when the run returns. Its channel is fixed when it is built: a later run of the same agent that is given another channel sends that channel its turn-level events, and its text deltas still go to the first.
turn_completed carries optional usage for one provider call while run_completed carries the session-cumulative total, and their input_tokens fields use different denominators. usage: None means no accounting exists for that turn, not zero usage. Read Usage accounting before aggregating either.

Agent methods

Error handling

Use this dependency set for the sample. The explicit meerkat-core dependency supplies TurnTerminalCauseKind and TurnTerminalOutcome, which meerkat does not re-export; transitive dependencies are not available as direct crate imports. The meerkat_core imports under Core types need the same dependency.
No run returns Err(AgentError::TokenBudgetExceeded { .. }); it comes from Budget::check() when you call it yourself. A token or tool-call budget spent during a run, or already spent at its start, ends as Ok(RunResult) with terminal_cause_kind == Some(TurnTerminalCauseKind::BudgetExhausted); a spent time budget ends as Err(AgentError::TerminalFailure { outcome: TimeBudgetExceeded, .. }). The answer of the model call that takes a run past its token budget is discarded: it is not committed to the session and not returned, although its tokens are counted. The result’s text is then the latest assistant text the session already held: text from an earlier step of the same run, else the answer of an earlier turn, else empty. Check terminal_cause_kind before using text: on BudgetExhausted the text is not this call’s answer. A streaming caller has by then received the discarded answer’s text deltas; no TextComplete and no TurnCompleted follow them.

Events

Reconcile BoundaryAppendApplied with BoundaryAppendsDiscarded for the same session, run, and input IDs, and with canonical transcript history. The discard payload carries session_id, run_id, and input_ids; the applied event can include canonical notices and the application-time transcript_start offset. A run terminal alone does not prove discard. A discard does not terminalize the input or invalidate its later application in another run; retained canonical history remains authoritative.

Core types

Message and ContentBlock

ContentInput

ContentInput is the prompt type accepted by CreateSessionRequest and StartTurnRequest. It supports both text-only and multimodal prompts:

ToolCall and ToolResult

RunResult


See also

  • Tools and stores - tool system, session stores, MCP integration
  • Advanced - expert-only direct agent construction, providers, budgets, and hooks
  • API reference - quick-lookup type index