> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rkat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Mobs Examples

> Create mobs, spawn members, wire peers, send work, and run flows through the current host control plane.

For the full guide, see [Mobs](/guides/mobs).

<Note>
  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.
</Note>

## Create a mob

<Tabs>
  <Tab title="JSON-RPC">
    ```json theme={null}
    {
      "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." }
              }
            }
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    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);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    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?;
    ```
  </Tab>
</Tabs>

## Spawn members

<Tabs>
  <Tab title="CLI">
    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.
  </Tab>

  <Tab title="JSON-RPC">
    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "id": 2,
      "method": "mob/spawn",
      "params": {
        "mob_id": "release-triage",
        "profile": "lead",
        "agent_identity": "lead-1"
      }
    }
    ```

    ```json theme={null}
    {
      "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" }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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"},
    ])
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    await mob.spawn({ profile: "lead", agentIdentity: "lead-1" });
    await mob.spawnMany([
      { profile: "analyst", agentIdentity: "analyst-1" },
      { profile: "analyst", agentIdentity: "analyst-2", runtimeMode: "turn_driven" },
    ]);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    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?;
    ```
  </Tab>
</Tabs>

## Place a member on a bound host

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

```bash theme={null}
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`:

```bash theme={null}
rkat --realm team-alpha mob bind-host release-triage \
  --descriptor ./worker-west.host.json
rkat --realm team-alpha mob hosts release-triage --json
```

```json theme={null}
{
  "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:

```bash theme={null}
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
```

<Note>
  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.
</Note>

<Warning>
  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.
</Warning>

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:

```rust theme={null}
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.

<Warning>
  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.
</Warning>

## Wire and unwire peers

<Tabs>
  <Tab title="JSON-RPC">
    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "id": 4,
      "method": "mob/wire",
      "params": {
        "mob_id": "release-triage",
        "agent_identity": "lead-1",
        "peer": "analyst-1"
      }
    }
    ```

    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "id": 5,
      "method": "mob/unwire",
      "params": {
        "mob_id": "release-triage",
        "agent_identity": "lead-1",
        "peer": "analyst-1"
      }
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    await mob.wire("lead-1", "analyst-1")
    await mob.unwire("lead-1", "analyst-1")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    await mob.wire("lead-1", "analyst-1");
    await mob.unwire("lead-1", "analyst-1");
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    handle
        .wire(AgentIdentity::from("lead-1"), AgentIdentity::from("analyst-1"))
        .await?;
    handle
        .unwire(AgentIdentity::from("lead-1"), AgentIdentity::from("analyst-1"))
        .await?;
    ```
  </Tab>
</Tabs>

## 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.

<Tabs>
  <Tab title="JSON-RPC">
    ```json theme={null}
    {
      "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"
      }
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    lead = mob.member("lead-1")
    await lead.send(
        "Decompose the task and assign work to the analysts.",
        handling_mode="queue",
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const lead = mob.member("lead-1");
    await lead.send(
      "Decompose the task and assign work to the analysts.",
      { handlingMode: "queue" },
    );
    ```
  </Tab>
</Tabs>

## 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.

<Tabs>
  <Tab title="JSON-RPC">
    ```json theme={null}
    {
      "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"
      }
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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.",
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    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.",
    });
    ```
  </Tab>
</Tabs>

## Run a flow

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    rkat mob run release-triage --flow triage --param severity='"high"'
    rkat mob runs release-triage
    rkat mob run-flow release-triage --flow triage --stream
    ```
  </Tab>

  <Tab title="JSON-RPC">
    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "id": 7,
      "method": "mob/flow_run",
      "params": {
        "mob_id": "release-triage",
        "flow_id": "triage",
        "params": { "severity": "high" }
      }
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    run_id = await mob.run_flow("triage", {"severity": "high"})
    status = await mob.flow_status(run_id)
    result = await mob.run_result(run_id)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const runId = await mob.runFlow("triage", { severity: "high" });
    const status = await mob.flowStatus(runId);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    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?;
    ```
  </Tab>
</Tabs>

## 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.

```bash theme={null}
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

```python theme={null}
events = await mob.subscribe_member_events("lead-1")
async for event in events:
    print(event)
```

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

## See also

* [Mobs guide](/guides/mobs)
* [Live Channels guide](/guides/realtime)
* [Mobpack examples](/examples/mobpack)
* [WASM examples](/examples/wasm)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.