Skip to main content

Tool system

Defining tools

Define tools using JSON Schema:

Implementing AgentToolDispatcher

The AgentToolDispatcher trait connects your tools to the agent:
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 overrides dispatch_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.
File-based persistence using JSONL format. Enable the facade’s jsonl-store feature:
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.
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