Comms & mobs

For the full guide, see Comms and the 0.5 mob orchestration architecture notes.

Keep-alive mode

Enable the comms listener so the agent stays alive after its initial prompt, waiting for incoming messages and external events as future runtime-backed turn work.

rkat run --comms-name agent-a --keep-alive "You are a coordinator."

{
  "jsonrpc": "2.0", "id": 1,
  "method": "session/create",
  "params": {
    "prompt": "You are a coordinator.",
    "keep_alive": true,
    "comms_name": "agent-a"
  }
}

curl -X POST http://localhost:8080/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "You are a coordinator.",
    "keep_alive": true,
    "comms_name": "agent-a"
  }'

{
  "prompt": "You are a coordinator.",
  "keep_alive": true,
  "comms_name": "agent-a"
}

Called via the meerkat_run tool.

session = await client.create_session(
    "You are a coordinator.",
    keep_alive=True,
    comms_name="agent-a",
)

const session = await client.createSession("You are a coordinator.", {
  keepAlive: true,
  commsName: "agent-a",
});

let result = service.create_session(CreateSessionRequest {
    model: "claude-sonnet-4-5".into(),
    prompt: "You are a coordinator.".into(),
    system_prompt: None,
    max_tokens: None,
    render_metadata: None,
    event_tx: None,
    skill_references: None,
    initial_turn: InitialTurnPolicy::RunImmediately,
    build: Some(SessionBuildOptions {
        keep_alive: true,
        comms_name: Some("agent-a".into()),
        ..Default::default()
    }),
    labels: None,
}).await?;

Send a message

Push an event into a running session’s comms inbox.

{
  "jsonrpc": "2.0", "id": 2,
  "method": "comms/send",
  "params": {
    "session_id": "01936f8a-...",
    "payload": {"alert": "build failed", "severity": "high"},
    "source": "ci-pipeline"
  }
}

curl -X POST http://localhost:8080/comms/send \
  -H "Content-Type: application/json" \
  -d '{"session_id":"01936f8a-...","payload":{"alert":"build failed"},"source":"ci-pipeline"}'

{"name": "meerkat_comms_send", "arguments": {
  "session_id": "01936f8a-...",
  "kind": "peer_message",
  "to": "agent-b",
  "body": "Hello from agent-a"
}}

session = await client.create_session("...", keep_alive=True, comms_name="agent-a")
await session.send(payload={"alert": "build failed"}, source="ci-pipeline")

const session = await client.createSession("...", { keepAlive: true, commsName: "agent-a" });
await session.send({ payload: { alert: "build failed" }, source: "ci-pipeline" });

let injector = service.event_injector(&session_id).await
    .expect("comms must be enabled");
injector.inject(r#"{"alert": "build failed"}"#.into(), PlainEventSource::Rpc)?;

List peers

Discover trusted peers visible to a running session.

{
  "jsonrpc": "2.0", "id": 3,
  "method": "comms/peers",
  "params": { "session_id": "01936f8a-..." }
}

curl http://localhost:8080/comms/peers?session_id=01936f8a-...

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

peers = await session.peers()
for p in peers:
    print(f"{p['name']} @ {p['address']}")

const peers = await session.peers();
peers.forEach(p => console.log(`${p.name} @ ${p.address}`));

let runtime = service.comms_runtime(&session_id).await
    .expect("comms must be enabled");
let peers = runtime.peers().await;
for p in &peers { println!("{} @ {}", p.name, p.address); }

External event injection

Push external events from outside systems into a running agent. Events are queued as runtime-backed external inputs and admitted as future turn work.

# Keep-alive with stdin events (pipe or type interactively)
rkat run --comms-name monitor --keep-alive --stdin \
  "You are a monitoring agent."

{
  "jsonrpc": "2.0", "id": 4,
  "method": "comms/send",
  "params": {
    "session_id": "01936f8a-...",
    "payload": {"event": "deploy_complete", "env": "prod"},
    "source": "deploy-bot"
  }
}

curl -X POST http://localhost:8080/comms/send \
  -H "Content-Type: application/json" \
  -d '{"session_id":"01936f8a-...","payload":{"event":"deploy_complete","env":"prod"},"source":"deploy-bot"}'

{"name": "meerkat_comms_send", "arguments": {
  "session_id": "01936f8a-...",
  "kind": "event",
  "body": "{\"event\":\"deploy_complete\",\"env\":\"prod\"}"
}}

await session.send(payload={"event": "deploy_complete", "env": "prod"}, source="deploy-bot")

await session.send({ payload: { event: "deploy_complete", env: "prod" }, source: "deploy-bot" });

let injector = service.event_injector(&session_id).await
    .expect("comms must be enabled");

injector.inject(
    r#"{"event": "deploy_complete"}"#.into(),
    PlainEventSource::Rpc,
)?;

Delegate through mobs

In 0.5, delegated and multi-agent work routes through mobs rather than a standalone helper-agent tool family. Use mob member refs, flow runs, and peer messaging to coordinate temporary discussion groups or longer-lived orchestration topologies.

Getting started

Core concepts

Guides

Examples

Keep-alive mode

Send a message

List peers

External event injection

Delegate through mobs

Getting started

Core concepts

Guides

Examples

​Keep-alive mode

​Send a message

​List peers

​External event injection

​Delegate through mobs

Keep-alive mode

Send a message

List peers

External event injection

Delegate through mobs