Mobs - Meerkat

For the full guide, see Mobs.

There are two different mob surfaces:

Host APIs: typed mob/* methods over JSON-RPC and the SDK-backed Mob classes
Agent-side tools: mob_* tools exposed inside a running agent session

This page focuses on the host control plane. It does not treat agent-side mob_* tools as if they were the public RPC/SDK API.

Create a mob

JSON-RPC
Python
TypeScript
Rust

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "mob/create",
  "params": {
    "definition": {
      "id": "release-triage",
      "profiles": {
        "lead": {
          "model": "claude-opus-4-8",
          "peer_description": "Coordinates triage"
        },
        "analyst": {
          "model": "claude-sonnet-4-6",
          "peer_description": "Investigates issues"
        }
      },
      "flows": {
        "triage": {
          "steps": {
            "scan": { "role": "lead", "message": "Prioritize incoming issues." }
          }
        }
      }
    }
  }
}

mob = await client.create_mob(
    definition={
        "id": "release-triage",
        "profiles": {
            "lead": {
                "model": "claude-opus-4-8",
                "peer_description": "Coordinates triage",
            },
            "analyst": {
                "model": "claude-sonnet-4-6",
                "peer_description": "Investigates issues",
            },
        },
    }
)
print(mob.id)

const mob = await client.createMob({
  definition: {
    id: "release-triage",
    profiles: {
      lead: {
        model: "claude-opus-4-8",
        peer_description: "Coordinates triage",
      },
      analyst: {
        model: "claude-sonnet-4-6",
        peer_description: "Investigates issues",
      },
    },
  },
});
console.log(mob.mobId);

let definition: MobDefinition = serde_json::from_value(json!({
    "id": "release-triage",
    "profiles": {
        "lead": { "model": "claude-opus-4-8" },
        "analyst": { "model": "claude-sonnet-4-6" }
    }
}))?;

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

Spawn members

CLI
JSON-RPC
Python
TypeScript
Rust

The CLI exposes helper, callable-run, and run-resource commands such as spawn-helper, fork-helper, run, runs, status, logs, attach, run-flow, member-status, respawn, and wait-kickoff. It does not expose the raw host-side mob/spawn lifecycle directly.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "mob/spawn",
  "params": {
    "mob_id": "release-triage",
    "profile": "lead",
    "agent_identity": "lead-1"
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "mob/spawn_many",
  "params": {
    "mob_id": "release-triage",
    "specs": [
      { "profile": "analyst", "agent_identity": "analyst-1" },
      { "profile": "analyst", "agent_identity": "analyst-2", "runtime_mode": "turn_driven" }
    ]
  }
}

await mob.spawn(profile="lead", agent_identity="lead-1")
await mob.spawn_many([
    {"profile": "analyst", "agent_identity": "analyst-1"},
    {"profile": "analyst", "agent_identity": "analyst-2", "runtime_mode": "turn_driven"},
])

await mob.spawn({ profile: "lead", agentIdentity: "lead-1" });
await mob.spawnMany([
  { profile: "analyst", agentIdentity: "analyst-1" },
  { profile: "analyst", agentIdentity: "analyst-2", runtimeMode: "turn_driven" },
]);

handle
    .spawn_spec(SpawnMemberSpec::new("lead", AgentIdentity::from("lead-1")))
    .await?;

let mut analyst = SpawnMemberSpec::new("analyst", AgentIdentity::from("analyst-2"));
analyst.runtime_mode = Some(MobRuntimeMode::TurnDriven);
handle.spawn_spec(analyst).await?;

Wire and unwire peers

JSON-RPC
Python
TypeScript
Rust

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "mob/wire",
  "params": {
    "mob_id": "release-triage",
    "agent_identity": "lead-1",
    "peer": "analyst-1"
  }
}

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "mob/unwire",
  "params": {
    "mob_id": "release-triage",
    "agent_identity": "lead-1",
    "peer": "analyst-1"
  }
}

await mob.wire("lead-1", "analyst-1")
await mob.unwire("lead-1", "analyst-1")

await mob.wire("lead-1", "analyst-1");
await mob.unwire("lead-1", "analyst-1");

handle
    .wire(AgentIdentity::from("lead-1"), AgentIdentity::from("analyst-1"))
    .await?;
handle
    .unwire(AgentIdentity::from("lead-1"), AgentIdentity::from("analyst-1"))
    .await?;

Send work to a member

Use the host control plane when an application needs to deliver content directly to a member session.

JSON-RPC
Python
TypeScript

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "mob/member_send",
  "params": {
    "mob_id": "release-triage",
    "agent_identity": "lead-1",
    "content": "Decompose the task and assign work to the analysts.",
    "handling_mode": "queue"
  }
}

lead = mob.member("lead-1")
await lead.send(
    "Decompose the task and assign work to the analysts.",
    handling_mode="queue",
)

const lead = mob.member("lead-1");
await lead.send(
  "Decompose the task and assign work to the analysts.",
  { handlingMode: "queue" },
);

Submit tracked work

Use the work lane when you need a cancellable work reference rather than plain content delivery. The work lane uses the opaque member_ref returned by spawn, member list, or member send responses.

JSON-RPC
Python
TypeScript

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "mob/submit_work",
  "params": {
    "member_ref": "member_ref_from_spawn_or_members",
    "content": "Review the flaky test history and summarize the top failure modes.",
    "origin": "external"
  }
}

members = await mob.members()
lead_ref = next(m["member_ref"] for m in members if m["agent_identity"] == "lead-1")

work = await client.mob_submit_work(
    lead_ref,
    "Review the flaky test history and summarize the top failure modes.",
)

const lead = (await mob.listMembers()).find(
  (member) => member.agentIdentity === "lead-1",
);
if (!lead) throw new Error("lead-1 is not spawned");

const work = await client.mobSubmitWork({
  memberRef: lead.memberRef,
  content: "Review the flaky test history and summarize the top failure modes.",
});

Run a flow

CLI
JSON-RPC
Python
TypeScript
Rust

rkat mob run release-triage --flow triage --param severity='"high"'
rkat mob runs release-triage
rkat mob run-flow release-triage --flow triage --stream

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "mob/flow_run",
  "params": {
    "mob_id": "release-triage",
    "flow_id": "triage",
    "params": { "severity": "high" }
  }
}

run_id = await mob.run_flow("triage", {"severity": "high"})
status = await mob.flow_status(run_id)
result = await mob.run_result(run_id)

const runId = await mob.runFlow("triage", { severity: "high" });
const status = await mob.flowStatus(runId);

let run_id = handle.run_flow("triage".into(), json!({"severity": "high"})).await?;
let status = handle.flow_status(run_id).await?;
let runs = handle.list_runs(None).await?;

Helper-oriented CLI flows

The current CLI is strongest for helper-style workflows on an existing mob:

rkat mob spawn-helper release-triage "Join as lead-1 and summarize the release status." --profile lead --agent-identity lead-1
rkat mob fork-helper release-triage lead-1 "Investigate the flaky test history." --profile analyst --agent-identity analyst-2
rkat mob member-status release-triage lead-1 --json
rkat mob respawn release-triage analyst-2 --initial-message "Resume with a fresh runtime."
rkat mob wait-kickoff release-triage --json

Events and subscriptions

events = await mob.subscribe_member_events("lead-1")
async for event in events:
    print(event)

const events = await mob.subscribeMemberEvents("lead-1");
for await (const event of events) {
  console.log(event);
}

​Create a mob

​Spawn members

​Wire and unwire peers

​Send work to a member

​Submit tracked work

​Run a flow

​Helper-oriented CLI flows

​Events and subscriptions

​See also