Introducing the Multi-Agent Interface Layer (MAIL)

2025-09-23

TL;DR. MAIL is a lightweight, REST‑transported communication spec for AI agents. It defines a small set of message types—request, response, broadcast, interrupt, and broadcast complete—plus addressing (agent@swarm), routing, and an inter‑swarm envelope so agents can collaborate reliably inside a swarm and across swarms. It’s human‑readable, LLM‑friendly, and ships with a Python/FastAPI reference server.

Diagram illustrating an example of single-swarm MAIL communication, showing how discrete agents can collaborate to complete a common task. (credit: Will Hahn @ Charon Labs)

MAIL in 90 seconds (for everyone)

Think of MAIL as email for AI agents:

Agents have addresses (like weather@research‑swarm).
One agent requests help from another, gets a response, or broadcasts something everyone should know.
If something urgent happens, an interrupt can pause or stop work.
When the job is truly done, the swarm says broadcast complete so there’s a single, unambiguous finish line.

Why this matters: with MAIL, different agent teams—even in different companies—can coordinate work over the web as easily as people coordinate over email, while staying auditable and controllable.

Why now?

Multi‑agent systems are moving from demos to production. Teams need interoperability (agents from different stacks should cooperate), operational clarity (who did what, when), and internet‑scale routing (call a remote swarm as easily as a local agent). Frameworks help compose agents; MAIL fills the gap at the wire‑protocol layer with a durable, minimal messaging model over HTTP.

What MAIL is (high‑level)

Data Model

JSON messages with explicit sender, recipient, subject, body, task_id, and a msg_type from five verbs. Interswarm messages wrap payloads and annotate source_swarm / target_swarm, e.g., when you send to weather@remote‑swarm.

Addressing & Routing

Local names resolve inside a swarm; agent@swarm routes externally. Routers rewrite sender/recipient with swarm qualifiers and set expect_response when a reply is required.

Priorities & Ordering

Messages sent by the system have top priority within the queue, followed by messages from users. For agents, interrupts and completes are highest priority, followed by requests and responses. Within a class, delivery is FIFO by timestamp.

Runtime Model

A MAIL instance stores per‑agent histories for context, executes agent actions/tool calls, tracks pending work by task_id, emits action‑result broadcasts, and resolves only when broadcast complete arrives.

Transport & Security

REST endpoints cover user chat, inter‑swarm messaging, and a swarm registry; HTTP bearer tokens gate roles (admin, agent, user).

Use cases: What can you build with MAIL?

Enterprise agent swarms. Route tasks among domain specialists (research, data access, coding, compliance). Use broadcasts to fan out searches and interrupts for policy stops.
Inter‑org collaboration. Let a procurement swarm talk directly to a vendor’s quoting swarm via @vendor‑swarm, with explicit request/response trails for auditing.
Federated RAG & tool networks. Retrieval swarms call remote tool swarms (pricing, inventory, CRM), aggregate results under one task_id, and finalize with broadcast complete.
Human‑in‑the‑loop ops. Treat a person like a first‑class address; pause a run with interrupt, resume on approval.
Edge/device agent meshes. Keep the protocol identical from cloud to edge; devices subscribe to broadcasts and respond with measurements.

An abstract example of interswarm communication over MAIL, illustrating concepts such as task delegation and swarm structure. (credit: Will Hahn @ Charon Labs)

Advantages: Why do teams like MAIL?

LLM‑native, human‑legible. The email metaphor keeps prompts and results readable for both humans and models—great for debugging and safety reviews.
Small verb set, big coverage. Five message types cover plan/execute, pub‑sub, interrupts, and finalization—no heavy ontology required.
Interop by default. agent@swarm addressing + an inter‑swarm envelope make cross‑org communication first‑class.
Operational clarity. Every task culminates in broadcast complete, simplifying monitoring, tracing, and SLAs.
Security model you already know. Simple bearer tokens and roles; easy to layer mTLS, audit logging, or gateways.
Reference server implementation included. A Python/FastAPI server implements the spec’s data model, routing semantics, runtime, and REST transport.
Ergonomic Python SDK. Integrating MAIL into a Python project is simple; Easy-to-use classes that represent agents, messages, actions, and more.

Where MAIL fits vs. other efforts

FIPA ACL / KQML (classic MAS standards)

FIPA ACL and KQML define rich communicative acts (performative types like request, inform, propose) and formal message parameters; they predate LLMs and often presume separate content languages/ontologies.¹ ² ³ MAIL keeps a minimal verb set, JSON envelopes, and LLM‑friendly bodies while retaining clear routing and completion semantics.⁴

Anthropic’s Model Context Protocol (MCP)

MCP standardizes how applications expose tools, prompts, and resources to LLMs (a “USB‑C for AI apps”).⁵ ⁶ It connects models to capabilities; it’s not primarily an agent‑to‑agent routing protocol. MAIL is complementary: use MCP to give an agent tools and data; use MAIL to coordinate multi‑agent task flow within and across swarms.⁷ ⁸

LangChain’s Agent Protocol

Agent Protocol proposes framework‑agnostic APIs for serving agents in production (Runs/Threads/Store) and introspection.⁹ ¹⁰ MAIL is orthogonal and lower‑level: a message‑passing layer that defines who talks to whom, how messages are prioritized/routed, and how tasks finalize across multiple agents and swarms. They can coexist: an Agent‑Protocol service can speak MAIL between sub‑agents.¹¹

Frameworks (AutoGen, OpenAI Swarm, LangGraph)

These are powerful libraries for composing agents, not interop wire protocols.¹² ¹³ ¹⁴ Use them to build agents; use MAIL so those agents can communicate across stacks and organizations over HTTP.¹⁵

What MAIL is not

Not a replacement for your favorite agent framework; it’s the glue that lets agents talk across stacks.¹² ¹⁵
Not a heavy semantic language. If you want FIPA‑style performatives/ontologies, encode them in the body—MAIL stays minimal.

Selected highlights: A quick look at the spec

Message & Interswarm models. JSON envelopes with msg_type, IDs, sender/recipient, timestamps, and optional metadata; inter‑swarm wraps payloads and annotates source/target swarms and expect_response.
Addressing. user, agent, and system address types. Inter‑swarm addresses look like agent-name@swarm-name. Special recipient agent: all broadcasts locally.
Routing rules. Local delivery by name; @remote triggers inter‑swarm wrapping and delivery to the remote /interswarm/message endpoint; responses return via /interswarm/response.
REST surface & roles. Public POST /message (user/admin) calls into the supervisor and resolves when broadcast complete lands; admins can maintain a swarm registry for cross‑swarm calls; agents use inter‑swarm endpoints; all protected by bearer tokens.

Design choices we sweated

Minimal verbs, maximal composability. Five core message types cover most workflows without a new ontology per domain.
Finality as a first‑class event. Broadcast complete reduces ambiguity around “are we done yet?” in concurrent chains.
Inter‑swarm as a requirement. Cross‑boundary calls and responses are part of the spec, not an afterthought.
Natural‑language friendly bodies. Bodies are free‑form for LLMs (and humans); you can include structured snippets for tools when helpful.

Implications

Observability & billing. MAIL’s explicit task_id and completion events make task‑level tracing, budgets, and SLAs straightforward to implement.
Safety & governance. Clear message boundaries and interrupts make human‑review and policy checks easy to insert mid‑flight.
Ecosystem effects. A common envelope and routing scheme lets orgs expose swarms like APIs—enabling marketplaces and inter‑company automations. (MCP plugs into capabilities; MAIL coordinates agents.)⁵ ⁶

Open source & how to get involved

We’re open‑sourcing MAIL at charonlabs/mail under the Apache‑2.0 license. That’s a permissive license widely used in industry; it allows broad use and modification while requiring preservation of notices and providing an explicit patent license from contributors. Contributions can be incorporated into commercial and open projects alike.¹⁶ ¹⁷

How you can help (great first PRs):

Implement additional runtimes (e.g., Node/TypeScript reference server) that speak the same wire protocol.
Add policy hooks (pre‑send / pre‑receive) or audit log exporters.
Build adapters so agents from AutoGen, LangGraph, or OpenAI Swarm can emit/ingest MAIL messages natively.¹² ¹⁴ ¹⁵
Expand the test suite to improve code coverage.