Mobs Examples

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",
          "tools": { "comms": true },
          "external_addressable": true
        },
        "analyst": {
          "model": "claude-sonnet-4-6",
          "peer_description": "Investigates issues",
          "tools": { "comms": true }
        }
      },
      "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",
                "tools": {"comms": True},
                "external_addressable": True,
            },
            "analyst": {
                "model": "claude-sonnet-4-6",
                "peer_description": "Investigates issues",
                "tools": {"comms": True},
            },
        },
        "flows": {
            "triage": {
                "steps": {
                    "scan": {"role": "lead", "message": "Prioritize incoming issues."}
                }
            }
        },
    }
)
print(mob.id)

const mob = await client.createMob({
  definition: {
    id: "release-triage",
    profiles: {
      lead: {
        model: "claude-opus-4-8",
        peer_description: "Coordinates triage",
        tools: { comms: true },
        external_addressable: true,
      },
      analyst: {
        model: "claude-sonnet-4-6",
        peer_description: "Investigates issues",
        tools: { comms: true },
      },
    },
    flows: {
      triage: {
        steps: {
          scan: { role: "lead", message: "Prioritize incoming issues." },
        },
      },
    },
  },
});
console.log(mob.mobId);

let definition: MobDefinition = serde_json::from_value(json!({
    "id": "release-triage",
    "profiles": {
        "lead": {
            "model": "claude-opus-4-8",
            "tools": { "comms": true },
            "external_addressable": true
        },
        "analyst": {
            "model": "claude-sonnet-4-6",
            "tools": { "comms": true }
        }
    },
    "flows": {
        "triage": {
            "steps": {
                "scan": { "role": "lead", "message": "Prioritize incoming issues." }
            }
        }
    }
}))?;

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?;

Place a member on a bound host

Run the member-host daemon in its own restart-stable realm. Keep this process running:

rkat --realm worker-west-host mob host \
  --listen-tcp 0.0.0.0:4300 \
  --advertise-tcp tcp://worker-west.example.com:4300 \
  --allow-remote \
  --descriptor-out ./worker-west.host.json

Bind its mode-0600 descriptor to the mob from the controlling host, then use the reported host id as placement:

rkat --realm team-alpha mob bind-host release-triage \
  --descriptor ./worker-west.host.json
rkat --realm team-alpha mob hosts release-triage --json

{
  "jsonrpc": "2.0",
  "id": 30,
  "method": "mob/spawn",
  "params": {
    "mob_id": "release-triage",
    "profile": "analyst",
    "agent_identity": "west-analyst-1",
    "placement": "host-id-from-bind-report"
  }
}

Read host reachability, route convergence, and the member’s owning-host history through the controller:

rkat --realm team-alpha mob hosts release-triage --json
rkat --realm team-alpha mob route-installs release-triage
rkat --realm team-alpha mob member-history release-triage west-analyst-1

REST and public MCP expose those three observations but not host binding, grants, member live control, or hard cancel. Python and TypeScript SDKs wrap the full JSON-RPC family. Trusted in-process MobHandle callers also expose hard cancel. Browser mobs stay single-host.

Do not use a placed member’s session id with the controller’s generic session/* methods. The session belongs to the member host’s realm. Use identity-routed mob operations and mob/member_history; remote transcript revision and edit methods are not bridged in v1.

The placed profile must also be portable. Remote admission rejects Rust bundles, external tool dispatchers, WorkGraph tools, host-only MCP allow-lists, inherited tool filters, in-process compaction curators, and secret-bearing shell or MCP environment/header values. Placement cannot be combined with an explicit backend or runtime binding. Admission also rejects a member whose required capabilities are absent on the bound host.

Resume a durable member under a new role

Role migration is a trusted Rust-host operation. It preserves the exact mob, member identity, session, and transcript while declaring the exact predecessor role for one cold Resume request:

let spec = SpawnMemberSpec::new(
    "home-automation",
    AgentIdentity::from("home-automation-1"),
)
.with_resume_bridge_session_id_from_role(session_id, "domain");

handle.spawn_spec(spec).await?;

Use a SpawnMemberCustomizer with ctx.spawn_source == SpawnSource::Resume and spec.declare_resume_from_role("domain")? when cold restore reconstructs the spec after a process restart. The runtime rejects a missing or incorrect predecessor declaration and refuses migration while the exact session is live, even if that actor is idle.

Do not add resume_from_role to JSON-RPC, REST, MCP, SDK, CLI, Web, or agent-tool spawn payloads. It exists only on trusted in-process specs and the private member-host materialization wire.

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. mob/member_send and SDK Member.send require the target’s profile to set external_addressable: true; omission means false. The creation examples opt in the lead only. Internal flow dispatch and ordinary peer messaging do not require this external-entry opt-in.

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. Externally originated work also requires external_addressable: true on the selected member’s profile; use lead-1’s member_ref for these examples.

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: Assume ordinary members lead-1 and analyst-2 have already been spawned as above. Keep lead-1 live as the fork source, and give each temporary helper a fresh identity distinct from those persistent members.

rkat mob spawn-helper release-triage "Summarize the release status." --profile lead --agent-identity release-summary-helper --result-label release-summary --max-text-bytes 4096
rkat mob fork-helper release-triage lead-1 "Investigate the flaky test history." --profile analyst --agent-identity flaky-review-helper --result-label flaky-test-review --max-text-bytes 4096
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

Both helper commands run one bounded task, capture its result, and attempt retirement. Successful cleanup removes the helper from the active roster; retirement_error reports cleanup debt without erasing the committed result. Do not rely on a completed one-shot helper remaining live as a later fork source. The status and respawn commands above address the ordinary members, not the temporary helpers.

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);
}

Getting started

Concepts

Guides: Models And Hosting

Guides: Runtime Behavior

Guides: Orchestration

Examples: Foundations

Examples: Capabilities

Examples: Orchestration And Deployment

Create a mob

Spawn members

Place a member on a bound host

Resume a durable member under a new role

Wire and unwire peers

Send work to a member

Submit tracked work

Run a flow

Helper-oriented CLI flows

Events and subscriptions

See also

​Create a mob

​Spawn members

​Place a member on a bound host

​Resume a durable member under a new role

​Wire and unwire peers

​Send work to a member

​Submit tracked work

​Run a flow

​Helper-oriented CLI flows

​Events and subscriptions

​See also

Create a mob

Spawn members

Place a member on a bound host

Resume a durable member under a new role

Wire and unwire peers

Send work to a member

Submit tracked work

Run a flow

Helper-oriented CLI flows

Events and subscriptions

See also