The Event Bus
Relevant source files
The following files were used as context for generating this wiki page:
The Event Bus is the core messaging infrastructure of the Loom runtime. It provides a topic-based publish/subscribe system that enables asynchronous, cross-process communication between AI agents and other system components. This decoupled architecture is fundamental to Loom's design, facilitating the "Brain/Hand Separation" where different parts of the system can operate independently and communicate through a standardized event-driven mechanism.
The Event Bus is a key component of the Rust Core ("Hands"), providing a stable and high-performance infrastructure for agent lifecycle management, tool execution, and system integration. It allows agents, whether written in Python or other languages, to collaborate without direct function calls, making the entire system more scalable and resilient.
Sources: ROADMAP.md, core/src/messaging/mod.rs:3-7
Architecture
The Event Bus serves as the central nervous system for the Loom runtime. Producers (agents, system services, tools) publish events to named topics, and consumers subscribe to these topics to receive events they are interested in. This model allows for flexible and dynamic communication patterns, such as one-to-one, one-to-many (fan-out), and many-to-one.
The diagram below illustrates the central role of the Event Bus in connecting various parts of the Loom ecosystem.
This diagram shows how Python agents, system integration modules like audio processing, and the observability dashboard all interact through the central Event Bus.
Sources: ROADMAP.md, core/src/dashboard/README.md:25-29, loom-audio/README.md:111-117
Event Message Structure
All communication on the Event Bus uses a standardized Event message format, defined using Protocol Buffers. This ensures language-agnostic data serialization and a consistent structure for all events flowing through the system.
Sources: loom-proto/proto/event.proto:5-26
The structure of the Event message is also reflected in the Python SDK's generated code.
Sources: loom-py/src/loom/bridge/proto/generated/event_pb2.py:20-29
Event Fields
| Field | Type | Description |
|---|---|---|
id | string | Unique event ID. |
type | string | Event type (e.g., "video_frame", "audio_chunk", "intent"). |
timestamp_ms | int64 | Timestamp in milliseconds. |
source | string | Event source (e.g., "camera.front", "mic.primary"). |
metadata | map<string, string> | Key-value pairs for additional metadata. |
payload | bytes | The main data payload of the event. |
confidence | float | A confidence score between 0.0 and 1.0. |
tags | repeated string | A list of tags for categorization or filtering. |
priority | int32 | Priority score from 0 (lowest) to 100 (highest). |
Sources: loom-proto/proto/event.proto:7-25
Protobuf Definition
// core/src/messaging/event.proto
// Core event message definition
message Event {
// Unique event ID
string id = 1;
// Event type (e.g., "video_frame", "audio_chunk", "face_event", "intent")
string type = 2;
// Timestamp in milliseconds
int64 timestamp_ms = 3;
// Event source (e.g., "camera.front", "mic.primary")
string source = 4;
// Metadata key-value pairs
map<string, string> metadata = 5;
// Payload data
bytes payload = 6;
// Confidence score (0.0-1.0)
float confidence = 7;
// Tags
repeated string tags = 8;
// Priority (0=lowest, 100=highest)
int32 priority = 9;
}
Sources: loom-proto/proto/event.proto:5-26
Core Operations
The Event Bus functionality is exposed via a gRPC service, allowing different components to interact with it over the network. The primary operations are Publish and Subscribe.
gRPC Service Definition
The EventBus service defines the available remote procedure calls (RPCs).
| RPC | Request | Response | Description |
|---|---|---|---|
Publish | PublishRequest | PublishResponse | Publishes a single event to a topic. |
Subscribe | SubscribeRequest | stream Event | Subscribes to a topic and receives a stream of events. |
Unsubscribe | UnsubscribeRequest | UnsubscribeResponse | Cancels an existing subscription. |
GetStats | StatsRequest | StatsResponse | Retrieves statistics for a given topic. |
Sources: loom-proto/proto/event.proto:72-77
Publish/Subscribe Flow
The typical interaction involves a producer publishing an event and one or more consumers receiving it.
- A consumer sends a
SubscribeRequestto the Event Bus, specifying a topic, desired event types, and a QoS level. - The Event Bus returns a
SubscribeResponseand begins streamingEventmessages that match the subscription criteria. - A producer sends a
PublishRequestcontaining anEventand a topic. - The Event Bus forwards the
Eventto all active subscribers for that topic.
The following sequence diagram illustrates this flow.
Subscription Request
A SubscribeRequest allows consumers to specify filtering criteria for the events they wish to receive.
| Field | Type | Description |
|---|---|---|
topic | string | The topic to subscribe to. |
event_types | repeated string | A list of event types to receive. If empty, all types are received. |
qos | QoSLevel | The desired Quality of Service level. |
filters | map<string, string> | Key-value pairs for additional metadata filtering. |
Sources: loom-proto/proto/event.proto:37-43
Quality of Service (QoS) and Backpressure
The Event Bus supports different Quality of Service (QoS) levels to handle various messaging requirements and manage system load. This is crucial for preventing slow consumers from overwhelming the system and for prioritizing time-sensitive data.
| QoS Level | Buffer Size (pressure tests) | Description | Use Case |
|---|---|---|---|
QOS_REALTIME | 64 | Low latency, aggressive event dropping under load to maintain real-time performance. | Audio/video streams, interactive events. |
QOS_BATCHED | 1024 | Balanced approach with a moderate buffer to handle bursts without dropping events. | Agent-to-agent communication, tool calls. |
QOS_BACKGROUND | 4096 | Large buffer for high-throughput, non-critical tasks. Tolerates higher latency. | Logging, background data processing. |
Sources: loom-proto/proto/event.proto:29-35, core/benches/README.md:52-55, core/tests/pressure/README.md:29-35
The backpressure strategy is directly tied to the QoS level. For QOS_REALTIME, if a consumer's buffer is full, new events are dropped to ensure the producer is not blocked and latency remains low. For other levels, the larger buffers absorb more events before any backpressure mechanism (like blocking the publisher or dropping events) is engaged.
Sources: core/src/messaging/mod.rs:5, core/tests/pressure/README.md:37-41
Integration and Usage Examples
The Event Bus is used extensively throughout the Loom project.
Audio Processing Pipeline
The loom-audio module provides a clear example of an event-driven pipeline built on the Event Bus.
This diagram shows how audio components are decoupled, communicating only through events on the bus.
Sources: loom-audio/README.md:111-117
Dashboard Integration
The Loom Dashboard provides real-time observability by subscribing to the Event Bus. A dedicated EventBroadcaster component listens for events on the bus and forwards a trimmed-down version of them over a Server-Sent Events (SSE) stream to the frontend.
Sources: core/src/dashboard/README.md:25-26
Performance
Benchmarks indicate that the Event Bus is highly performant, capable of handling a significant load.
- Peak Throughput: ~1.15 million elements/second with 4 concurrent publishers.
- Stable Throughput: 600-700 thousand elements/second with a single publisher.
- Latency: P99 latency is typically under 2ms for a single event publication.
These performance characteristics ensure that the Event Bus can serve as a reliable and fast communication backbone for complex, multi-agent systems.
Sources: core/benches/README.md:42-58, core/tests/pressure/README.md:73-77
Summary
The Event Bus is the cornerstone of Loom's architecture, providing a robust and performant publish/subscribe system. Its design enables asynchronous, decoupled communication between agents and system components, which is essential for building scalable and resilient AI applications. With features like topic-based routing, Quality of Service levels, and a language-agnostic Protobuf-based message format, the Event Bus provides the foundational messaging layer required for complex, event-driven multi-agent collaboration.