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

# Comms & external events

> Keep-alive sessions, typed comms commands, peer discovery, and durable external event ingress.

For the full guide, see [Comms](/guides/comms).

## Keep a session alive for inbound work

Keep-alive sessions stay resident so later comms or external events can wake them up as future runtime-backed work.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    rkat run --comms-name agent-a --keep-alive "You are a coordinator."
    ```
  </Tab>

  <Tab title="JSON-RPC">
    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "id": 1,
      "method": "session/create",
      "params": {
        "prompt": "You are a coordinator.",
        "keep_alive": true,
        "comms_name": "agent-a"
      }
    }
    ```
  </Tab>

  <Tab title="REST">
    ```bash theme={null}
    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"
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    session = await client.create_session(
        "You are a coordinator.",
        keep_alive=True,
        comms_name="agent-a",
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const session = await client.createSession("You are a coordinator.", {
      keepAlive: true,
      commsName: "agent-a",
    });
    ```
  </Tab>
</Tabs>

## Send a typed comms command

`comms/send` is the typed host-side comms surface. Use it for local input, peer messages, peer lifecycle notifications, peer requests, and peer responses.

<Tabs>
  <Tab title="JSON-RPC">
    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "id": 2,
      "method": "comms/send",
      "params": {
        "session_id": "01936f8a-...",
        "kind": "peer_message",
        "to": "agent-b",
        "body": "Build failed in CI. Please investigate.",
        "handling_mode": "queue"
      }
    }
    ```
  </Tab>

  <Tab title="REST">
    ```bash theme={null}
    curl -X POST http://localhost:8080/comms/send \
      -H "Content-Type: application/json" \
      -d '{
        "session_id": "01936f8a-...",
        "kind": "peer_message",
        "to": "agent-b",
        "body": "Build failed in CI. Please investigate.",
        "handling_mode": "queue"
      }'
    ```
  </Tab>

  <Tab title="MCP">
    ```json theme={null}
    {
      "name": "meerkat_comms_send",
      "arguments": {
        "session_id": "01936f8a-...",
        "kind": "peer_message",
        "to": "agent-b",
        "body": "Build failed in CI. Please investigate.",
        "handling_mode": "queue"
      }
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    receipt = await session.send({
        "kind": "peer_message",
        "to": "agent-b",
        "body": "Build failed in CI. Please investigate.",
        "handling_mode": "queue",
    })
    print(receipt)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const receipt = await session.send({
      kind: "peer_message",
      to: "agent-b",
      body: "Build failed in CI. Please investigate.",
      handling_mode: "queue",
    });
    console.log(receipt);
    ```
  </Tab>
</Tabs>

## List discoverable peers

Use `comms/peers` to see which trusted peers are currently visible to the session runtime.

<Tabs>
  <Tab title="JSON-RPC">
    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "id": 3,
      "method": "comms/peers",
      "params": {
        "session_id": "01936f8a-..."
      }
    }
    ```
  </Tab>

  <Tab title="REST">
    ```bash theme={null}
    curl "http://localhost:8080/comms/peers?session_id=01936f8a-..."
    ```
  </Tab>

  <Tab title="MCP">
    ```json theme={null}
    {
      "name": "meerkat_comms_peers",
      "arguments": {
        "session_id": "01936f8a-..."
      }
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    peers = await session.peers()
    for peer in peers:
        print(peer["name"])
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const peers = await session.peers();
    peers.forEach((peer) => console.log(peer.name));
    ```
  </Tab>
</Tabs>

## Inject a durable external event

Use `session/external_event` when the event should enter the runtime's external-ingress lane rather than the comms command lane.

<Tabs>
  <Tab title="JSON-RPC">
    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "id": 4,
      "method": "session/external_event",
      "params": {
        "session_id": "01936f8a-...",
        "kind": "generic_json",
        "event_type": "deploy_complete",
        "payload": {
          "environment": "prod",
          "release": "2026.04.21"
        }
      }
    }
    ```
  </Tab>

  <Tab title="REST">
    ```bash theme={null}
    curl -X POST http://localhost:8080/sessions/01936f8a-.../external-events \
      -H "Content-Type: application/json" \
      -d '{
        "kind": "generic_json",
        "event_type": "deploy_complete",
        "payload": {
          "environment": "prod",
          "release": "2026.04.21"
        }
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    await session.send_external_event(
        "deploy_complete",
        {
            "environment": "prod",
            "release": "2026.04.21",
        },
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    await session.sendExternalEvent("deploy_complete", {
      environment: "prod",
      release: "2026.04.21",
    });
    ```
  </Tab>
</Tabs>

<Note>
  Use `comms/send` for typed inbox and peer communication. Use `session/external_event` when an outside system is appending durable runtime-backed work.
</Note>

## Next step

* [Examples: Mobs](/examples/mobs)
* [Examples: WASM](/examples/wasm)