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

> 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-6",
              "peer_description": "Coordinates triage"
            },
            "analyst": {
              "model": "claude-sonnet-4-6",
              "peer_description": "Investigates issues"
            }
          },
          "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-6",
                    "peer_description": "Coordinates triage",
                },
                "analyst": {
                    "model": "claude-sonnet-4-6",
                    "peer_description": "Investigates 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-6",
            peer_description: "Coordinates triage",
          },
          analyst: {
            model: "claude-sonnet-4-6",
            peer_description: "Investigates issues",
          },
        },
      },
    });
    console.log(mob.mobId);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    let definition = MobDefinition::from_json(json!({
        "id": "release-triage",
        "profiles": {
            "lead": { "model": "claude-opus-4-6" },
            "analyst": { "model": "claude-sonnet-4-6" }
        }
    }))?;

    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 currently exposes helper-oriented mob commands such as `spawn-helper`, `fork-helper`, `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>

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

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

<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-flow release-triage --flow triage --params '{"severity":"high"}'
    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)
    ```
  </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?;
    ```
  </Tab>
</Tabs>

## Helper-oriented CLI flows

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

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

```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)