Comms & external events

For the full guide, see 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.

CLI
JSON-RPC
REST
Python
TypeScript

rkat run --comms-name agent-a --keep-alive "You are a coordinator."

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/create",
  "params": {
    "prompt": "You are a coordinator.",
    "keep_alive": true,
    "comms_name": "agent-a"
  }
}

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"
  }'

session = await client.create_session(
    "You are a coordinator.",
    keep_alive=True,
    comms_name="agent-a",
)

const session = await client.createSession("You are a coordinator.", {
  keepAlive: true,
  commsName: "agent-a",
});

Listen as a remote signed peer

Use the rkat run comms flags when the agent process itself should be reachable by other Meerkats or by a mob supervisor:

rkat run \
  --comms-name remote-reviewer \
  --comms-listen-tcp 0.0.0.0:4200 \
  --comms-advertise-tcp reviewer.example.com:4200 \
  --comms-binding-out ./remote-reviewer.binding.json \
  --keep-alive \
  "You review work sent over signed comms."

This is different from rkat-rpc --tcp, which exposes JSON-RPC for hosts and SDKs rather than the signed peer channel.

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. The to field is the canonical peer ID (from comms/peers), not a display name.

JSON-RPC
REST
MCP
Python
TypeScript

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "comms/send",
  "params": {
    "session_id": "01936f8a-...",
    "kind": "peer_message",
    "to": "0193a1b2-...",
    "body": "Build failed in CI. Please investigate.",
    "handling_mode": "queue"
  }
}

curl -X POST http://localhost:8080/comms/send \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "01936f8a-...",
    "kind": "peer_message",
    "to": "0193a1b2-...",
    "body": "Build failed in CI. Please investigate.",
    "handling_mode": "queue"
  }'

{
  "name": "meerkat_comms_send",
  "arguments": {
    "session_id": "01936f8a-...",
    "kind": "peer_message",
    "to": "0193a1b2-...",
    "body": "Build failed in CI. Please investigate.",
    "handling_mode": "queue"
  }
}

receipt = await session.send(
    kind="peer_message",
    to="0193a1b2-...",
    body="Build failed in CI. Please investigate.",
    handling_mode="queue",
)
print(receipt)

const receipt = await session.send({
  kind: "peer_message",
  to: "0193a1b2-...",
  body: "Build failed in CI. Please investigate.",
  handling_mode: "queue",
});
console.log(receipt);

List discoverable peers

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

JSON-RPC
REST
MCP
Python
TypeScript

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "comms/peers",
  "params": {
    "session_id": "01936f8a-..."
  }
}

curl "http://localhost:8080/comms/peers?session_id=01936f8a-..."

{
  "name": "meerkat_comms_peers",
  "arguments": {
    "session_id": "01936f8a-..."
  }
}

peers = await session.peers()
for peer in peers:
    print(peer["name"])

const peers = await session.peers();
peers.forEach((peer) => console.log(peer.name));

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.

JSON-RPC
REST
Python
TypeScript

{
  "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"
    }
  }
}

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"
    }
  }'

await session.send_external_event(
    "deploy_complete",
    {
        "environment": "prod",
        "release": "2026.04.21",
    },
)

await session.sendExternalEvent("deploy_complete", {
  environment: "prod",
  release: "2026.04.21",
});

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

Getting started

Concepts

Guides: Models And Hosting

Guides: Runtime Behavior

Guides: Orchestration

Examples: Foundations

Examples: Capabilities

Examples: Orchestration And Deployment

Comms & external events

Keep a session alive for inbound work

Listen as a remote signed peer

Send a typed comms command

List discoverable peers

Inject a durable external event

Next step

​Keep a session alive for inbound work

​Listen as a remote signed peer

​Send a typed comms command

​List discoverable peers

​Inject a durable external event

​Next step

Keep a session alive for inbound work

Listen as a remote signed peer

Send a typed comms command

List discoverable peers

Inject a durable external event

Next step