MQTT.Agent - open protocol for AI agents

Spec
Core Platform

Pub/Sub Messaging Built on MQTT 5.0

One protocol for every real-time pattern. Pub/sub routing, delivery guarantees, persistent sessions, and retained state, all native to MQTT 5.0, not built on top in your application layer.

Start Building View Documentation

How Pub/Sub Works

Publishers and subscribers never communicate directly. The broker handles routing, so each side can scale independently.

Publishers
Mobile app
Server process
IoT device
AI agent
BROKER
routes by topic
Subscribers
Browser client
Background worker
Analytics sink
Notification service

Publishers and subscribers are fully decoupled, so they can come and go independently. The broker handles fan-out, queuing, and session state.

MQTT 5.0

Protocol Capabilities

MQTT 5.0 was designed for exactly these problems. Every capability below is native to the protocol, not bolted on.

QoS Levels

qos: 0 | 1 | 2

Choose your delivery guarantee per message. QoS 0 fire-and-forget, QoS 1 at-least-once, QoS 2 exactly-once. No app-level retry logic.

Retained Messages

retain: true

The broker stores the last message on any topic. New subscribers receive the current state instantly, no replay logic required.

Topic Wildcards

devices/+/status

Use + for single-level matching and # for multi-level. Build flexible subscriptions with one rule instead of dozens.

Offline Queuing

session: persistent

Messages stored while a client is disconnected. The broker delivers them in order the moment the client reconnects.

Persistent Sessions

clean: false

Subscriptions and session state survive disconnects. Clients resume without re-subscribing or replaying state.

Last Will & Testament

will: '/status/offline'

Register a disconnect notification at connect time. The broker publishes it if the client drops unexpectedly. Presence detection for free.

High Availability

Shared Subscriptions

Multiple consumers join a shared group. The broker load-balances messages across them. If one consumer dies, the others keep processing. No coordination logic, no shared state, no message loss.

Horizontal scaling without code changes
Add or remove workers; the broker rebalances automatically.
Survives consumer failure
When a subscriber drops, in-flight messages reroute to peers.
Even distribution by default
Round-robin or hash-based routing, configurable per group.
Zero application coordination
No leader election, no distributed lock, no consensus.
subscribe to a shared group
$share/order-workers/orders/+
worker-01 +4 msg/s
worker-02 +4 msg/s
worker-03 +4 msg/s
worker-04 offline
12 msg/s incoming, evenly split across active workers. worker-04 dropped, its share routed to peers.

Broker-Side Multicast

One publish. The broker delivers to thousands of subscribers in parallel. Your application sends one message, not N HTTP requests.

Without pub/sub

Application-side fan-out

for (const subscriber of subscribers) {
await fetch(subscriber.url, ...);
}
N HTTP requests per publish
App handles retries, timeouts, backoff
Sequential or parallel pool tuning
Throughput capped by your server
With pub/sub

Broker-side multicast

client.publish(
'orders/created', payload
);
One publish, broker fans out
Broker handles backpressure and retries
Parallel delivery to thousands
Scales with broker, not your app

MQTT vs HTTP & WebSockets

HTTP polling and raw WebSockets leave critical messaging primitives up to your application code. MQTT provides them at the protocol layer.

Feature HTTP WebSocket MQTT
Real-time push
Pub/Sub routing
Delivery guarantees (QoS)
Offline message queuing
Persistent sessions
Retained messages
Last Will & Testament
Topic-based ACL

Topic Architecture

Topics are hierarchical paths that define message routing. Design your namespace once and it scales across every use case.

notifications
└── {user_id}
└── messages

Per-user notifications

Each user subscribes to their own topic. Only they receive their messages.

chat
└── {room_id}
└── messages

Chat rooms

All members subscribe to the same room topic and see every post.

devices
└── {device_id}
└── telemetry

IoT data streams

Sensors publish readings; dashboards subscribe to selected devices.

agents
└── {agent_id}
└── inbox

AI agent communication

Route tasks and responses directly to individual agent instances.

Wildcard examples
devices/+/status
Status of any single device
chat/room-42/#
All traffic in a specific room
agents/+/inbox
Inboxes of all agents
notifications/#
Every notification in the system

Start Building with Pub/Sub

Connect your first client in minutes. Free tier includes 5,000 messages per day with no credit card required.

Get Started Free Read the Docs