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.

Reply from inside an agent turn

The agent-facing tools are separate from the host APIs below. When a peer message caused the current turn, use the pre-addressed reply_to_peer tool:

{
  "name": "reply_to_peer",
  "arguments": {
    "body": "I reproduced the failure and attached the minimal trace.",
    "handling_mode": "queue"
  }
}

There is no peer_id input. The runtime mints a reply capability for the incoming delivery and revalidates trust when the reply is sent. If several peer messages were admitted in the same turn, the first call returns ambiguous_reply with delivery IDs; retry with one of them:

{
  "name": "reply_to_peer",
  "arguments": {
    "reply_to": "delivery-id-from-ambiguous-reply",
    "body": "This result is for your review request.",
    "handling_mode": "queue"
  }
}

For unsolicited outreach, discover a canonical identity with peers, then use send_message. Use send_response only when answering a typed send_request, not as a general reply tool.

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

If REST cannot prove the terminal delivery outcome, it returns typed send_ambiguous details instead of send_failed:

{
  "code": "send_ambiguous",
  "envelope_id": "0193a1b2-...",
  "retry_safe": false,
  "required_action": "reconcile"
}

Reconcile that envelope against durable work truth before creating another attempt. A new envelope id is new peer work; only a higher-level durable idempotency key that is coarser than the retry can make a replay collapse.

Declare outbound content taint

Host-side peer sends can inherit the runtime declaration, declare a value for one send, or explicitly send no declaration. This example affirmatively marks the content as tainted:

{
  "jsonrpc": "2.0",
  "id": 20,
  "method": "comms/send",
  "params": {
    "session_id": "01936f8a-...",
    "kind": "peer_message",
    "to": "0193a1b2-...",
    "body": "This summary contains unvetted external web content.",
    "content_taint": {"declare": "tainted"},
    "handling_mode": "queue"
  }
}

Omit content_taint to inherit. Set it to "undeclared" to suppress a runtime-level declaration for that send. Agent-facing tools do not expose this override; they inherit the host-owned runtime declaration.

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

Reply from inside an agent turn

Send a typed comms command

Declare outbound content taint

List discoverable peers

Inject a durable external event

Next step

​Keep a session alive for inbound work

​Listen as a remote signed peer

​Reply from inside an agent turn

​Send a typed comms command

​Declare outbound content taint

​List discoverable peers

​Inject a durable external event

​Next step

Keep a session alive for inbound work

Listen as a remote signed peer

Reply from inside an agent turn

Send a typed comms command

Declare outbound content taint

List discoverable peers

Inject a durable external event

Next step