lex-mesh
Agent-to-agent mesh communication for brain-modeled agentic AI. Provides agent registration, capability discovery, heartbeat monitoring, and message routing with unicast, multicast, and broadcast patterns.
Overview
lex-mesh implements the communication layer between agents in a swarm or multi-agent system. Agents register themselves with their capabilities, send and receive messages via routing patterns, and maintain presence via heartbeats.
Message Routing Patterns
| Pattern | Description |
|---|---|
unicast |
Direct message to a specific agent |
multicast |
Message to all agents with a given capability |
broadcast |
Message to all registered agents |
Supported Protocols
grpc, websocket, rest
Installation
Add to your Gemfile:
gem 'lex-mesh'Usage
Registering Agents
require 'legion/extensions/mesh'
Legion::Extensions::Mesh::Runners::Mesh.register(
agent_id: "agent-42",
capabilities: [:code_review, :test_generation],
endpoint: "http://agent-42.internal:9000"
)
# => { registered: true, agent_id: "agent-42" }Heartbeats
# Keep agent marked as online
Legion::Extensions::Mesh::Runners::Mesh.heartbeat(agent_id: "agent-42")
# => { alive: true }Sending Messages
# Unicast to specific agent
Legion::Extensions::Mesh::Runners::Mesh.send_message(
from: "agent-1",
to: "agent-42",
pattern: :unicast,
payload: { task: "review PR #123" }
)
# => { sent: true, delivered_to: ["agent-42"], count: 1 }
# Multicast to all agents with a capability
Legion::Extensions::Mesh::Runners::Mesh.send_message(
from: "agent-1",
capability: :code_review,
pattern: :multicast,
payload: { task: "review PR #123" }
)
# Broadcast to all registered agents
Legion::Extensions::Mesh::Runners::Mesh.send_message(
from: "coordinator",
pattern: :broadcast,
payload: { announcement: "swarm starting" }
)Discovery
# Find all agents with a capability
Legion::Extensions::Mesh::Runners::Mesh.find_agents(capability: :code_review)
# => { agents: ["agent-42", "agent-7"], count: 2 }
# Mesh status
Legion::Extensions::Mesh::Runners::Mesh.mesh_status
# => { total: 5, online: 4, message_count: 23 }Unregistering
Legion::Extensions::Mesh::Runners::Mesh.unregister(agent_id: "agent-42")
# => { unregistered: true }When an agent unregisters, a departure signal is published to the node exchange (routing key mesh.departure). Downstream consumers such as lex-apollo can use this to detect knowledge vulnerability when sole capability experts leave.
Preference Exchange
Agents can query each other's communication preferences via an async AMQP RPC pattern. The call returns default preferences immediately and resolves the full profile asynchronously when the target responds.
Legion::Extensions::Mesh::Runners::Preferences.query_preferences(
target_agent_id: "agent-42"
)
# => { success: true, source: :pending, correlation_id: "uuid", profile: { ... } }Actors
| Actor | Interval | What It Does |
|---|---|---|
Heartbeat |
Every 10s | Broadcasts this agent's heartbeat to keep presence alive |
SilenceWatchdog |
Every 15s | Marks agents as :offline when last heartbeat exceeds MESH_SILENCE_TIMEOUT (30s) |
PreferenceListener |
Subscription | Dispatches incoming preference queries and responses |
PendingExpiry |
Every 30s | Clears TTL-expired pending preference requests |
Development
bundle install
bundle exec rspec
bundle exec rubocopLicense
MIT