Inter-agent communication

​

What this guide is for

• long-lived keep-alive sessions
• peer-to-peer agent messaging
• host-side external event ingress
• a practical operational understanding of the comms system

​

Overview

• Five LLM-facing tools: send_message, reply_to_peer, send_request, send_response, and peers
• Three transport layers: Unix Domain Sockets (UDS), TCP, and in-process (inproc)
• Ed25519 cryptographic identity: Every agent has a keypair; all messages are signed
• Trust-based peer model: Agents only accept messages from explicitly trusted peers
• External event ingestion: Push plain-text events from stdin, webhooks, RPC, or TCP/UDS listeners
• Auth-optional mode: Signed listeners for agent-to-agent comms; separate plain listeners for external events when auth = "none"
• Keep-alive: A runtime-backed session processes its initial prompt, then remains alive waiting for future admitted work
• Runtime-backed queueing: Incoming messages and external events are queued once and admitted through runtime ingress

​

Architecture

​

Setup

​

Identity and cryptography

• Key generation: Keypair::generate() creates a new random keypair using OsRng.
• Key persistence: Keypair::save(dir) writes identity.key (mode 0600 on Unix) and identity.pub to disk. Keypair::load(dir) reads them back. Keypair::load_or_generate(dir) is the canonical entry point.
• Public key format: PubKey is a 32-byte Ed25519 public key. The canonical string format is ed25519:<base64> (standard Base64 with padding).
• Standalone default identity directory: <base-dir>/.rkat/identity/. Session-scoped factory builds use a durable per-session identity root instead.

pub struct Envelope {
    pub id: Uuid,       // Unique message ID
    pub from: PubKey,   // Sender's public key
    pub to: PubKey,     // Recipient's public key
    pub kind: MessageKind,
    pub sig: Signature,  // Ed25519 signature over canonical CBOR of [id, from, to, kind]
}

​

Peer identity and naming

​

Trust model

pub struct TrustEntry {
    pub peer_id: PeerId,      // Canonical routing identity (the store key)
    pub name: PeerName,       // Display-only slug; not unique across entries
    pub pubkey: PubKey,       // Ed25519 public key
    pub address: PeerAddress, // Typed address: "uds://...", "tcp://...", or "inproc://..."
    pub meta: PeerMeta,       // Friendly metadata for peer discovery (description, labels)
}

{
  "peers": [
    {
      "name": "coding-agent",
      "pubkey": "ed25519:KioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKio=",
      "addr": "tcp://192.168.1.50:4200"
    },
    {
      "name": "review-agent",
      "pubkey": "ed25519:AQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE=",
      "addr": "uds:///tmp/meerkat-review.sock"
    }
  ]
}

​

Trust enforcement

​

Transport layer

​

Address formats

​

Message types

#[serde(tag = "type", rename_all = "lowercase")]
pub enum MessageKind {
    Message {
        body: String,
        blocks: Option<Vec<ContentBlock>>,
        content_taint: Option<SenderContentTaint>,
        handling_mode: Option<HandlingMode>,
        objective_id: Option<ObjectiveId>,
    },
    #[serde(rename = "incarnation_fenced_message")]
    IncarnationFencedMessage {
        body: String,
        blocks: Option<Vec<ContentBlock>>,
        content_taint: Option<SenderContentTaint>,
        handling_mode: Option<HandlingMode>,
        objective_id: Option<ObjectiveId>,
        expected_recipient: PeerRecipientIncarnation,
    },
    Request {
        intent: String,
        params: JsonValue,
        blocks: Option<Vec<ContentBlock>>,
        reply_endpoint: Option<PeerAddress>,
        content_taint: Option<SenderContentTaint>,
        handling_mode: Option<HandlingMode>,
        objective_id: Option<ObjectiveId>,
    },
    Lifecycle { kind: PeerLifecycleKind, params: JsonValue },
    Response {
        in_reply_to: Uuid,
        status: Status,
        result: JsonValue,
        blocks: Option<Vec<ContentBlock>>,
        content_taint: Option<SenderContentTaint>,
        handling_mode: Option<HandlingMode>,
        objective_id: Option<ObjectiveId>,
    },
    Ack { in_reply_to: Uuid },
}

#[serde(rename_all = "lowercase")]
pub enum Status {
    Accepted,
    Completed,
    Failed,
}

​

ACK behavior

​

LLM-facing tools

{
  "peers": [
    {
      "peer_id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "review-agent",
      "address": {
        "transport": "tcp",
        "endpoint": "192.168.1.50:4200"
      },
      "source": "trusted",
      "sendable_kinds": ["peer_message", "peer_request", "peer_response"],
      "capabilities": {
        "version": 1,
        "extensions": {"review": true}
      },
      "meta": {
        "description": "Reviews pull requests",
        "labels": {"role": "reviewer"}
      }
    }
  ]
}

​

Tool availability

​

Request and response across turns

• A queue delivery (the default) that reaches a running target is staged for that target’s next run start. It becomes the next turn, never part of the current one. An idle keep-alive session or mob member wakes on a queued peer input by itself (the mob runtime owns the comms drain, including for turn_driven members), so a host nudge is only ever needed for sequencing, not for delivery.
• A terminal send_response (completed or failed) is appended as a durable notice and run as a new reaction turn of the requester. With handling_mode: "steer" it also preempts the requester’s current run at its next boundary, but it still starts a new run; a reply never lands inside the requester’s running turn. An accepted progress response is coalesced into the requester’s next run and does not wake an idle requester.
• Only send_message, reply_to_peer, and send_request with handling_mode: "steer" inject into a running turn, at the target’s next run checkpoint, and only while the target is mid-turn. Steer aimed at an idle target is normalised to queue and becomes an ordinary next turn.
• There is no agent-facing await-reply primitive. The wait tool was removed in 0.5.2 and send_request has no timeout. A hub that fans out asks and then wants to wait ends its turn; the replies arrive as later turns, and the hub reasons about them then.

​

Inbox

• Inbox::new_transport_only() creates transport plumbing without semantic peer-admission authority; its sender rejects semantic inbox items
• runtime peer/event ingress uses the classified queue with an installed machine handle and returns a typed admission outcome (Admitted or Dropped { reason }); inbox-full, closed-session, and untrusted-sender drops are explicit, never silent
• each consumer obtains an exact FIFO-head claim; durable-runtime input remains queued until the runtime commits a typed terminal receipt, while volatile-control input is removed only by an exact handoff
• queue snapshots, claim age, handoff counters, and delivery correlations are read-only diagnostics derived from the canonical queue; they cannot commit, release, or reconstruct admission authority

• queueing is transport/inbox work
• durable consumption is runtime-backed admission with an exact terminal receipt
• volatile consumption is an exact FIFO handoff to a control consumer and does not claim durable admission

​

Configuration

[comms]
mode = "inproc"                    # "inproc", "tcp", or "uds"
address = "0.0.0.0:4200"          # Required when mode = "tcp" or "uds"
auth = "none"                      # "none" (open) or "ed25519"
event_address = "127.0.0.1:4201"  # Plain-text event listener (requires auth = "none")

pub struct CoreCommsConfig {
    pub enabled: bool,
    pub name: String,                        // Default: "meerkat"
    pub inproc_namespace: Option<String>,    // Realm-scoped namespace for inproc isolation
    pub listen_uds: Option<PathBuf>,         // Signed agent-to-agent listener (UDS)
    pub listen_tcp: Option<SocketAddr>,      // Signed agent-to-agent listener (TCP)
    pub advertise_address: Option<String>,   // Address advertised to signed peers
    pub event_listen_tcp: Option<SocketAddr>, // Plain event listener (auth = Open only)
    pub event_listen_uds: Option<PathBuf>,   // Plain event listener (Unix, auth = Open only)
    pub identity_dir: PathBuf,               // Default: ".rkat/identity"
    pub trusted_peers_path: PathBuf,         // Persisted projection path, not startup authority
    pub ack_timeout_secs: u64,               // Default: 30
    pub max_message_bytes: u32,              // Default: 1,048,576
    pub auth: CommsAuthMode,
    pub require_peer_auth: bool,             // Default: true
    pub allow_external_unauthenticated: bool, // Default: false (non-loopback plain listeners)
    pub pairing_password: Option<String>,    // Runtime-only enrollment secret (never serialized)
}

​

CLI usage

​

Signed TCP remote peer

export RKAT_PAIRING_PASSWORD="$(openssl rand -base64 32)"

rkat run \
  --comms-name mdm-target-1 \
  --comms-listen-tcp 0.0.0.0:4200 \
  --comms-advertise-tcp target.example.com:4200 \
  --comms-pairing-password-env RKAT_PAIRING_PASSWORD \
  --comms-binding-out ./target-binding.json \
  --agent-description "Remote MDM target" \
  --agent-label site=gcp \
  --keep-alive \
  "You are the remote target. Stay available for signed peer work."

​

Peer metadata

# Agent with description and labels
rkat run --comms-name reviewer \
  --agent-description "Reviews pull requests for style issues" \
  --agent-label lang=rust \
  --agent-label team=infra \
  --keep-alive "You review code when asked."

use meerkat_core::PeerMeta;

let build_config = AgentBuildConfig {
    keep_alive: true,
    comms_name: Some("reviewer".to_string()),
    peer_meta: Some(PeerMeta::default()
        .with_description("Reviews pull requests for style issues")
        .with_label("lang", "rust")),
    ..AgentBuildConfig::new("claude-sonnet-4-6")
};

{
  "peers": [{
    "peer_id": "018f6b2a-...",
    "name": "reviewer",
    "address": {
      "transport": "inproc",
      "endpoint": "reviewer"
    },
    "source": "inproc",
    "sendable_kinds": ["peer_message", "peer_request", "peer_response"],
    "capabilities": {"version": 1, "extensions": {}},
    "meta": {
      "description": "Reviews pull requests for style issues",
      "labels": {"lang": "rust", "team": "infra"}
    }
  }]
}

​

Keep-alive mode

# Keep-alive with comms only
rkat run --comms-name orchestrator --keep-alive "You are a project coordinator."

# Keep-alive with stdin events
rkat run --comms-name monitor --keep-alive --stdin lines "You are a monitoring agent."

​

SDK / programmatic usage

use meerkat::build_comms_runtime_from_config;

let runtime =
    build_comms_runtime_from_config(&config, base_dir, "my-agent", peer_meta).await?;

use meerkat::compose_tools_with_comms;

let (tools_with_comms, usage_instructions) =
    compose_tools_with_comms(base_tools, tool_usage_instructions, comms_material)?;

let factory = AgentFactory::new(store_path)
    .project_root(project_root)
    .comms(true);

let build_config = AgentBuildConfig {
    model: "claude-sonnet-4-6".to_string(),
    keep_alive: true,
    comms_name: Some("my-agent".to_string()),
    peer_meta: Some(PeerMeta::default()
        .with_description("Coordinates peer agents")),
    ..AgentBuildConfig::new("claude-sonnet-4-6")
};

let agent = factory.build_agent(build_config, &config).await?;

// Standalone
let bootstrap = CommsBootstrap::from_config(config, base_dir);
let prepared = bootstrap.prepare().await?;

// Child runtime (inproc; generated wiring must install parent trust)
let bootstrap = CommsBootstrap::for_child_inproc(
    "child-agent".to_string(),
    ParentCommsContext {
        parent_name: "parent".to_string(),
        parent_pubkey: parent_pubkey_bytes,
        parent_addr: "inproc://parent".to_string(),
        comms_base_dir: base_dir,
        inproc_namespace: None,
    },
);
let prepared = bootstrap.prepare().await?;

​

Agent loop integration

​

Inbox consumption

1. CommsRuntime and the inbox own delivery
2. the active keep-alive/drain lifecycle path owns durable admission, while explicit control responders own volatile handoff
3. formatted message injection into the session is a projection of the durable lifecycle truth

​

Transcript and model projection

• Message: comms.kind = "message" plus peer identity and optional content blocks.
• Request: comms.kind = "request" plus peer identity, request id, intent, params payload, and response guidance in the model projection.
• Response: comms.kind = "response_terminal" or response_progress plus peer identity, request id, status, and payload.

​

Typed peer lifecycle notices

• mob.peer_added
• mob.peer_retired
• mob.peer_unwired
• mob.dismiss (supervisor-directed dismissal of a live executor)

• mob.kickoff_failed
• mob.kickoff_cancelled

• None (default): use runtime default (50)
• 0: never inline peer lifecycle updates
• -1: always inline
• >0: inline only when current peer count is less than or equal to the threshold
• < -1: invalid (rejected by mob definition validation; factory builds also reject)

​

External event ingestion

​

Event sources

​

CLI stdin events

# Keep-alive with structured stdin events
echo '{"body":"deployment failed on prod"}' | \
  rkat run "You are a monitoring agent." \
  --comms-name monitor \
  --keep-alive --stdin lines --line-format json \
  --tools safe

​

REST webhook

# Without auth (localhost only)
curl -X POST http://localhost:8080/sessions/sid_abc/external-events \
  -H "Content-Type: application/json" \
  -d '{"kind": "generic_json", "event_type": "alert", "payload": {"alert": "CPU spike", "host": "web-03"}}'

# With webhook secret
RKAT_WEBHOOK_SECRET=my-secret  # set on server
curl -X POST http://localhost:8080/sessions/sid_abc/external-events \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: my-secret" \
  -d '{"kind": "generic_json", "event_type": "alert", "payload": {"alert": "deployment failed"}}'

​

RPC session/external_event

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/external_event",
  "params": {
    "session_id": "sid_abc123",
    "kind": "generic_json",
    "event_type": "ci_alert",
    "payload": {"alert": "build failed"}
  }
}

​

TCP/UDS plain event listeners

[comms]
mode = "tcp"
address = "127.0.0.1:4200"         # Signed agent-to-agent listener
auth = "none"
event_address = "127.0.0.1:4201"   # Plain-text event listener

# Push events via netcat
echo '{"body":"hello from external system"}' | nc 127.0.0.1 4201

​

Event transcript format

• Stdin: source = "stdin"
• Webhook: source = "webhook"
• RPC: source = "rpc" with optional structured source metadata.
• TCP/UDS: source = "tcp" or source = "uds"

​

Delivery vs observation

use meerkat_core::{EventInjector, HandlingMode, PlainEventSource};

let injector = service.event_injector(&session_id).await
    .expect("comms must be enabled");

injector.inject(
    "review PR #42".into(),     // ContentInput
    PlainEventSource::Rpc,
    HandlingMode::Queue,
    None,                       // Option<RenderMetadata>
)?;

• session-scoped: use the session’s primary event_tx or session/stream_open (RPC) / Session.subscribe() (Web SDK) / session.subscribe_events() (Python SDK) / session.subscribeEvents() (TypeScript SDK)
• agent-scoped: use MobHandle::subscribe_agent_events(...) or mob/stream_open (RPC) / Member.subscribe() or Mob.subscribeMemberEvents(agentIdentity) (Web SDK) / mob.subscribe_member_events(agent_identity) (Python SDK) / mob.subscribeMemberEvents(agentIdentity) (TypeScript SDK)
• mob-scoped: use MobHandle::subscribe_mob_events(...) or mob/stream_open (RPC) / Mob.subscribeEvents() (Web SDK) / mob.subscribe_events() (Python SDK) / mob.subscribeEvents() (TypeScript SDK)

• The agent must be running in keep-alive mode if you expect inbox events to be drained promptly.
• Comms must be enabled. Without comms, event_injector() returns None.
• Observation subscriptions are independent of delivery — configure them separately.

​

Security

• All messages are signed with Ed25519 using canonical CBOR encoding
• Trust is explicit: only messages from peers in the live, machine-authorized TrustStore are accepted; the persisted JSON projection is not startup authority
• Misaddressed messages are dropped: the receiver verifies envelope.to matches its own public key
• Private keys are stored with restrictive permissions: identity.key is written with mode 0600 on Unix
• Secret bytes are zeroized: Keypair::from_secret() zeroizes the input after copying
• ACK validation: ACK signatures, sender, recipient, and in_reply_to ID are all verified
• Exact replay handling: durable runtime ingress deduplicates the same interaction identity instead of starting a second turn

​

See also

• Built-in tools reference - comms tool parameter details
• Configuration: comms - config file settings
• Examples: comms - keep-alive mode and messaging across surfaces