Inter-agent communication

​

Overview

• Two LLM-facing tools: send (with kind parameter for message/request/response), 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).
• Default identity directory: <runtime-root>/.rkat/identity/.

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]
}

​

Trust model

pub struct TrustedPeer {
    pub name: String,     // Human-readable name (used by tools)
    pub pubkey: PubKey,   // Ed25519 public key
    pub addr: String,     // 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 },
    Request { intent: String, params: JsonValue },
    Response { in_reply_to: Uuid, status: Status, result: JsonValue },
    Ack { in_reply_to: Uuid },
}

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

​

ACK behavior

​

LLM-facing tools

{
  "peers": [
    {
      "name": "review-agent",
      "peer_id": "ed25519:...",
      "address": "tcp://192.168.1.50:4200"
    }
  ]
}

​

Tool availability

​

Inbox

• InboxSender::send(item) enqueues an item and calls notify.notify_waiters()
• Inbox::try_drain() returns all currently available items without blocking
• Inbox::recv() blocks until a message is available

• queueing is transport/inbox work
• consumption is runtime-backed admission work

​

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>,
    pub listen_tcp: Option<SocketAddr>,
    pub identity_dir: PathBuf,               // Default: "<runtime-root>/.rkat/identity"
    pub trusted_peers_path: PathBuf,         // Default: "<runtime-root>/.rkat/trusted_peers.json"
    pub ack_timeout_secs: u64,               // Default: 30
    pub max_message_bytes: usize,            // Default: 1,048,576
}

​

CLI usage

​

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-5")
};

{
  "peers": [{
    "name": "reviewer",
    "peer_id": "ed25519:...",
    "address": "inproc://reviewer",
    "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 "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").await?;

use meerkat::compose_tools_with_comms;

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

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

let build_config = AgentBuildConfig {
    model: "claude-sonnet-4-5".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-5")
};

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

use meerkat_comms::agent::{CommsAgent, CommsManager, CommsManagerConfig};

let config = CommsManagerConfig::with_keypair(keypair)
    .trusted_peers(trusted_peers)
    .comms_config(comms_config);
let comms_manager = CommsManager::new(config)?;

let agent = AgentBuilder::new()
    .model("claude-sonnet-4-5")
    .build(llm_client, tools, store)
    .await;

let mut comms_agent = CommsAgent::new(agent, comms_manager);

// Run with comms inbox draining
let result = comms_agent.run("Use send with kind=peer_message to greet agent-b".to_string()).await?;

// Or run in stay-alive mode
let result = comms_agent.run_stay_alive("You are a coordinator.".to_string(), None).await?;

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

// Child runtime (inproc, auto-trusts parent)
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,
    },
);
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 consumption
3. formatted message injection into the session is a projection of that lifecycle truth

​

Message injection format

• Message: [COMMS MESSAGE from <peer>]\n<body>
• Request: [COMMS REQUEST from <peer> (id: <uuid>)]\nIntent: <intent>\nParams: <json>\n\nTo respond, use send with kind=peer_response, peer="<peer>", request_id="<uuid>"
• Response: [COMMS RESPONSE from <peer> (to request: <uuid>)]\nStatus: <status>\nResult: <json>

​

Silent comms intents

let mut config = AgentBuildConfig::new("claude-sonnet-4-5");
config.silent_comms_intents = vec![
    "mob.peer_added".into(),
    "mob.peer_retired".into(),
];

• 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 stdin events
rkat run "You are a monitoring agent." \
  --comms-name monitor \
  --keep-alive --stdin \
  --enable-builtins

# Then type or pipe events:
echo '{"body":"deployment failed on prod"}' | ...

​

REST webhook

# Without auth (localhost only)
curl -X POST http://localhost:8080/sessions/sid_abc/external-events \
  -H "Content-Type: application/json" \
  -d '{"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 '{"alert": "deployment failed"}'

​

RPC session/external_event

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/external_event",
  "params": {
    "session_id": "sid_abc123",
    "payload": {"alert": "build failed"},
    "source": "rpc"
  }
}

​

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 injection format

• Stdin: [EVENT via stdin] <body>
• Webhook: [EVENT via webhook] <body>
• RPC: [EVENT via rpc] <body> (with optional [source: name] prefix)
• TCP/UDS: [EVENT via tcp] <body> or [EVENT via uds] <body>

​

Delivery vs observation

use meerkat_core::{EventInjector, PlainEventSource};

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

injector.inject(
    "review PR #42".into(),
    PlainEventSource::Rpc,
)?;

• 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(meerkatId) (Web SDK) / mob.subscribe_member_events(meerkat_id) (Python/TypeScript SDK)
• mob-scoped: use MobHandle::subscribe_mob_events(...) or mob/stream_open (RPC) / Mob.subscribeEvents() (Web SDK) / mob.subscribe_events() (Python/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 trusted_peers.json are accepted
• 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

​

See also

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