Examples: Sessions & streaming

For concepts, see Sessions and Realms.

The Rust snippets on this page use the SessionService API. Production surfaces host that service behind the runtime control plane; small standalone Rust examples may instead construct EphemeralSessionService directly.

Create a session

rkat run --model claude-sonnet-4-6 "What is the capital of France?"

{
  "jsonrpc": "2.0", "id": 1,
  "method": "session/create",
  "params": {
    "prompt": "What is the capital of France?",
    "model": "claude-sonnet-4-6"
  }
}

curl -X POST http://localhost:8080/sessions \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What is the capital of France?", "model": "claude-sonnet-4-6"}'

{
  "prompt": "What is the capital of France?",
  "model": "claude-sonnet-4-6"
}

Called via the meerkat_run tool.

async with MeerkatClient() as client:
    session = await client.create_session(
        "What is the capital of France?",
        model="claude-sonnet-4-6",
    )
    print(session.text)

const client = new MeerkatClient();
await client.connect();

const session = await client.createSession("What is the capital of France?", {
  model: "claude-sonnet-4-6",
});
console.log(session.text);

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::Inherit,
    max_tokens: None,
    event_tx: None,
    initial_turn: InitialTurnPolicy::RunImmediately,
    deferred_prompt_policy: DeferredPromptPolicy::default(),
    build: None,
    labels: None,
}).await?;
println!("{}", result.text);

Multi-turn

# Resume the most recent session
rkat run --resume last "Now explain it in more detail"

# Or target a specific prior session
rkat run --resume ~2 "Now explain it in more detail"

{
  "jsonrpc": "2.0", "id": 2,
  "method": "turn/start",
  "params": {
    "session_id": "01936f8a-7b2c-7000-8000-000000000001",
    "prompt": "Now explain it in more detail"
  }
}

curl -X POST http://localhost:8080/sessions/01936f8a-7b2c-7000-8000-000000000001/messages \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "01936f8a-7b2c-7000-8000-000000000001",
    "prompt": "Now explain it in more detail"
  }'

{
  "name": "meerkat_resume",
  "arguments": {
    "session_id": "01936f8a-...",
    "prompt": "What's my name?"
  }
}

result = await session.turn("Now explain it in more detail")
print(result.text)

const result = await session.turn("Now explain it in more detail");
console.log(result.text);

let result = service.start_turn(&session_id, StartTurnRequest {
    prompt: "Now explain it in more detail".into(),
    injected_context: Vec::new(),
    system_prompt: None,
    event_tx: None,
    runtime: StartTurnRuntimeSemantics::default(),
}).await?;
println!("{}", result.text);

Attach host context without merging it into the prompt

Use injected_context for ambient facts that should be retained as separate, typed transcript messages immediately before the user’s message. These entries are visible in transcript reads but excluded from semantic-memory indexing. Use transient_turn_context instead when host-regenerated facts must apply to one provider request without entering the session transcript at all.

JSON-RPC
REST
Python
TypeScript

{
  "jsonrpc": "2.0", "id": 3,
  "method": "turn/start",
  "params": {
    "session_id": "01936f8a-...",
    "injected_context": [
      "Current incident severity: SEV-1",
      "On-call owner: payments-platform"
    ],
    "prompt": "Recommend the next action"
  }
}

curl -X POST http://localhost:8080/sessions/01936f8a-.../messages \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "01936f8a-...",
    "injected_context": ["Current incident severity: SEV-1"],
    "prompt": "Recommend the next action"
  }'

result = await session.turn(
    "Recommend the next action",
    injected_context=["Current incident severity: SEV-1"],
)

const result = await session.turn("Recommend the next action", {
  injectedContext: ["Current incident severity: SEV-1"],
});

Resume by ID or alias

CLI supports short prefix matching and relative aliases for resuming sessions.

# Full UUID
rkat run --resume 01936f8a-7b2c-7000-8000-000000000001 "Keep going"

# Short prefix (git-style, fails on ambiguity)
rkat run --resume 019c8b99 "Keep going"

# Most recent session
rkat run --resume last "Keep going"

# 2nd most recent
rkat run --resume ~1 "Go back to this one"

# Omitting the session value resumes `last`
rkat --resume "Keep going"

List sessions

rkat session list
rkat session list --limit 10
rkat session list --limit 10 --offset 20

{"jsonrpc": "2.0", "id": 3, "method": "session/list"}

curl http://localhost:8080/sessions

{"name": "meerkat_sessions", "arguments": {}}

sessions = await client.list_sessions()
for s in sessions:
    print(s.session_id, s.message_count, s.is_active)

const sessions = await client.listSessions();
for (const s of sessions) {
  console.log(s.sessionId, s.messageCount, s.isActive);
}

let sessions = service.list(SessionQuery::default()).await?;
for s in &sessions { println!("{}: {}", s.session_id, s.message_count); }

Read session state

rkat session show 01936f8a-...

{
  "jsonrpc": "2.0", "id": 4,
  "method": "session/read",
  "params": { "session_id": "01936f8a-..." }
}

curl http://localhost:8080/sessions/01936f8a-...

{"name": "meerkat_read", "arguments": {"session_id": "01936f8a-..."}}

state = await client.read_session("01936f8a-...")
print(state)

const state = await client.readSession("01936f8a-...");
console.log(state);

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

Audit and restore transcript revisions

Persistent sessions retain an append-only revision graph when their transcript head is rewritten. Revision reads and restores keep the same session identity. These mutations are available over JSON-RPC and the RPC-backed SDKs, not REST. The target must be idle; running_behavior: "reject" fails with SESSION_BUSY instead of racing active work.

JSON-RPC
Python
TypeScript

{
  "jsonrpc": "2.0", "id": 5,
  "method": "session/transcript_revisions",
  "params": { "session_id": "01936f8a-...", "offset": 0, "limit": 50 }
}

Read the active head with session/transcript_revision and "revision": "current". Restore a retained revision with:

{
  "jsonrpc": "2.0", "id": 6,
  "method": "session/restore_transcript_revision",
  "params": {
    "session_id": "01936f8a-...",
    "revision": "sha256:...",
    "reason": { "kind": "restore", "note": "Restore reviewed head" },
    "running_behavior": "reject"
  }
}

revisions = await client.list_session_transcript_revisions(session.id)
current = await client.read_session_transcript_revision(session.id, "current")

if revisions.entries:
    restored = await session.restore_transcript_revision(
        revisions.entries[0].revision,
        {"kind": "restore", "note": "Restore reviewed head"},
        expected_parent_revision=revisions.head_revision,
        running_behavior="reject",
    )

const revisions = await client.listSessionTranscriptRevisions(session.id);
const current = await client.readSessionTranscriptRevision(session.id, "current");

if (revisions.entries.length > 0) {
  const restored = await session.restoreTranscriptRevision(
    revisions.entries[0].revision,
    { kind: "restore", note: "Restore reviewed head" },
    {
      expectedParentRevision: revisions.headRevision,
      runningBehavior: "reject",
    },
  );
}

session/rewrite_transcript and the corresponding SDK methods commit typed message-range replacements. A rewrite cannot mint the runtime-owned compaction_summary role, while an existing injected_context role may be preserved.

Archive a session

rkat session delete 01936f8a-...

{
  "jsonrpc": "2.0", "id": 5,
  "method": "session/archive",
  "params": { "session_id": "01936f8a-..." }
}

curl -X DELETE http://localhost:8080/sessions/01936f8a-...

{"name": "meerkat_archive", "arguments": {"session_id": "01936f8a-..."}}

await session.archive()

await session.archive();

service.archive(&session_id).await?;

Interrupt a turn

Cancel an in-flight turn. Runtime-backed public interrupt handling returns a successful no-op for an existing idle session. This does not make missing or archived targets successful no-ops, and direct substrate calls differ.

rkat session interrupt 01936f8a-...

{
  "jsonrpc": "2.0", "id": 6,
  "method": "turn/interrupt",
  "params": { "session_id": "01936f8a-..." }
}

curl -X POST http://localhost:8080/sessions/01936f8a-.../interrupt

{"name": "meerkat_interrupt", "arguments": {"session_id": "01936f8a-..."}}

await session.interrupt()

await session.interrupt();

A directly constructed EphemeralSessionService returns SessionError::NotRunning when idle. This example propagates that result with ?; it does not normalize it to a successful no-op.

service.interrupt(&session_id).await?;

Event streaming

# Basic streaming
rkat run --stream "Tell me a story"

Events arrive as session/event notifications during a turn:

{
  "jsonrpc": "2.0",
  "method": "session/event",
  "params": {
    "session_id": "01936f8a-7b2c-7000-8000-000000000001",
    "event": {
      "event_id": "01936f8a-7b2c-7000-8000-000000000002",
      "source": {
        "type": "session",
        "session_id": "01936f8a-7b2c-7000-8000-000000000001"
      },
      "seq": 1,
      "timestamp_ms": 1732746900268,
      "payload": {
        "type": "text_delta",
        "delta": "The capital"
      }
    }
  }
}

The wire event is an EventEnvelope<AgentEvent>; the agent event lives at params.event.payload. The SDK stream helpers below expose decoded agent events instead.

# SSE stream (connect before starting a turn)
curl -N http://localhost:8080/sessions/01936f8a-.../events

Events arrive as Server-Sent Events with types like text_delta, tool_call_requested, turn_completed, and done.

{
  "name": "meerkat_run",
  "arguments": {
    "prompt": "Tell me a story",
    "stream": true
  }
}

When stream: true, this agent-event path sends MCP logging notifications (notifications/message), not notifications/progress. Each notification has params.level: "info" and a params.data object containing source: "meerkat", session_id, and event as an EventEnvelope<AgentEvent>. The actual agent event is at params.data.event.payload.For long-running or autonomous sessions, use the managed event stream tools instead:

// Open a stream
{"name": "meerkat_event_stream_open", "arguments": {"session_id": "01936f8a-..."}}
// => {"stream_id": "evt-..."}

// Poll for events (blocks until next event or timeout)
{"name": "meerkat_event_stream_read", "arguments": {"stream_id": "evt-..."}}

// Close when done
{"name": "meerkat_event_stream_close", "arguments": {"stream_id": "evt-..."}}

# Streaming on session create
async with client.create_session_streaming("Tell me a story") as stream:
    async for event in stream:
        match event:
            case TextDelta(delta=chunk):
                print(chunk, end="", flush=True)
    result = stream.result

# Streaming on a follow-up turn
async with session.stream("Continue the story") as events:
    async for event in events:
        match event:
            case TextDelta(delta=chunk):
                print(chunk, end="", flush=True)

// Streaming on session create
const stream = client.createSessionStreaming("Tell me a story");
for await (const event of stream) {
  if (event.type === "text_delta") {
    process.stdout.write(event.delta);
  }
}
const result = stream.result;

// Streaming on a follow-up turn
for await (const event of session.stream("Continue the story")) {
  if (event.type === "text_delta") {
    process.stdout.write(event.delta);
  }
}

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::TurnCompleted { usage: Some(usage), .. } => {
                // Per-call usage: `accounting` names the resolved model and
                // the normalized presented input for this one call.
                println!(
                    "\n[{}: {} tokens]",
                    usage.accounting().model,
                    usage.normalized_total_tokens()
                );
            }
            _ => {}
        }
    }
});

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

turn_completed carries usage for one provider call while run_completed and RunResult.usage carry the session-cumulative total, and their input_tokens fields use different denominators. Read Usage accounting before aggregating either.

Model and provider selection

rkat run --model gpt-5.5 --provider openai "Hello"
rkat run --model gemini-3.8-flash --provider gemini "Hello"
rkat run --model claude-opus-5 "Hello"

{
  "jsonrpc": "2.0", "id": 7,
  "method": "session/create",
  "params": {
    "prompt": "Hello",
    "model": "gpt-5.5",
    "provider": "openai",
    "provider_params": {
      "provider_tag": { "provider": "open_ai", "reasoning_effort": "high" }
    }
  }
}

curl -X POST http://localhost:8080/sessions \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Explain monads","model":"gpt-5.5","provider":"openai","provider_params":{"provider_tag":{"provider":"open_ai","reasoning_effort":"high"}}}'

{
  "prompt": "Hello",
  "model": "gpt-5.5",
  "provider": "openai"
}

Called via the meerkat_run tool.

session = await client.create_session(
    "Hello",
    model="gpt-5.5",
    provider="openai",
    provider_params={
        "provider_tag": {"provider": "open_ai", "reasoning_effort": "high"},
    },
)

const session = await client.createSession("Hello", {
  model: "gpt-5.5",
  provider: "openai",
  providerParams: {
    provider_tag: { provider: "open_ai", reasoning_effort: "high" },
  },
});

let result = service.create_session(CreateSessionRequest {
    model: "gpt-5.5".into(),
    prompt: "Explain monads".into(),
    injected_context: Vec::new(),
    system_prompt: SystemPromptOverride::Inherit,
    max_tokens: None,
    event_tx: None,
    initial_turn: InitialTurnPolicy::RunImmediately,
    deferred_prompt_policy: DeferredPromptPolicy::default(),
    build: Some(SessionBuildOptions {
        provider: Some(Provider::OpenAI),
        provider_params: Some(ProviderParamsOverride {
            provider_tag: Some(ProviderTag::OpenAi(OpenAiProviderTag {
                reasoning_effort: Some(ReasoningEffort::High),
                ..Default::default()
            })),
            ..Default::default()
        }),
        ..Default::default()
    }),
    labels: None,
}).await?;

Switch model on a running session

A follow-up turn may replace the active model and provider without changing the session identity. The persisted auth binding is re-resolved for the new model unless the surface explicitly supplies another binding.

rkat run --resume 01936f8a-... --model gpt-5.5 --provider openai \
  "Re-evaluate the answer with the OpenAI model"

{
  "jsonrpc": "2.0", "id": 8,
  "method": "turn/start",
  "params": {
    "session_id": "01936f8a-...",
    "prompt": "Re-evaluate the answer",
    "model": "gpt-5.5",
    "provider": "openai"
  }
}

curl -X POST http://localhost:8080/sessions/01936f8a-.../messages \
  -H "Content-Type: application/json" \
  -d '{
    "session_id":"01936f8a-...",
    "prompt":"Re-evaluate the answer",
    "model":"gpt-5.5",
    "provider":"openai"
  }'

{
  "session_id": "01936f8a-...",
  "prompt": "Re-evaluate the answer",
  "model": "gpt-5.5",
  "provider": "openai"
}

Called via the meerkat_resume tool.

result = await session.turn(
    "Re-evaluate the answer",
    model="gpt-5.5",
    provider="openai",
)

const result = await session.turn("Re-evaluate the answer", {
  model: "gpt-5.5",
  provider: "openai",
});

Config management

# Read config
rkat config get
rkat config get --format json --with-generation

# Replace config
rkat config set --json '{"agent": {"model": "gpt-5.5"}}'

# Merge-patch with optimistic concurrency
rkat config patch --json '{"limits": {"budget": 50000}}' --expected-generation 3

limits.budget sets the runtime total-token budget used at construction, distinct from the per-call output-token limit.

{"jsonrpc": "2.0", "id": 8, "method": "config/get"}

{
  "jsonrpc": "2.0", "id": 9,
  "method": "config/set",
  "params": {
    "config": {"agent": {"model": "gpt-5.5"}},
    "expected_generation": 3
  }
}

{
  "jsonrpc": "2.0", "id": 10,
  "method": "config/patch",
  "params": {
    "patch": {"agent": {"max_tokens_per_turn": 8192}},
    "expected_generation": 4
  }
}

# Read
curl http://localhost:8080/config

# Replace
curl -X PUT http://localhost:8080/config \
  -H "Content-Type: application/json" \
  -d '{"config": {"agent": {"model": "gpt-5.5"}}, "expected_generation": 3}'

# Merge-patch
curl -X PATCH http://localhost:8080/config \
  -H "Content-Type: application/json" \
  -d '{"patch": {"agent": {"max_tokens_per_turn": 8192}}, "expected_generation": 4}'

// Get config
{"name": "meerkat_config", "arguments": {"action": "get"}}

// Patch config
{"name": "meerkat_config", "arguments": {
  "action": "patch",
  "patch": {"agent": {"max_tokens_per_turn": 8192}}
}}

config = await client.get_config()
await client.set_config({"agent": {"model": "gpt-5.5"}}, expected_generation=3)
await client.patch_config({"agent": {"max_tokens_per_turn": 8192}}, expected_generation=4)

const config = await client.getConfig();
await client.setConfig({ agent: { model: "gpt-5.5" } }, { expectedGeneration: 3 });
await client.patchConfig({ agent: { max_tokens_per_turn: 8192 } }, { expectedGeneration: 4 });

Config-document keys use the schema’s snake_case. SDK wrapper options such as expectedGeneration remain camelCase.

let store: Arc<dyn ConfigStore> = Arc::new(FileConfigStore::new(config_path));
let runtime = ConfigRuntime::new(store, state_path);

let snapshot = runtime.get().await?;
println!("generation: {}", snapshot.generation);

// Replace with optimistic concurrency (generation CAS)
runtime.set(new_config, Some(snapshot.generation)).await?;

Realm selection

Realms scope sessions and config. Surfaces see the same state only when both the realm_id and resolved physical provider/root match. Realm is set at startup for server surfaces (RPC, REST, MCP) and per-command or per-connection for CLI and SDKs.

Without an explicit override, the CLI derives a stable workspace realm from the context root (normally the current directory) and stores it under the project-local .rkat/realms root. RPC, REST, MCP, and SDK connections create a new opaque realm unless the caller supplies one.

rkat --state-root /data/meerkat --realm team-alpha run "Plan release"
rkat --state-root /data/meerkat --realm team-alpha --instance worker-1 session list
rkat --state-root /data/meerkat --realm team-alpha --realm-backend sqlite run --resume last "Continue"

rkat-rpc --state-root /data/meerkat --realm team-alpha --realm-backend sqlite --instance worker-1

rkat-rest --state-root /data/meerkat --realm team-alpha --realm-backend sqlite --instance api-1

rkat-mcp --state-root /data/meerkat --realm team-alpha --realm-backend sqlite --instance mcp-1

await client.connect(
    realm_id="team-alpha",
    state_root="/data/meerkat",
    instance_id="worker-1",
)

await client.connect({
  realmId: "team-alpha",
  stateRoot: "/data/meerkat",
  instanceId: "worker-1",
});

Getting started

Concepts

Guides: Models And Hosting

Guides: Runtime Behavior

Guides: Orchestration

Examples: Foundations

Examples: Capabilities

Examples: Orchestration And Deployment

Examples: Sessions & streaming

Create a session

Multi-turn

Attach host context without merging it into the prompt

Resume by ID or alias

List sessions

Read session state

Audit and restore transcript revisions

Archive a session

Interrupt a turn

Event streaming

Model and provider selection

Switch model on a running session

Config management

Realm selection

Next step

​Create a session

​Multi-turn

​Attach host context without merging it into the prompt

​Resume by ID or alias

​List sessions

​Read session state

​Audit and restore transcript revisions

​Archive a session

​Interrupt a turn

​Event streaming

​Model and provider selection

​Switch model on a running session

​Config management

​Realm selection

​Next step

Create a session

Multi-turn

Attach host context without merging it into the prompt

Resume by ID or alias

List sessions

Read session state

Audit and restore transcript revisions

Archive a session

Interrupt a turn

Event streaming

Model and provider selection

Switch model on a running session

Config management

Realm selection

Next step