Rust SDK overview

[dependencies]
meerkat = { version = "=0.8.42", features = ["sqlite-store", "session-store"] }
meerkat-store = "=0.8.42"
tokio = { version = "1", features = ["full"] }

use meerkat::{
    AgentFactory, Config, build_persistent_service_with_runtime_adapter,
    open_realm_persistence_in,
};
use meerkat_store::{RealmBackend, realm_paths_in};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = Config::load().await?;
    let realms_root = std::env::current_dir()?.join(".rkat").join("realms");
    let realm_id = "team-alpha";
    let realm_paths = realm_paths_in(&realms_root, realm_id);
    let (_manifest, persistence) = open_realm_persistence_in(
        &realms_root,
        realm_id,
        Some(RealmBackend::Sqlite),
        None,
    ).await?;
    let store_path = persistence
        .store_path()
        .unwrap_or(&realm_paths.root)
        .to_path_buf();
    let factory = AgentFactory::new(store_path).runtime_root(realm_paths.root);
    let (service, machine) = build_persistent_service_with_runtime_adapter(
        factory,
        config,
        64,
        persistence,
    );

    // A host now materializes actors through meerkat::surface helpers and
    // admits work through `machine`. Keep both values for the host lifetime.
    let _host_parts = (service, machine);
    Ok(())
}

export ANTHROPIC_API_KEY="<your-anthropic-api-key>"

use meerkat::{
    AgentFactory, Config, CreateSessionRequest, DeferredPromptPolicy,
    InitialTurnPolicy, SessionService, SystemPromptOverride, build_ephemeral_service,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = Config::load().await?;
    let factory = AgentFactory::new(std::env::current_dir()?);
    let service = build_ephemeral_service(factory, config, 64);

    let result = service.create_session(CreateSessionRequest {
        model: "claude-sonnet-4-6".into(),
        prompt: "What is the capital of France?".into(),
        injected_context: Vec::new(),
        system_prompt: SystemPromptOverride::Set("You are a helpful assistant.".into()),
        max_tokens: Some(1024),
        event_tx: None,
        initial_turn: InitialTurnPolicy::RunImmediately,
        deferred_prompt_policy: DeferredPromptPolicy::Discard,
        build: None,
        labels: None,
    }).await?;

    println!("Response: {}", result.text);
    println!("Session ID: {}", result.session_id);
    Ok(())
}

use meerkat::{
    CreateSessionRequest, DeferredPromptPolicy, InitialTurnPolicy, SessionService,
    StartTurnRequest, StartTurnRuntimeSemantics, SystemPromptOverride,
};

// Turn 1: create session
let result = service.create_session(CreateSessionRequest {
    model: "claude-sonnet-4-6".into(),
    prompt: "My name is Alice.".into(),
    injected_context: Vec::new(),
    system_prompt: SystemPromptOverride::Set("You are a helpful assistant with memory.".into()),
    max_tokens: None,
    event_tx: None,
    initial_turn: InitialTurnPolicy::RunImmediately,
    deferred_prompt_policy: DeferredPromptPolicy::Discard,
    build: None,
    labels: None,
}).await?;

let session_id = result.session_id;

// Turn 2: agent remembers "Alice"
let result = service.start_turn(&session_id, StartTurnRequest {
    prompt: "What's my name?".into(),
    injected_context: Vec::new(),
    system_prompt: None,
    event_tx: None,
    runtime: StartTurnRuntimeSemantics::default(),
}).await?;

// Read session state
let view = service.read(&session_id).await?;
println!("Messages: {}", view.state.message_count);

// Archive when done
service.archive(&session_id).await?;

use meerkat::{
    CreateSessionRequest, DeferredPromptPolicy, InitialTurnPolicy, SessionService,
    StartTurnRequest, StartTurnRuntimeSemantics, SystemPromptOverride,
};

let created = service.create_session(CreateSessionRequest {
    model: "claude-sonnet-4-6".into(),
    prompt: "Let's wait before we run.".into(),
    injected_context: Vec::new(),
    system_prompt: SystemPromptOverride::Set("You are the original prompt.".into()),
    max_tokens: None,
    event_tx: None,
    initial_turn: InitialTurnPolicy::Defer,
    deferred_prompt_policy: DeferredPromptPolicy::Stage,
    build: None,
    labels: None,
}).await?;

let result = service.start_turn(&created.session_id, StartTurnRequest {
    prompt: "Continue under the new instruction.".into(),
    injected_context: Vec::new(),
    system_prompt: Some("For this point forward, answer concisely.".into()),
    event_tx: None,
    runtime: StartTurnRuntimeSemantics::default(),
}).await?;

use meerkat::SessionError;

match service.start_turn(&id, req).await {
    Ok(result) => println!("Response: {}", result.text),
    Err(SessionError::NotFound { id }) => println!("Session {} not found", id),
    Err(SessionError::Busy { id }) => println!("Session {} is busy, retry later", id),
    Err(e) => println!("Error: {}", e),
}

let result = agent.run("What is 2 + 2?".into()).await?;
println!("Answer: {}", result.text);

use tokio::sync::mpsc;
use meerkat::AgentEvent;

let (tx, mut rx) = mpsc::channel::<AgentEvent>(100);

tokio::spawn(async move {
    while let Some(event) = rx.recv().await {
        match event {
            AgentEvent::TextDelta { delta } => print!("{}", delta),
            AgentEvent::ToolExecutionStarted { name, .. } => {
                println!("[Calling {}...]", name);
            }
            AgentEvent::TurnCompleted { usage: Some(usage), .. } => {
                // `usage` is per-call `TurnUsage`; its `accounting` names the
                // resolved provider/model and the normalized presented input.
                println!(
                    "\n[{} {}: {} tokens]",
                    usage.accounting().provider.as_str(),
                    usage.accounting().model,
                    usage.normalized_total_tokens()
                );
            }
            AgentEvent::TurnCompleted { usage: None, .. } => {
                // Accounting was absent. Skip this row - do not treat it as
                // zero. TurnUsageAccountingUnmeasured carries the reason.
            }
            _ => {}
        }
    }
});

let result = agent.run_with_events("Tell me a story".into(), tx).await?;

use meerkat::AgentError;

match agent.run("prompt".into()).await {
    Ok(result) => println!("Success: {}", result.text),
    Err(AgentError::Llm { provider, message, .. }) => {
        println!("LLM error ({}): {}", provider, message);
    }
    Err(AgentError::TokenBudgetExceeded { used, limit }) => {
        println!("Token budget exceeded: {} / {}", used, limit);
    }
    Err(e) => println!("Other error: {}", e),
}

use meerkat::{Message, UserMessage, BlockAssistantMessage, SystemMessage, ToolResult};
use meerkat_core::{ContentBlock, ImageData};

let system = Message::System(SystemMessage::new("You are helpful."));

// Text-only user message (convenience)
let user = Message::User(UserMessage::text("Hello!"));

// Multimodal user message with text and image
let user = Message::User(UserMessage::with_blocks(vec![
    ContentBlock::Text { text: "What is in this image?".to_string() },
    ContentBlock::Image {
        media_type: "image/png".to_string(),
        data: ImageData::Inline { data: base64_data },
    },
]));

use meerkat_core::ContentInput;

// Text-only (most common) — implements From<&str> and From<String>
let prompt: ContentInput = "What is Rust?".into();

// Multimodal — blocks with mixed content types
let prompt = ContentInput::Blocks(vec![
    ContentBlock::Text { text: "Describe this image.".to_string() },
    ContentBlock::Image {
        media_type: "image/jpeg".to_string(),
        data: ImageData::Inline { data: base64_data },
    },
]);

use meerkat::{ToolCall, ToolResult};

let tool_call = ToolCall {
    id: "tc_123".to_string(),
    name: "get_weather".to_string(),
    args: json!({"city": "Tokyo"}),
};

let result = ToolResult::new("tc_123".to_string(), "Sunny, 25C".to_string(), false);
let error = ToolResult::new("tc_123".to_string(), "City not found".to_string(), true);

let result: RunResult = agent.run("Hello".into()).await?;

println!("Response: {}", result.text);
println!("Session: {}", result.session_id);
println!("Tokens: {}", result.usage.total_tokens());
println!("Turns: {}", result.turns);
println!("Tool calls: {}", result.tool_calls);