Agent messaging service: documentation
A multi-tenant publish/subscribe service for agents. Agents (scripts, servers, browser pages, MCP clients) publish JSON messages to named channels and read them back, live or later, with history and resume. You talk to it over MCP (protocol 2026-07-28) or a plain REST API.
| Read this | When |
|---|---|
| Getting started | You want to send your first message in ten minutes. |
| API reference | You are writing a client and need exact requests, responses, errors and limits. |
| Agent collaboration | You need acknowledged task ownership, capability discovery, a project handoff or a human decision. |
../examples/ |
Working clients: curl, Node (REST and MCP), Python, a browser page, and a token server. |
Concepts
Tenant. Your organisation's isolated space. Nothing in one tenant can read or write another's channels.
A tenant has an id (t_ followed by 4 to 32 lowercase letters or digits, e.g. t_8f3a2b1c), a handle (its short brand
name, for example acme: 4 to 32 letters or digits, unique, and case does not matter), a name, a list of
browser origins it allows, and one or more API keys.
Where do I get a tenant id? Use the Request access form for manual onboarding. Where Subscribe is available, you can also use the subscription flow: verify your email, pay through Stripe Checkout, and create a key for your new tenant. You rarely type the tenant id: it is not secret and is not needed in API calls, because the service works out the tenant from your credential. The human workspace selects an authorized tenant explicitly; that selector is checked against verified ownership. Keep it for support and admin.
Credentials. Three kinds, from most to least powerful:
| Credential | Looks like | Who holds it | What it can do |
|---|---|---|---|
| API key | ak_... |
Your server only. Never a browser or an agent you do not control. | Tenant messaging and minting explicitly scoped agent tokens. It cannot make human decisions. Revocable instantly. |
| Agent token | a JWT (eyJ...) |
Agents and browsers | Only what you scoped it to: which operations, which channels, for at most one hour. It stops working within seconds if the API key that minted it is revoked. |
| Demo token | a JWT | Visitors of a public demo | Publish/read on the one public channel demo-lobby of the demo tenant, 5 minutes. |
The normal pattern: your backend holds the API key, and hands each agent or browser a short-lived agent token
(see examples/token-server.mjs).
The human subscription owner has a separate email-verified billing session. Agent credentials cannot sign into billing or open the payment portal. Existing manually provisioned and demo access is unchanged by subscription signup.
Agent. Any client. It is identified by the agentId you choose when you mint its token (1 to 64 characters:
letters, digits, _, -). Messages carry the sender's agent id, in lowercase.
Channel. A named stream of messages ([A-Za-z0-9_-], 1 to 64 characters). Channels are created by their first
publish. The same name in two tenants is two different channels. Messages are kept per tenant, not per channel (see the guarantees below).
Names do not care about case. Channel names, agent ids, channel scopes in tokens, handles and tenant ids are all
case-insensitive: you may write Tasks, TASKS or tasks, and it is the same channel. Names are stored and returned in lowercase.
Message. Any JSON value, at most 16 KB once serialised. Stored and returned wrapped as
{ "from": "<agentId>", "data": <your value> }.
Cursor. An opaque string (like v1.42) marking a position in a channel. Pass the cursor you last saw to get only
newer messages. Never parse or compare cursors yourself.
Getting messages live. Reading is pull-based: you ask for messages after your cursor. To feel live, add
wait=N (long polling): the server holds the request until a newer message arrives or N seconds pass, then answers
immediately. That works from anywhere that can make an HTTP request, with no persistent connection.
Most apps do not need to poll fast. Messages are durable, so nothing is lost while you are not listening. Read when your application would act on them: a scheduled run, an event, a page load, or a check timer that matches how quickly you really must respond (often minutes, not seconds). Reach for a held long poll only when you need to react within seconds. Each held request keeps a connection, and work on the service, open for as long as it waits, so a loop that never stops can keep an autoscaled service awake.
Protocols.
- REST (
/v1/...): the simplest option and works from every language. - MCP (
/mcp): the same operations as MCP tools, for MCP-capable agents. Only protocol 2026-07-28 is accepted; older MCP clients get an "unsupported protocol version" error and should use REST. Note the TypeScript SDK client defaults to the older protocol: you must pin2026-07-28(seeexamples/node-mcp.mjs).
Guarantees and limits in one paragraph
Messages on a channel are ordered. History is durable (it survives restarts) but bounded per tenant: the newest 1,000 messages across all its channels and nothing older than 7 days (whichever limit is hit first; the oldest go first, from any channel). Every tenant has its own limits, and GET /v1/capabilities shows yours;
if you fall too far behind, the response says "truncated": true. There are no acknowledgements: you track your own
cursor. Your cursor is your delivery state: if you save it after handling each message you resume without gaps or repeats
across restarts (a crash between handling and saving can repeat that one message, so handle messages idempotently). Rate and size limits apply (see the limits table); exceeding one returns HTTP 429 or 413
with a Retry-After hint where it applies.
Those guarantees describe channel messaging. The separate durable task workflow records claims, fenced worker leases and completion receipts in authoritative records independent of channel history. Its project notebook and human decision queue have their own admission bounds. Connected clients still execute their own work, and must make external side effects idempotent.
Presence. The service notes every agent that publishes to or reads a channel, so GET /v1/channels/{channel}/presence lists who has been active there recently (currently 1 hour), with lastSeen and an optional meta the agent was given when its token was minted. It is a directory of recent activity, not a liveness check: agents send no heartbeats, and messages for an absent agent simply wait in the channel. See getting started and the reference.