Tool system
Defining tools
Define tools using JSON Schema:Implementing AgentToolDispatcher
TheAgentToolDispatcher trait connects your tools to the agent:
ToolIdentityRegistry (dynamic registration)
ToolIdentityRegistry (dynamic registration)
For dynamic tool registration:
Calls dispatched again after a restart
Since 0.9.5 a run in a durable session continues after a crash from its last committed round, and the calls of a round whose results were not committed are dispatched again under the same call ids (see Durable runs). Delivery is at least once. A tool whose effect must not happen twice overridesdispatch_with_context and deduplicates on the call’s ToolCallDedupeKey:
ToolCallDedupeKey::new(run_id, round, call_id, tool_name, arguments) derives
the same key, digest included, from its parts, for a tool that records keys
outside the dispatch. MCP tools and callback tools receive the same key:
Core’s MCP client adds it to the tools/call request’s _meta under
io.meerkat/tool_call_dedupe_key (meerkat_core::TOOL_CALL_DEDUPE_KEY_META_KEY),
and callback requests carry it as dedupe_key. An McpCallContextProvider
whose metadata uses that name is refused with McpCallContextError::Denied,
as for io.meerkat/origin, and the model gets an access_denied tool error
for that call.
Multimodal tool results
Tool results can carry either plain text or multimodal content blocks:ToolResult::new(...) creates a text-only result. ToolResult::with_blocks(...) passes content blocks directly into ToolResult.content, enabling tools to return images and other rich content to vision-capable models.
The built-in view_image tool uses the same content-block mechanism to read image files from disk and return them as ContentBlock::Image blocks. It is automatically hidden from models that lack vision or image tool result support.
Session stores
SessionStore owns the session persistence domain. A complete facade realm-backed
runtime also needs runtime lifecycle and delivery state, schedules, WorkGraph
state, detached jobs, blobs, and artifacts. RealmStorageProvider is that
facade persistence boundary: one provider returns every required store in a
RealmStoreSet, and the facade composes that set into the realm’s
PersistenceBundle.
Mob state is intentionally not a RealmStoreSet slot. The separate
meerkat-mob crate owns its mob store to avoid a facade dependency cycle;
Meta or another higher-level host composes it alongside the facade provider.
Since 0.9.5 a host can also keep a realm’s durable state in its own database
by implementing meerkat_core::host_store::HostStore; Core builds the realm’s
stores over it. See the Host Store SPI reference.
Each required slot declares a DurabilityClass and its actual
DurabilityResolution. Startup fails closed when a durable slot resolves to
non-persistent storage unless the realm manifest explicitly declares that
domain ephemeral. The required domains are sessions, runtime, schedule,
workgraph, jobs, blobs, and artifacts.
- JsonlStore
- MemoryStore
File-based persistence using JSONL format. Enable the facade’s
jsonl-store feature:Implementing a custom store
Implementing a custom store
Implement
SessionStore when replacing session-content storage.
AgentFactory::session_store() installs it for direct-agent or custom-builder
integration. It is not an override for persistent-service composition:
the persistent builders take their session store from PersistenceBundle
and install its adapter as the default per-agent override, taking precedence over
the factory’s custom store.Prefer
SessionStore for backend implementations: it includes list, delete,
and exists, and AgentFactory::session_store() wraps it via StoreAdapter.
That setter alone does not compose the runtime-backed lifecycle.For a realm-backed persistent host, put the custom store in
RealmStoreSet.session_store returned by your RealmStorageProvider, then
use open_realm_persistence_with_provider() to obtain the PersistenceBundle.
Supply or delegate all other required stores, keep each durability declaration
accurate, and preserve the runtime/session-store persistence-profile pairing:
HeadCanonicalV1 requires an IncrementalSessionStore. See Implementing a
realm storage provider below.Low-level PersistenceBundle::new() and related constructors also accept
custom stores; callers using them own the corresponding composition. With
session-store enabled, these constructors return Result and request ordinary
shared custody when supported by the backend. Handle construction refusal before
publishing the host.
For governed composition, select
PersistenceBundle::new_with_local_grant_authorization(...) upfront; see
Native governed embedding. A custom SessionStore
is not a drop-in replacement for the entire persistence bundle.Implementing a realm storage provider
Implementing a realm storage provider
Implement
RealmStorageProvider when an external backend must own the whole
realm. open() receives the canonical RealmOpenContext and returns a
RealmStoreSet with all seven required stores and exactly one durability
declaration for each domain. DiskStorageProvider is the built-in reference
implementation for SQLite, JSONL, and explicitly ephemeral memory realms.The snippet below is intentionally schematic and non-runnable: each backend
must construct its own seven stores and durability declarations before it can
return.Provider implementations should run the published meerkat-store-conformance
chapters for each supplied session, blob, and artifact trait capability. The
suite covers session round trips, guarded revisions, incremental/rewrite
semantics, concurrency, blob/artifact survival, and dangling references.
It is the only published suite. Runtime, scheduler, WorkGraph, and job store
contracts are checked by tests inside the Meerkat repository, against the
built-in memory and SQLite stores only; no published suite runs them against
a provider’s own stores. Facade composition enforces the provider’s complete
durability declaration set.A provider that versions its own SQLite domains can call
meerkat_sqlite::preflight_domain_version (since 0.9.4). It runs the schema
eligibility check that preflight_schema_eligibility runs and returns the
ledger version it verified (None for a fresh domain), read in the same
snapshot as the check. Decide whether a lazily provisioned domain exists, and
which of its tables to read, from that version rather than from a later read.MCP integration
Route tool calls across multiple MCP servers:See also
- Rust SDK overview - getting started, sessions, events
- Rust SDK advanced - expert-only direct agent construction, providers, hooks
- Tools concept - how the tool system works
- Durable runs and host stores - per-round commits, calls dispatched again, host stores
