Tools and stores

Tool system

Defining tools

Define tools using JSON Schema:

use meerkat::ToolDef;
use serde_json::json;

let tool = ToolDef::new(
    "get_weather",
    "Get current weather for a city",
    json!({
        "type": "object",
        "properties": {
            "city": {
                "type": "string",
                "description": "City name"
            },
            "units": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"],
                "default": "celsius"
            }
        },
        "required": ["city"]
    }),
);

Implementing AgentToolDispatcher

The AgentToolDispatcher trait connects your tools to the agent:

use async_trait::async_trait;
use meerkat::{AgentToolDispatcher, ToolDef, ToolError, ToolResult};
use meerkat_core::{ToolCallView, ToolDispatchOutcome};
use serde_json::json;
use std::sync::Arc;

struct MyToolDispatcher;

#[async_trait]
impl AgentToolDispatcher for MyToolDispatcher {
    fn tools(&self) -> Arc<[Arc<ToolDef>]> {
        vec![
            Arc::new(ToolDef::new(
                "search",
                "Search the web",
                json!({
                    "type": "object",
                    "properties": {
                        "query": {"type": "string"}
                    },
                    "required": ["query"]
                }),
            )),
        ].into()
    }

    async fn dispatch(&self, call: ToolCallView<'_>) -> Result<ToolDispatchOutcome, ToolError> {
        match call.name {
            "search" => {
                #[derive(serde::Deserialize)]
                struct Args { query: String }

                let args: Args = call.parse_args()
                    .map_err(|e| ToolError::invalid_arguments("search", e.to_string()))?;
                Ok(ToolResult::new(call.id.to_string(), format!("Results for: {}", args.query), false).into())
            }
            _ => Err(ToolError::not_found(call.name)),
        }
    }
}

ToolIdentityRegistry (dynamic registration)

For dynamic tool registration:

use meerkat_tools::registry::ToolIdentityRegistry;
use std::sync::Arc;

let mut registry = ToolIdentityRegistry::new();

registry.register(Arc::new(tool_def));

let weather = registry.get("get_weather");
let tools: Vec<_> = registry.iter().collect();

Multimodal tool results

Tool results can carry either plain text or multimodal content blocks:

use meerkat::ToolResult;
use meerkat_core::{ContentBlock, ImageData};

// Standard text result
let output = ToolResult::new("tool-1".into(), "{\"status\":\"ok\",\"count\":42}".into(), false);

// Multimodal result with image content
let output = ToolResult::with_blocks("tool-2".into(), vec![
    ContentBlock::Text { text: "Screenshot captured:".to_string() },
    ContentBlock::Image {
        media_type: "image/png".to_string(),
        data: ImageData::Inline { data: base64_encoded_png },
    },
], false);

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; MobKit or another higher-level host composes it alongside the facade provider. 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:

use meerkat::JsonlStore;
use std::path::PathBuf;

let store = JsonlStore::new(PathBuf::from("./sessions"));
store.init().await?;

store.save(&session).await?;
let session = store.load(&session_id).await?;
store.delete(&session_id).await?;

In-memory storage for testing:

use meerkat::MemoryStore;

let store = MemoryStore::new();
store.save(&session).await?;
let loaded = store.load(&session_id).await?;

Implementing a custom store

Implement the SessionStore trait and pass it to AgentFactory::session_store() when you are replacing only session persistence. Then compose the persistent service with MeerkatMachine so the custom store participates in the canonical runtime-backed lifecycle instead of only a one-off direct agent.

use async_trait::async_trait;
use meerkat::{Session, SessionFilter, SessionId, SessionMeta, SessionStore, SessionStoreError};
use std::sync::Arc;

struct BigQueryStore { /* your storage backend */ }

#[async_trait]
impl SessionStore for BigQueryStore {
    async fn save(&self, session: &Session) -> Result<(), SessionStoreError> {
        // Persist session to BigQuery
        Ok(())
    }

    async fn load(&self, id: &SessionId) -> Result<Option<Session>, SessionStoreError> {
        // Load session by ID
        Ok(None)
    }

    async fn list(&self, filter: SessionFilter) -> Result<Vec<SessionMeta>, SessionStoreError> {
        Ok(vec![])
    }

    async fn delete(&self, id: &SessionId) -> Result<(), SessionStoreError> {
        Ok(())
    }

    async fn delete_if_current_revision(
        &self,
        id: &SessionId,
        expected_current_revision: &str,
    ) -> Result<bool, SessionStoreError> {
        // Compare-and-delete for derived projections; return false when the
        // stored revision no longer matches.
        Ok(false)
    }
}

// Use as a custom store implementation boundary
let store: Arc<dyn SessionStore> = Arc::new(BigQueryStore { /* ... */ });

Prefer SessionStore + session_store() over implementing AgentSessionStore directly. SessionStore is the richer trait (with list, delete, exists) and AgentFactory automatically wraps it via StoreAdapter. Implementing AgentSessionStore directly bypasses the factory and loses runtime-backed session orchestration.For runtime-backed persistent services, realm persistence still flows through the PersistenceBundle opened for that realm. Treat custom SessionStore implementations as a storage seam for custom builders or direct agent/store integration, not as a drop-in replacement for the entire runtime persistence bundle.

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. Runtime, scheduler, WorkGraph, and job stores retain their own crate-level conformance suites, while facade composition enforces the provider’s complete durability declaration set.

use async_trait::async_trait;
use meerkat::{
    PersistenceError, RealmOpenContext, RealmStorageProvider, RealmStoreSet,
};

struct ExternalRealmProvider;

#[async_trait]
impl RealmStorageProvider for ExternalRealmProvider {
    fn name(&self) -> &str { "external" }

    async fn open(
        &self,
        ctx: &RealmOpenContext,
    ) -> Result<RealmStoreSet, PersistenceError> {
        // Open every store from ctx.locator / ctx.manifest and return one
        // durability declaration for each required domain.
        todo!()
    }
}

MCP integration

Route tool calls across multiple MCP servers:

use meerkat::{McpRouter, McpServerConfig};
use std::collections::HashMap;

let mut router = McpRouter::new();

// Add stdio-based MCP server
let config = McpServerConfig::stdio(
    "my-server",
    "/path/to/mcp-server".to_string(),
    vec!["--arg".to_string()],
    HashMap::new(),
);
router.add_server(config).await?;

// Add HTTP/SSE-based MCP server
let config = McpServerConfig::streamable_http(
    "remote-server",
    "https://mcp.example.com/sse".to_string(),
    HashMap::new(),
);
router.add_server(config).await?;

// List all available tools (synchronous snapshot)
let tools = router.list_tools();

// Call a tool (returns the result content blocks)
let result = router.call_tool("tool_name", &args).await?;

// Graceful shutdown
router.shutdown().await;

Rust

Python

TypeScript

Tools and stores

Tool system

Defining tools

Implementing AgentToolDispatcher

Multimodal tool results

Session stores

MCP integration

See also

​Tool system

​Defining tools

​Implementing AgentToolDispatcher

​Multimodal tool results

​Session stores

​MCP integration

​See also

Tool system

Defining tools

Implementing AgentToolDispatcher

Multimodal tool results

Session stores

MCP integration

See also