Meerkat

https://docs.rkat.ai/
Admin
Meerkat is a library-first agent engine built in Rust that handles state machines, retries, budgets,...
Tokens:230,882
Snippets:2,222
Trust Score:2.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Quick Start with Meerkat Python SDK

Source: https://docs.rkat.ai/sdks/python/overview

A basic example demonstrating how to create a session, interact with it, stream responses, and archive the session.

```python
import asyncio
from meerkat import MeerkatClient, TextDelta

async def main() -> None:
    async with MeerkatClient() as client:
        session = await client.create_session("What is the capital of France?")
        print(session.text)

        result = await session.turn("And Germany?")
        print(result.text)

        async with session.stream("Give one extra fact.") as events:
            async for event in events:
                match event:
                    case TextDelta(delta=chunk):
                        print(chunk, end="", flush=True)
            print()

        await session.archive()

asyncio.run(main())
```

--------------------------------

### Complete Service Lifecycle Example

Source: https://docs.rkat.ai/rust/advanced

Demonstrates the full lifecycle of a service interaction: creating a session with a prompt and system prompt, starting a turn with a follow-up prompt, and reading session details including token billing.

```rust
use meerkat::{AgentFactory, Config, build_ephemeral_service};
use meerkat::{CreateSessionRequest, StartTurnRequest, SessionService};
use meerkat_core::service::InitialTurnPolicy;

#[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); // embedded/testing substrate only

    let result = service.create_session(CreateSessionRequest {
        model: "claude-sonnet-4-6".into(),
        prompt: "What is 25 * 17?".into(),
        render_metadata: None,
        system_prompt: Some("You are a helpful math assistant.".into()),
        max_tokens: Some(2048),
        event_tx: None,
        skill_references: None,
        initial_turn: InitialTurnPolicy::RunImmediately,
        build: None,
        labels: None,
    }).await?;

    println!("Response: {}", result.text);

    let result = service.start_turn(&result.session_id, StartTurnRequest {
        prompt: "Now divide that result by 5.".into(),
        system_prompt: None,
        render_metadata: None,
        handling_mode: HandlingMode::Queue,
        event_tx: None,
        skill_references: None,
        flow_tool_overlay: None,
        additional_instructions: None,
    }).await?;

    println!("Follow-up: {}", result.text);

    let view = service.read(&result.session_id).await?;
    println!("Total tokens: {}", view.billing.total_tokens);

    Ok(())
}
```

--------------------------------

### Prompt-First Examples with Input Piping

Source: https://docs.rkat.ai/cli/commands

Examples showing how to pipe input from standard input to rkat for processing.

```bash
rkat "summarize this repository"
```

```bash
cat story.txt | rkat "summarize the story"
```

```bash
git diff | rkat run --json "review these changes"
```

```bash
tail -f app.log | rkat run --stdin lines "watch for incidents"
```

--------------------------------

### Get Project-Scoped MCP Server

Source: https://docs.rkat.ai/cli/commands

Example of retrieving details for an MCP server configured specifically for the current project.

```bash
rkat mcp get filesystem --scope project
```

--------------------------------

### Agent Schedule Tool Examples

Source: https://docs.rkat.ai/guides/scheduling

Examples of schedule tools available within an agent session.

```python
meerkat_schedule_create
meerkat_schedule_get
meerkat_schedule_occurrences
```

--------------------------------

### Get Configuration in TOML Format

Source: https://docs.rkat.ai/cli/commands

Example of retrieving the rkat configuration specifically in TOML format.

```bash
rkat config get --format toml
```

--------------------------------

### Multimodal Prompt Example

Source: https://docs.rkat.ai/sdks/typescript/reference

Example of creating a session with a multimodal prompt, including text and an image.

```typescript
// Multimodal prompt example
const session = await client.createSession([
  { type: "text", text: "Describe this image" },
  { type: "image", media_type: "image/png", data: base64Data },
]);
```

--------------------------------

### Setup Methods

Source: https://docs.rkat.ai/rust/overview

Methods for initializing and configuring the Meerkat engine in Rust.

```APIDOC
## Setup

### `Config::load()`

#### Description
Load configuration from disk.

### `AgentFactory::new(store_root)`

#### Description
Create a factory for building agents.

### `open_realm_persistence_in(...)`

#### Description
Open a realm-backed persistence bundle.

### `build_persistent_service(factory, config, cap, persistence)`

#### Description
Build the runtime-backed persistent session substrate.

### `build_ephemeral_service(factory, config, cap)`

#### Description
Build an in-memory Queue-only substrate.
```

--------------------------------

### Install Meerkat Python SDK

Source: https://docs.rkat.ai/sdks/python/overview

Install the SDK using pip. For local development, use the editable install with dev dependencies.

```bash
pip install meerkat-sdk
```

```bash
pip install -e "sdks/python[dev]"
```

--------------------------------

### List All MCP Servers

Source: https://docs.rkat.ai/cli/commands

Example of listing all configured MCP servers across all scopes.

```bash
rkat mcp list --scope all
```

--------------------------------

### turn/start

Source: https://docs.rkat.ai/api/rpc

Start a new turn on existing session.

```APIDOC
## turn/start

### Description
Start a new turn on existing session.

### Method
RPC

### Endpoint
turn/start

### Parameters
#### Request Body
- **session_id** (string) - Required - The ID of the session.
- **prompt** (object) - Required - The prompt for the new turn.
  - **content** (string) - Required - The text content of the prompt.

### Request Example
```json
{
  "method": "turn/start",
  "session_id": "sess-abc",
  "prompt": {
    "content": "Tell me more."
  }
}
```

### Response
#### Success Response
- **turn** (object) - The result of the new turn.

### Response Example
```json
{
  "turn": {
    "content": [
      {
        "type": "text",
        "value": "Certainly!"
      }
    ]
  }
}
```
```

--------------------------------

### Custom Skill SKILL.md Example

Source: https://docs.rkat.ai/guides/skills

Example of a project-level custom skill definition file. Defines the skill's name, description, and requirements.

```markdown
---
name: my-deployment
description: Project-specific deployment procedures
requires_capabilities: []
---

# my-deployment

1. Run `make build` to create the release binary.
2. Deploy via `./deploy.sh production`.

```

--------------------------------

### Install Meerkat CLI

Source: https://docs.rkat.ai/quickstart

Install the Meerkat command-line interface using Cargo.

```bash
cargo install rkat
```

--------------------------------

### Start Meerkat Agent Session (Minimal Request)

Source: https://docs.rkat.ai/api/mcp

Use this minimal request to start a Meerkat agent session with a basic prompt. Ensure the 'prompt' field is populated with your query.

```json
{
  "prompt": "Write a haiku about Rust"
}
```

--------------------------------

### Start rkat-rpc server with TCP and WebSocket listeners

Source: https://docs.rkat.ai/api/rpc

Starts the server with optional TCP and realtime WebSocket listeners. TCP and WebSocket listeners are local-only by default. Binding a non-loopback address requires the --allow-remote flag.

```bash
rkat-rpc --tcp 127.0.0.1:9001
```

```bash
rkat-rpc --tcp 127.0.0.1:9001 --realtime-ws 127.0.0.1:9002
```

--------------------------------

### Set Configuration from Local File

Source: https://docs.rkat.ai/cli/commands

Example of setting the rkat configuration using a local TOML configuration file.

```bash
rkat config set ./.rkat/config.toml
```

--------------------------------

### CLI Quickstart: Generate Image

Source: https://docs.rkat.ai/guides/image-generation

Use this command to initiate image generation via the CLI, allowing only the image tool for the first turn. Ensure the `--tools safe` flag is used to enable builtins.

```bash
rkat run \
  --model gpt-5.5 \
  --allow-tool generate_image \
  "Use generate_image to create a square PNG of a cozy tabby cat by a sunlit window. Return the blob id and a one-sentence caption."
```

--------------------------------

### CLI: Run with JSON output

Source: https://docs.rkat.ai/examples/structured-output

Use the --output json flag to get the full result including structured_output. This shows an example of a simple arithmetic query.

```bash
# --output json returns the full result including structured_output
rkat run --output json --schema '{"type":"object","properties":{"answer":{"type":"string"}},"required":["answer"]}' "What is 2+2?"
# stdout: {"session_id":"...","text":"...","structured_output":{"answer":"4"}}
```

--------------------------------

### Prompt-First Usage with Options

Source: https://docs.rkat.ai/cli/commands

Demonstrates the general syntax for prompt-first usage, including optional arguments.

```bash
rkat [OPTIONS] <PROMPT>
```

```bash
rkat run [OPTIONS] <PROMPT>
```

--------------------------------

### Hook Event Types

Source: https://docs.rkat.ai/examples/hooks

Hooks emit various events into the session event stream. Subscribe to these events for building dashboards, alerting, or audit trails. Examples include hook start, completion, denial, failure, and rewrite application.

```json
// HookStarted -- emitted when a hook begins execution
{"type": "hook_started", "hook_id": "safety-gate", "point": "pre_tool_execution"}

// HookCompleted -- emitted when a hook finishes successfully
{"type": "hook_completed", "hook_id": "safety-gate", "point": "pre_tool_execution", "duration_ms": 42}

// HookDenied -- emitted when a hook blocks execution
{"type": "hook_denied", "hook_id": "safety-gate", "point": "pre_tool_execution", "reason_code": "policy_violation", "message": "rm -rf not allowed"}

// HookFailed -- emitted when a hook errors or times out
{"type": "hook_failed", "hook_id": "audit-log", "point": "post_tool_execution", "error": "process exited with code 1"}

// HookRewriteApplied -- emitted when a hook applies a patch
{"type": "hook_rewrite_applied", "hook_id": "pii-scrub", "point": "post_tool_execution", "patch": {"ToolResult": {"content": "***", "is_error": null}}}
```

--------------------------------

### Shell Tool Configuration Example

Source: https://docs.rkat.ai/reference/builtin-tools

Illustrates the configuration options for shell tools, including enabling, timeouts, path restrictions, and security modes.

```rust
ShellConfig {
    enabled: true,
    default_timeout_secs: 60,
    restrict_to_project: false,
    shell: "bash".to_string(),
    shell_path: Some("/bin/bash".into()),
    project_root: "/path/to/project".into(),
    max_completed_jobs: 50,
    completed_job_ttl_secs: 600,
    max_concurrent_processes: 20,
    security_mode: SecurityMode::AllowList,
    security_patterns: vec!["ls *.txt".to_string(), "grep *.log".to_string()],
}
```

--------------------------------

### initialize

Source: https://docs.rkat.ai/api/rpc

Returns server capabilities. This is typically the first method called to understand what the server supports.

```APIDOC
## initialize

### Description
Returns server capabilities.

### Method
RPC

### Endpoint
initialize

### Parameters
None

### Request Example
```json
{
  "method": "initialize"
}
```

### Response
#### Success Response
- **capabilities** (object) - Server capabilities.

### Response Example
```json
{
  "capabilities": {
    "some_capability": true
  }
}
```
```

--------------------------------

### session/create

Source: https://docs.rkat.ai/api/rpc

Create session and run first turn.

```APIDOC
## session/create

### Description
Create session and run first turn.

### Method
RPC

### Endpoint
session/create

### Parameters
#### Request Body
- **prompt** (object) - Required - The initial prompt for the session.
  - **content** (string) - Required - The text content of the prompt.

### Request Example
```json
{
  "method": "session/create",
  "prompt": {
    "content": "Hello, world!"
  }
}
```

### Response
#### Success Response
- **session_id** (string) - The ID of the created session.
- **turn** (object) - The result of the first turn.

### Response Example
```json
{
  "session_id": "sess-abc",
  "turn": {
    "content": [
      {
        "type": "text",
        "value": "Hi there!"
      }
    ]
  }
}
```
```

--------------------------------

### Example Error Responses

Source: https://docs.rkat.ai/api/rest

Examples of common error responses, including 'Session not found' and 'Bad request'.

```APIDOC
## Example Error Responses

<CodeGroup>
  ```json Session not found
  {
    "error": "Session not found: 01936f8a-7b2c-7000-8000-000000000099",
    "code": "SESSION_NOT_FOUND"
  }
  ```

  ```json Bad request
  {
    "error": "Session ID mismatch: path=abc body=def",
    "code": "BAD_REQUEST"
  }
  ```
</CodeGroup>
```

--------------------------------

### Prompt-First Examples with Advanced Flags

Source: https://docs.rkat.ai/cli/commands

Illustrates prompt-first usage with advanced flags like `--yolo` and parameter specification.

```bash
rkat run -t workspace "fix the failing test"
```

```bash
rkat run --yolo --param temperature=0.2 "take the gloves off"
```

--------------------------------

### Configure Filesystem and Stdio Skill Sources

Source: https://docs.rkat.ai/guides/skills

Configure filesystem and stdio sources for skills in TOML format. Filesystem sources point to a local path, while stdio sources specify a command and arguments to run.

```toml
[[repositories]]
name = "local-shared"
source_uuid = "33333333-3333-3333-3333-333333333333"
type = "filesystem"
path = "/opt/meerkat-skills"

[[repositories]]
name = "generated"
source_uuid = "44444444-4444-4444-4444-444444444444"
type = "stdio"
command = "my-skill-server"
args = ["--json"]
```

--------------------------------

### Install wasm-pack

Source: https://docs.rkat.ai/cli/commands

Installs the wasm-pack tool, which is a prerequisite for building web artifacts with `rkat mob web build`.

```bash
cargo install wasm-pack
wasm-pack --version
```

--------------------------------

### Python: Accessing Structured Output

Source: https://docs.rkat.ai/examples/structured-output

Demonstrates how to create a session with an output schema and access the structured output as a dictionary in Python.

```python
session = await client.create_session("Tell me about Tokyo", output_schema=schema)
data = session.structured_output  # dict: {"city": "Tokyo", "country": "Japan", ...}
print(data["city"])
print(data["population"])
```

--------------------------------

### Session Not Found Error Example

Source: https://docs.rkat.ai/api/rest

Example of a 'SESSION_NOT_FOUND' error response. This occurs when a requested session ID does not exist.

```json
{
  "error": "Session not found: 01936f8a-7b2c-7000-8000-000000000099",
  "code": "SESSION_NOT_FOUND"
}
```

--------------------------------

### Build and Orchestrate a Mob Runtime

Source: https://docs.rkat.ai/reference/api-reference

This example demonstrates building a mob runtime from a TOML definition, creating and wiring members, sending messages, and running a flow. It requires setting up persistent storage and a session service.

```rust
use std::sync::Arc;
use meerkat_core::types::HandlingMode;
use meerkat_mob::{
    AgentIdentity,
    FlowId,
    MobBuilder,
    MobDefinition,
    MobSessionService,
    MobStorage,
    SpawnMemberSpec,
};

async fn orchestrate(
    definition_toml: &str,
    session_service: Arc<dyn MobSessionService>,
) -> Result<(), Box<dyn std::error::Error>> {
    let definition = MobDefinition::from_toml(definition_toml)?;
    let storage = MobStorage::persistent("./mob.db")?;

    let handle = MobBuilder::new(definition, storage)
        .with_session_service(session_service)
        .create()
        .await?;

    handle
        .spawn_spec(SpawnMemberSpec::new("lead", AgentIdentity::from("lead-1")))
        .await?;
    handle
        .spawn_spec(SpawnMemberSpec::new("worker", AgentIdentity::from("worker-1")))
        .await?;
    handle
        .wire(
            AgentIdentity::from("lead-1"),
            AgentIdentity::from("worker-1"),
        )
        .await?;
    let lead = handle.member(&AgentIdentity::from("lead-1")).await?;
    lead.send("Coordinate work.", HandlingMode::Queue).await?;

    let run_id = handle
        .run_flow(FlowId::from("release_flow"), serde_json::json!({{"severity":"critical"}}))
        .await?;
    let _run = handle.flow_status(run_id).await?;
    Ok(())
}
```

--------------------------------

### Bad Request Error Example

Source: https://docs.rkat.ai/api/rest

Example of a 'BAD_REQUEST' error response. This can indicate invalid parameters or a session ID mismatch.

```json
{
  "error": "Session ID mismatch: path=abc body=def",
  "code": "BAD_REQUEST"
}
```

--------------------------------

### Create and Connect to a Realtime Session

Source: https://docs.rkat.ai/guides/realtime

Demonstrates how to establish a connection to a realtime-capable model and create a session. Ensure the model specified is compatible with realtime transport.

```python
from meerkat import MeerkatClient

async with MeerkatClient() as client:
    await client.connect(realm_id="team-alpha")

    # 1. Create a session on a realtime-capable model — transport attaches automatically.
    session = await client.create_session(
        prompt="Ready for realtime audio.",
        model="gpt-realtime-1.5",
        provider="openai",
    )

    # 2. Wait for the binding to reach BindingReady.
    while True:
        status = await client.runtime_realtime_attachment_status(session.id)
        if status.status == "binding_ready":
            break
        await asyncio.sleep(0.1)

    # 3. Obtain a bootstrap token and open the audio WebSocket.
    bootstrap = await client.realtime_open_info(session.id)
    # ... open ws to bootstrap.url, exchange audio chunks ...

    # 4. The session's history accumulates committed turns as audio commits
    #    at turn boundaries — same as a text session.
    history = await client.session_history(session.id)
```

--------------------------------

### Initialize Agent with Memory Store (SDK)

Source: https://docs.rkat.ai/guides/memory

This Rust SDK example demonstrates how to initialize an AgentFactory with memory support enabled. Memory and compaction features are automatically wired if the factory is configured with `memory(true)` and the binary is compiled with the corresponding features.

```rust
use meerkat::{AgentFactory, AgentBuildConfig};
use meerkat_store;

let realm = meerkat_store::realm_paths("team-alpha");
let factory = AgentFactory::new(realm.root.clone())
    .runtime_root(realm.root)
    .project_root(".")
    .builtins(true)
    .memory(true);

let mut build_config = AgentBuildConfig::new("claude-sonnet-4-6");
// Memory + compaction are wired automatically when:
//   1. The factory has memory(true)
//   2. The binary is compiled with session-compaction + memory-store-session features

let agent = factory.build_agent(build_config, &config).await?;
```

--------------------------------

### Install Meerkat TypeScript SDK

Source: https://docs.rkat.ai/quickstart

Install the Meerkat TypeScript SDK using npm. The SDK automatically handles the rpc server.

```bash
npm install @rkat/sdk
```

--------------------------------

### Install Meerkat Python SDK

Source: https://docs.rkat.ai/quickstart

Install the Meerkat Python SDK using pip. The SDK automatically handles the rpc server.

```bash
pip install meerkat-sdk
```

--------------------------------

### Structured Output Response Example

Source: https://docs.rkat.ai/api/rest

Example of a response body when structured output is requested, showing parsed output and schema warnings.

```json
{
  "session_id": "01936f8a-7b2c-7000-8000-000000000002",
  "text": "{\"country\":\"France\",\"capital\":\"Paris\"}",
  "turns": 1,
  "tool_calls": 0,
  "usage": {
    "input_tokens": 80,
    "output_tokens": 30,
    "total_tokens": 110
  },
  "structured_output": {
    "country": "France",
    "capital": "Paris"
  },
  "schema_warnings": [
    {
      "provider": "gemini",
      "path": "/properties/choice/oneOf",
      "message": "Removed unsupported keyword 'oneOf'"
    }
  ]
}
```

--------------------------------

### Structured Output Request Example

Source: https://docs.rkat.ai/api/rest

Example of a request body for generating structured output, including schema definition and retry settings.

```json
{
  "prompt": "Extract the capital of France",
  "model": "claude-opus-4-6",
  "output_schema": {
    "schema": {
      "type": "object",
      "properties": {
        "country": {"type": "string"},
        "capital": {"type": "string"}
      },
      "required": ["country", "capital"]
    },
    "name": "capital_extraction",
    "strict": false,
    "compat": "lossy",
    "format": "meerkat_v1"
  },
  "structured_output_retries": 2
}
```

--------------------------------

### TOML Configuration for Hooks

Source: https://docs.rkat.ai/guides/hooks

Example TOML configuration for setting up hooks, including default timeouts, payload sizes, and concurrency limits. It also shows how to define individual hook entries with their specific configurations.

```toml
[hooks]
default_timeout_ms = 5000       # Default: 5000
payload_max_bytes = 131072      # Default: 128 * 1024 (128 KiB)
background_max_concurrency = 32 # Default: 32

[[hooks.entries]]
id = "safety-check"
enabled = true
point = "pre_tool_execution"
mode = "foreground"
capability = "guardrail"
priority = 10
# failure_policy = "fail_closed"  # Optional; defaults based on capability
# timeout_ms = 10000              # Optional; overrides default_timeout_ms

[hooks.entries.runtime]
type = "command"
command = "python3"
args = ["hooks/safety_check.py"]
```

--------------------------------

### POST /auth/login/start

Source: https://docs.rkat.ai/api/rest

Initiates a loopback OAuth login process. The server manages the OAuth state and PKCE verifier. Requires provider and redirect URI.

```APIDOC
## POST /auth/login/start

### Description
Begin a loopback OAuth login. The server owns the OAuth state and PKCE verifier.

### Method
POST

### Endpoint
/auth/login/start

### Request Body
- **provider** (string) - Required - The OAuth provider.
- **redirect_uri** (string) - Required - The URI to redirect to after authentication.

### Request Example
{
  "provider": "anthropic",
  "redirect_uri": "http://127.0.0.1:53682/callback"
}
```

--------------------------------

### Get Realm Config

Source: https://docs.rkat.ai/api/mcp

Use the 'get' action to retrieve the current realm configuration for the MCP server instance. No parameters are required.

```json
{ "action": "get" }
```

--------------------------------

### Start Meerkat Agent Session (Full Request)

Source: https://docs.rkat.ai/api/mcp

This full request demonstrates how to configure advanced options for a Meerkat agent session, including system prompts, model selection, output schemas, and tool definitions. It's useful for complex tasks requiring specific configurations.

```json
{
  "prompt": "Analyze this code for bugs",
  "system_prompt": "You are a senior code reviewer.",
  "model": "claude-opus-4-6",
  "max_tokens": 4096,
  "provider": "anthropic",
  "output_schema": {
    "type": "object",
    "properties": {
      "bugs": {"type": "array", "items": {"type": "string"}},
      "severity": {"type": "string"}
    },
    "required": ["bugs", "severity"]
  },
  "structured_output_retries": 2,
  "stream": false,
  "verbose": false,
  "tools": [
    {
      "name": "read_file",
      "description": "Read a file from disk",
      "input_schema": {
        "type": "object",
        "properties": {"path": {"type": "string"}},
        "required": ["path"]
      },
      "handler": "callback"
    }
  ],
  "enable_builtins": false,
  "builtin_config": {
    "enable_shell": false,
    "shell_timeout_secs": 30
  },
  "keep_alive": null,
  "comms_name": null,
  "hooks_override": null
}
```

--------------------------------

### Run Image Generation with Gemini Provider Parameters

Source: https://docs.rkat.ai/concepts/providers

Example of running a Gemini model with a specified thinking budget for extended analysis.

```bash
rkat run --model gemini-3-flash-preview --param thinking_budget=5000 "Analyze this data"
```

--------------------------------

### Runtime Hook Response Example

Source: https://docs.rkat.ai/guides/hooks

An example of a RuntimeHookResponse JSON object, which can include a decision and a list of patches. An empty response signifies no opinion.

```json
{
  "decision": { "decision": "deny", "hook_id": "my-guard", "reason_code": "policy_violation", "message": "blocked" },
  "patches": [
    { "patch_type": "tool_args", "args": { "sanitized": true } }
  ]
}
```

--------------------------------

### Initialize OpenAI Client

Source: https://docs.rkat.ai/rust/advanced

Create an OpenAI LLM client using an API key, environment variables, or a custom base URL for Azure deployments or proxies.

```rust
use meerkat::OpenAiClient;

let client = OpenAiClient::new("sk-...".to_string());
let client = OpenAiClient::from_env()?;
let client = OpenAiClient::new("key".to_string())
    .with_base_url("https://my-deployment.openai.azure.com".to_string());
```

--------------------------------

### Start the rkat-rpc server

Source: https://docs.rkat.ai/api/rpc

Starts the server which reads newline-delimited JSON from stdin and writes JSON to stdout. Each line is a complete JSON-RPC 2.0 message.

```bash
rkat-rpc
```

--------------------------------

### OutputSchema wrapper format example

Source: https://docs.rkat.ai/guides/structured-output

Shows the JSON structure for the wrapper format, which allows explicit configuration of schema, name, strictness, compatibility, and format.

```json
{
  "schema": {
    "type": "object",
    "properties": {
      "result": { "type": "string" }
    }
  },
  "name": "my-schema",
  "strict": true,
  "compat": "strict",
  "format": "meerkat_v1"
}
```

--------------------------------

### Budget Warning Event Example

Source: https://docs.rkat.ai/examples/memory

An example of a 'budget_warning' event emitted when resource consumption nears a limit. This event includes the budget type, current usage, limit, and percentage consumed.

```json
{
  "type": "budget_warning",
  "budget_type": "tokens",
  "used": 8500,
  "limit": 10000,
  "percent": 85.0
}
```

--------------------------------

### Initialize Gemini Client

Source: https://docs.rkat.ai/rust/advanced

Create a Gemini LLM client using an API key or by loading credentials from the environment.

```rust
use meerkat::GeminiClient;

let client = GeminiClient::new("...".to_string());
let client = GeminiClient::from_env()?;
```

--------------------------------

### session/read

Source: https://docs.rkat.ai/api/rpc

Get session state.

```APIDOC
## session/read

### Description
Get session state.

### Method
RPC

### Endpoint
session/read

### Parameters
#### Request Body
- **session_id** (string) - Required - The ID of the session to read.

### Request Example
```json
{
  "method": "session/read",
  "session_id": "sess-abc"
}
```

### Response
#### Success Response
- **state** (object) - The current state of the session.

### Response Example
```json
{
  "state": {
    "last_turn": { ... }
  }
}
```
```

--------------------------------

### Retry Event Example

Source: https://docs.rkat.ai/examples/memory

An example of a 'retrying' event indicating an automatic retry attempt due to a transient LLM error. It shows the current attempt number, maximum attempts, the error type, and the delay before the next retry.

```json
{
  "type": "retrying",
  "attempt": 2,
  "max_attempts": 5,
  "error": "rate_limit_exceeded",
  "delay_ms": 4000
}
```

--------------------------------

### Rkat Init Command

Source: https://docs.rkat.ai/cli/commands

Initializes the Rkat configuration by creating the `.rkat/config.toml` file from a global template. This is typically the first command to run.

```bash
rkat init
```

--------------------------------

### approval/get

Source: https://docs.rkat.ai/api/rpc

Get one approval record.

```APIDOC
## approval/get

### Description
Get one approval record.

### Method
RPC

### Endpoint
approval/get

### Parameters
#### Request Body
- **approval_id** (string) - Required - The ID of the approval record to retrieve.

### Request Example
```json
{
  "method": "approval/get",
  "approval_id": "appr-123"
}
```

### Response
#### Success Response
- **approval** (object) - The approval record.

### Response Example
```json
{
  "approval": {
    "id": "appr-123",
    "title": "Approve deployment",
    "status": "pending"
  }
}
```
```

--------------------------------

### Build and Use SkillRuntime in Rust

Source: https://docs.rkat.ai/guides/skills

Demonstrates how to initialize an AgentFactory, build a SkillRuntime, list skills with their provenance, and load a specific skill's body. Requires the 'skills' feature to be enabled.

```rust
use meerkat::{AgentFactory, SkillRuntime, SkillFilter};
use meerkat_core::{Config, skills::{SkillKey, SkillName, SourceUuid}};

let config = Config::load().await?;
let factory = AgentFactory::new(store_path);

// Build a SkillRuntime (requires "skills" feature)
if let Some(runtime) = factory.build_skill_runtime(&config).await? {
    // List all skills with provenance
    let entries = runtime.list_all_with_provenance(&SkillFilter::default()).await?;
    for entry in &entries {
        println!(
            "{}: active={}, source={}",
            entry.descriptor.key,
            entry.is_active,
            entry.descriptor.source_name,
        );
    }

    // Load a specific skill's body (bypassing first-wins)
    let key = SkillKey::new(
        SourceUuid::parse("dc256086-0d2f-4f61-a307-320d4148107f")?,
        SkillName::parse("task-workflow")?,
    );
    let doc = runtime.load_from_source(&key, Some("dc256086-0d2f-4f61-a307-320d4148107f")).await?;
    println!("{}", doc.body);
}
```

--------------------------------

### meerkat_config

Source: https://docs.rkat.ai/api/mcp

Gets or updates the server configuration.

```APIDOC
## meerkat_config

### Description
Get or update server config.

### Method
(Not specified, assumed to be a tool invocation)

### Endpoint
(Not specified)

### Parameters
(Not specified)

### Request Example
(Not specified)

### Response
(Not specified)
```

--------------------------------

### artifact/get

Source: https://docs.rkat.ai/api/rpc

Get one stable artifact record.

```APIDOC
## artifact/get

### Description
Get one stable artifact record.

### Method
RPC

### Endpoint
artifact/get

### Parameters
#### Request Body
- **artifact_id** (string) - Required - The ID of the artifact to retrieve.

### Request Example
```json
{
  "method": "artifact/get",
  "artifact_id": "art-1"
}
```

### Response
#### Success Response
- **artifact** (object) - The artifact record.

### Response Example
```json
{
  "artifact": {
    "id": "art-1",
    "name": "model.onnx",
    "blob_id": "blob-xyz",
    "size": 1024
  }
}
```
```

--------------------------------

### Create Session for Realtime Interaction

Source: https://docs.rkat.ai/api/rest

Create a new session with a realtime-capable model to enable realtime interaction. The runtime automatically attaches the transport, and the status endpoint reports `binding_ready` when confirmed. Control realtime mode by swapping the session's model.

```bash
curl -X POST http://127.0.0.1:8080/sessions \
  -H 'content-type: application/json' \
  -d '{"prompt":"Ready for realtime interaction.","model":"gpt-realtime-1.5","provider":"openai"}'
```

--------------------------------

### session/history

Source: https://docs.rkat.ai/api/rpc

Get committed session transcript messages.

```APIDOC
## session/history

### Description
Get committed session transcript messages.

### Method
RPC

### Endpoint
session/history

### Parameters
#### Request Body
- **session_id** (string) - Required - The ID of the session.

### Request Example
```json
{
  "method": "session/history",
  "session_id": "sess-abc"
}
```

### Response
#### Success Response
- **messages** (array) - A list of messages in the session transcript.

### Response Example
```json
{
  "messages": [
    { "role": "user", "content": "Hello" },
    { "role": "assistant", "content": "Hi there!" }
  ]
}
```
```

--------------------------------

### Set Configuration from File

Source: https://docs.rkat.ai/cli/commands

Set the rkat configuration by providing a path to a configuration file.

```bash
rkat config set <FILE>
```

--------------------------------

### Mob Creation, Spawning, and Workflows (Rust SDK)

Source: https://docs.rkat.ai/guides/mobs

Demonstrates mob creation, member spawning, wiring agents, and running workflows using the Rust SDK.

```APIDOC
## Mob Definition

### Description
Defines the structure and properties of a mob.

### Method
`MobDefinition::from_json`

### Parameters
- `json` (string) - Required - JSON string representing the mob definition.

### Request Example
```rust
let definition = MobDefinition::from_json(json)?;
```

## Mob Builder

### Description
Builds a mob instance with specified configurations.

### Method
`MobBuilder::new`

### Parameters
- `definition` (MobDefinition) - Required - The mob definition.
- `storage` (MobStorage) - Required - The storage mechanism for the mob.

### Configuration Methods
- `with_session_service(service)`: Configures the session service.
- `allow_ephemeral_sessions(true)`: Allows ephemeral sessions.

### Create Mob

### Method
`create`

### Request Example
```rust
let handle = MobBuilder::new(definition, MobStorage::in_memory())
    .with_session_service(service)
    .allow_ephemeral_sessions(true)
    .create()
    .await?;
```

## Spawn Member

### Description
Spawns a member according to a specification.

### Method
`handle.spawn_spec`

### Parameters
- `spec` (SpawnMemberSpec) - Required - The specification for the member to spawn.
  - `profile` (string) - Required - The profile of the member.
  - `agent_identity` (string) - Required - The identity of the agent.

### Request Example
```rust
handle
    .spawn_spec(SpawnMemberSpec::new("lead", "lead-1"))
    .await?;
```

## Wire Agents

### Description
Establishes communication between two agents.

### Method
`handle.wire`

### Parameters
- `agent1` (AgentIdentity) - Required - The identity of the first agent.
- `agent2` (AgentIdentity) - Required - The identity of the second agent.

### Request Example
```rust
handle
    .wire(AgentIdentity::from("lead-1"), AgentIdentity::from("worker-1"))
    .await?;
```

## Run Workflow

### Description
Executes a defined workflow.

### Method
`handle.run_flow`

### Parameters
- `name` (string) - Required - The name of the workflow to run.
- `payload` (json) - Required - The payload for the workflow.

### Request Example
```rust
handle.run_flow("triage", json!({}))
    .await?;
```
```

--------------------------------

### GET /realms

Source: https://docs.rkat.ai/api/rest

Lists summaries of all configured realms.

```APIDOC
## GET /realms

### Description
List configured realm summaries.

### Method
GET

### Endpoint
/realms
```

--------------------------------

### GET /config

Source: https://docs.rkat.ai/api/rest

Retrieves the current realm configuration.

```APIDOC
## GET /config

### Description
Returns a realm config envelope.

### Method
GET

### Endpoint
/config

### Response
#### Success Response (200)
- **config** (object) - The main configuration object.
- **generation** (any) - The generation identifier.
- **realm_id** (string) - The ID of the realm.
- **instance_id** (string) - The ID of the instance.
- **backend** (object) - Backend specific configuration.
- **resolved_paths** (object) - Resolved paths for configuration files.
```

--------------------------------

### realtime/open_info

Source: https://docs.rkat.ai/api/rpc

Get bootstrap metadata for opening a realtime channel.

```APIDOC
## realtime/open_info

### Description
Get bootstrap metadata for opening a realtime channel.

### Method
RPC

### Endpoint
realtime/open_info

### Parameters
None

### Request Example
```json
{
  "method": "realtime/open_info"
}
```

### Response
#### Success Response
- **info** (object) - Realtime channel bootstrap information.

### Response Example
```json
{
  "info": {
    "url": "wss://realtime.example.com/ws",
    "token": "secret-token"
  }
}
```
```

--------------------------------

### Run Image Generation with Anthropic Provider Parameters

Source: https://docs.rkat.ai/concepts/providers

Example of running an Anthropic model with custom parameters like thinking budget.

```bash
rkat run --model claude-sonnet-4-6 --param thinking_budget=10000 "Solve this problem"
```

--------------------------------

### GET /sessions/{id}

Source: https://docs.rkat.ai/api/rest

Fetch session metadata and usage statistics.

```APIDOC
## GET /sessions/\{id}

### Description
Fetch session metadata and usage.

### Method
GET

### Endpoint
/sessions/\{id}

### Response
#### Success Response (200)
- **session_id** (string) - The unique identifier for the session.
- **created_at** (string) - The timestamp when the session was created.
- **updated_at** (string) - The timestamp when the session was last updated.
- **message_count** (integer) - The total number of messages in the session.
- **total_tokens** (integer) - The total number of tokens used in the session.

### Response Example
```json
{
  "session_id": "01936f8a-7b2c-7000-8000-000000000001",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:31:00Z",
  "message_count": 4,
  "total_tokens": 500
}
```
```

--------------------------------

### Realtime Bootstrap Methods

Source: https://docs.rkat.ai/guides/realtime

These product-layer RPC methods allow callers to open and inspect the actual audio transport on top of the session attachment.

```APIDOC
## Realtime Bootstrap Methods

These product-layer RPC methods allow callers to open and inspect the actual audio transport on top of the session attachment.

### `realtime/open_info`

**Purpose:** Issue a single-use bootstrap token for opening a realtime WebSocket.

### `realtime/status`

**Purpose:** Read product-layer realtime channel status for a session.

### `realtime/capabilities`

**Purpose:** Read product-layer realtime capabilities (supported input/output kinds, interrupt/transcript support).

**Usage:**
1. Create or resume a session on a realtime-capable model.
2. Poll `session/realtime_attachment_status` until it reports `binding_ready`.
3. Ensure the host actually exposes the realtime websocket bootstrap service.
4. Call `realtime/open_info` to obtain a bootstrap token.
5. Open a WebSocket to the bootstrap URL to exchange audio chunks.
```

--------------------------------

### Create and Use Sessions with Skills in TypeScript

Source: https://docs.rkat.ai/sdks/typescript/reference

Demonstrates how to preload skills into a session at creation time or inject them for specific turns. Also shows a convenience method for invoking a single skill.

```typescript
const session = await client.createSession("Hello!", {
  preloadSkills: [
    { sourceUuid: "dc256086-0d2f-4f61-a307-320d4148107f", skillName: "extraction-email" },
    { sourceUuid: "dc256086-0d2f-4f61-a307-320d4148107f", skillName: "formatting-markdown" },
  ],
});
```

```typescript
const result = await session.turn("Extract emails from this text", {
  skillRefs: [{ sourceUuid: "abc123", skillName: "extraction-email" }],
});
```

```typescript
const result2 = await session.invokeSkill(
  { sourceUuid: "abc123", skillName: "extraction-email" },
  "Extract emails from this text",
);
```

--------------------------------

### Get Version

Source: https://docs.rkat.ai/sdks/python/reference

Fetch the current contract version of the Meerkat SDK.

```APIDOC
## Get Version

### Description
Fetch the current contract version of the Meerkat SDK.

### Method
```python
from meerkat import CONTRACT_VERSION
print(CONTRACT_VERSION)
```

### Example
```
"0.6.0"
```
```

--------------------------------

### meerkat_mob_status

Source: https://docs.rkat.ai/api/mcp

Gets the lifecycle status for a specific mob (mob feature).

```APIDOC
## meerkat_mob_status

### Description
Get lifecycle status for one mob (mob feature).

### Method
(Not specified, assumed to be a tool invocation)

### Endpoint
(Not specified)

### Parameters
(Not specified)

### Request Example
(Not specified)

### Response
(Not specified)
```

--------------------------------

### Run Image Generation with OpenAI Provider Parameters

Source: https://docs.rkat.ai/concepts/providers

Example of running an OpenAI model with specific reasoning effort and seed for deterministic outputs.

```bash
rkat run --model gpt-5.4 --param reasoning_effort=high "Prove this theorem"
```

--------------------------------

### GET /comms/peers

Source: https://docs.rkat.ai/api/rest

Lists discoverable peers for a session. Requires the `comms` feature.

```APIDOC
## GET /comms/peers

### Description
List discoverable peers for a session. Requires the `comms` feature.

### Method
GET

### Endpoint
/comms/peers

### Parameters
#### Query Parameters
- **session_id** (string) - Required - Session ID to query peers for.

### Response
#### Success Response (200 OK)
- **peers** (array) - An array of peer objects, each containing `name` (string) and `address` (string).

#### Response Example
```json
{
  "peers": [
    {"name": "reviewer", "address": "127.0.0.1:4201"},
    {"name": "coordinator", "address": "inproc"}
  ]
}
```
```
Tokens:
Raw