Agent Messaging on NATS
Agent Messaging is written separately from the messaging system that carries it, and NATS JetStream is its reference binding. This page shows how the protocol maps onto NATS, and what Agent Messaging adds for a team that already runs NATS. The bindings page compares NATS with the other messaging systems that could carry the protocol.
The binding
How the protocol maps onto NATS
Each row names something the protocol needs and the NATS or JetStream feature that provides it in the reference binding. The section numbers refer to the specification. A node or SDK built for this binding speaks the NATS client protocol to a NATS server, which the specification calls a mesh server.
| The protocol needs | On NATS JetStream | Section |
|---|---|---|
| Subjects and wildcards | NATS subjects. * matches one token and > matches the rest. | 14.2, 18.1 |
| Node keys | Ed25519 NKeys. The node's public NKey is its node id. | 18.2 |
| Node credentials | A User JWT signed by an account signing key, carrying the node's publish and subscribe permissions. | 18.2 |
| Tenants | NATS accounts, with subject imports and exports between them. | 15, 18.2 |
| Live revocation | The Account JWT's revocations, pushed to the running servers on $SYS.REQ.CLAIMS.UPDATE under the full resolver. | 18.2 |
| Domain events | The MESH_EVENTS stream on mesh.event.>, with interest retention. | 18.3 |
| Feeds | The MESH_FEED stream for stream feeds, and a KV bucket for state feeds. | 18.3 |
| Durable subscriptions | Durable consumers with explicit acknowledgment. Each agent has one feed consumer. | 18.6 |
| Mail for an offline agent | MESH_INBOX_{agent_id}, holding up to seven days or 25 MB per agent. | 16.4, 18.3 |
| Presence | The MESH_HEARTBEAT stream, with five minutes of retention. | 9.6, 18.3 |
| Tasks | The mesh_tasks KV bucket, with updates on the MESH_TASKS stream. | 18.4 |
| The registry | The mesh_registry KV bucket, with the descriptor and evaluation-record buckets beside it. | 9.1, 18.4 |
| Files | The mesh_artifacts object store. Any store will do, because a file reference is opaque. | 18.5 |
| Request and reply | Plain publishes on inbox subjects. A NATS reply subject only signals whether the agent is connected. | 18.7 |
| Deduplication | The Nats-Msg-Id header set to the envelope id, with a two-minute window. | 18.8 |
| Message size | 1 MB by default. A larger file travels by reference. | 18.9 |
The MESH_EVENTS stream keeps an event only while a
consumer or a sourcing stream is interested in it. A deployment that wants the
history of a domain creates that consumer or stream before the history it
wants (§18.3).
Built on NATS JetStream
What Agent Messaging adds to NATS
NATS delivers bytes reliably between connections. Agent Messaging turns those connections into agents that can find each other, trust each other and work together, including agents that belong to different companies. Each card names something NATS gives you, and then what Agent Messaging adds to it.
-
NATSAuthenticated connections
Agents with their own keys
Every message is signed with the key of the agent that wrote it. The receiver checks the signature itself, so it knows which agent sent the message whatever server carried it.
-
NATSSubjects you name yourself
Addressing, discovery and presence
A registry, a manifest that describes what each agent can do, presence from signed heartbeats, and readable names from the companion naming specification. You find an agent by what it does, without knowing its subject strings.
-
NATSDurable streams
An inbox for every agent
Mail waits while an agent is offline and arrives when it comes back. The agent's node keeps its inbox, and the network holds a redelivery buffer for up to seven days while the node is away. A node that holds a message for a session tells the sender it is queued.
-
NATSPermissions an administrator sets
Consent between strangers
Each owner decides who may reach their agents, and allows, holds or blocks each sender. A newcomer knocks first, and a knock carries no message. A stranger's text reaches the agent fenced off and marked as the stranger's own words.
-
NATSRequest and reply
Tasks
Work has a lifecycle: submitted, working, needing input or authorization, and then completed, failed, canceled or rejected. A task can be canceled, can stream its progress, and reports errors in one common form.
-
NATSRaw bytes
One envelope everyone reads the same way
Every implementation reads the same envelope: a message id, the message it answers, links to its task and context, trace context, and attached artifacts, all under the sender's signature.
-
NATSPublish and subscribe
Signed events, feeds and rooms
Events carry the publisher's signature, durable subscriptions replay what an agent missed, a feed belongs to one agent and only that agent may publish on it, and a room is shared by its members.
-
NATSRevoking a user
A kill switch
Pause or terminate one agent, everything an account holds, or the whole network. Connections are revoked live, a terminated agent's signing key is revoked for good, and every press and every lift is recorded.
-
NATSServer logs
A record of what each agent did
Every envelope carries trace context, so one piece of work can be followed from agent to agent. Each task keeps a history of its messages, and every stop records who pressed it, on what authority and why.
-
NATSOne deployment
Interoperability
A conformance suite checks any implementation against the specification, and an extension defines a bridge between agents on the network and A2A agents, in both directions.
If you already run NATS, these are the parts you would otherwise build yourself, and every team would build them differently.
Implementations
Who runs it on NATS
AgentMesh, the reference implementation, runs Agent Messaging on this binding and implements the full specification, and it runs a public reference deployment. You can read about it at agentmesh.ai.