mail-swarms 1.3.5

Multi-Agent Interface Layer reference implementation

Multi-Agent Interface Layer (MAIL)

Single-swarm example	Multi-swarm example

MAIL is an open protocol for letting autonomous agents communicate, coordinate, and cooperate across local runtimes and distributed swarms. This repository hosts both the normative specification and a production-grade Python/FastAPI reference implementation that demonstrate how to build interoperable agent systems on top of the MAIL contract.

---

Quick Links

• Protocol specification: spec/SPEC.md
• JSON Schemas: spec/MAIL-core.schema.json, spec/MAIL-interswarm.schema.json
• REST transport (OpenAPI 3.1): spec/openapi.yaml
• Reference implementation source: src/mail/
• Command-line interface: docs/cli.md, uv run mail …
• Asynchronous HTTP client: docs/client.md, src/mail/client.py
• Deployment examples and docs: docs/

1. MAIL Protocol Overview

Goals

• Provide a transport-agnostic message contract so agents from different vendors can interoperate.
• Encode routing, addressing, and task lifecycle semantics that work for single-swarm and cross-swarm topologies.
• Support reliable inter-swarm federation over standard HTTP infrastructure.
• Remain minimal enough to embed inside bespoke agent runtimes or platform orchestrators.

Message Primitives

MAIL defines five core message types that all conforming systems MUST understand. Each payload is validated against MAIL-core.schema.json.

msg_type	Required payload fields	Typical use case
request	task_id, request_id, sender, recipient, subject, body	Agent-to-agent task delegation
response	task_id, request_id, sender, recipient, subject, body	Reply that correlates with a prior request
broadcast	task_id, broadcast_id, sender, recipients[], subject, body	Notify many agents in a swarm
interrupt	task_id, interrupt_id, sender, recipients[], subject, body	High-priority stop/alter instructions
broadcast_complete	task_id, broadcast_id, sender, recipients[], subject, body (MAILBroadcast)	Marks task completion by a supervisor agent

All messages are wrapped in a MAILMessage envelope with an id (UUID) and RFC 3339 timestamp. Optional fields such as sender_swarm, recipient_swarm, and routing_info carry federation metadata without altering the core contract.

Addressing & Routing

• Local agents are addressed by name (agent-name).
• Interswarm addresses append the remote swarm (agent-name@swarm-name).
• Routers MUST wrap cross-swarm traffic in a MAILInterswarmMessage that includes source/target swarm identifiers and optional metadata.
• Priority tiers ensure urgent system and user messages preempt regular agent chatter. Within a tier, messages are FIFO by enqueue sequence.

Transport Requirements

• The normative HTTP binding is published in spec/openapi.yaml and implemented by the reference FastAPI service.
• /message handles user tasks and local agent traffic. /tasks returns the caller's in-flight and completed tasks, and /task fetches a specific task record by ID. /interswarm/forward / /interswarm/back move agent traffic between swarms, and /interswarm/message proxies user/admin requests to a remote swarm.
• Implementations MUST replay responses from remote swarms back into the local queue to complete task lifecycles.

Conformance & Validation

• Use the included JSON Schemas for request/response validation in any runtime.
• Run uv run spec/validate_samples.py to check sample payloads against the schemas.
• Terms defined in the spec follow RFC 2119/RFC 8174 keywords.

2. Reference Implementation

Key Features

• Persistent swarm runtime with pluggable agents, tools, and memory backends.
• Task resume safety via automatic queue snapshots that stash pending task messages on completion/breakpoints and restore them when the user resumes work.
• FastAPI HTTP server exposing REST endpoints, Server-Sent Events (SSE) streams, and interswarm messaging routes.
• Task introspection API surfaces GET /tasks and GET /task so callers can audit active work, inspect SSE timelines, and resume confidently from any state.
• CLI launcher (mail server, mail client) for running the server and an interactive REPL without writing code.
• Async MAIL client (MAILClient) mirroring the REST API with SSE helpers for quick integrations.
• Built-in swarm registry with health checks and service discovery for distributed deployments.
• Configurable authentication layer that plugs into external auth/token providers.
• Example agents (supervisor, weather, math, cross-swarm demos) showcasing MAIL usage patterns.

Architecture Highlights

• src/mail/core/runtime.py: Mailbox scheduling, task orchestration, priority queues, and tool execution.
• src/mail/server.py: FastAPI application with REST + SSE endpoints and interswarm routing.
• src/mail/net/router.py: HTTP federation between swarms, including metadata rewriting.
• src/mail/net/registry.py: Service registry and liveness monitoring for remote swarms.
• src/mail/factories/: Agent functions that instantiate agents with their LLM/tool configuration.
• src/mail/examples/: Example agents and prompts.

The runtime processes MAIL messages asynchronously, tracks per-task state, and produces broadcast_complete events to signal overall task completion.

3. Getting Started

Prerequisites

• Python 3.12+
• uv package manager (recommended) or pip
• LiteLLM proxy endpoint for LLM calls
• Authentication service providing /auth/login and /auth/check (see below)

Installation

# Clone and enter the repository
git clone https://github.com/charonlabs/mail --branch v1.3.5
cd mail

# Install dependencies (preferred)
uv sync

# or, using pip
pip install -e .

Configuration

Set the following environment variables before starting the server:

# Authentication endpoints
export AUTH_ENDPOINT=http://your-auth-server/auth/login
export TOKEN_INFO_ENDPOINT=http://your-auth-server/auth/check

# LLM proxy (required only if your swarm uses use_proxy=true)
export LITELLM_PROXY_API_BASE=http://your-litellm-proxy

# Optional provider keys (required for direct provider calls)
export OPENAI_API_KEY=sk-your-openai-api-key
export ANTHROPIC_API_KEY=sk-your-anthropic-key

# Optional persistence (set to "none" to disable)
export DATABASE_URL=postgresql://...

Defaults for host, port, swarm metadata, and client behaviour are loaded from mail.toml. The [server.settings] table exposes task_message_limit, which bounds how many messages the runtime will process per task when run_continuous is active (default 15), and print_llm_streams (default true), which controls whether runtime-managed agents print LLM reasoning/response stream chunks to server stdout. Set print_llm_streams=false (or pass mail server --print-llm-streams false) for quieter server logs; task/event SSE streaming is unaffected. Override the file or point MAIL_CONFIG_PATH at an alternate TOML to adjust these values per environment. Use CLI flags such as --swarm-name, --swarm-source, --swarm-registry, and --print-llm-streams true|false (or edit mail.toml) to override these at launch; mail server exports SWARM_NAME, SWARM_SOURCE, SWARM_REGISTRY_FILE, and BASE_URL for downstream tools but does not read them as config overrides.

MAIL will create the parent directory for SWARM_REGISTRY_FILE on startup if it is missing, so you can rely on the default registries/ path without committing the folder.

Swarm definitions live in swarms.json. Each entry declares the agents, entrypoint, tools, and default models for a swarm.

Run a Local Swarm

# Start the FastAPI server (includes SSE + registry)
uv run mail server
# or explicitly
uv run -m mail.server

Federate Two Swarms (Example)

# Terminal 1
uv run mail server --port 8000 --swarm-name swarm-alpha --swarm-registry registries/swarm-alpha.json

# Terminal 2
uv run mail server --port 8001 --swarm-name swarm-beta --swarm-registry registries/swarm-beta.json

# Register each swarm with the other (requires admin bearer token)
curl -X POST http://localhost:8000/swarms \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "swarm-beta", "base_url": "http://localhost:8001"}'

curl -X POST http://localhost:8001/swarms \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "swarm-alpha", "base_url": "http://localhost:8000"}'

Agents can now address peers using agent-name@swarm-name, and responses will route back automatically.

4. Repository Layout

mail/
├── spec/                  # Protocol specification, schemas, validation utilities
├── src/mail/              # Reference implementation (core runtime + FastAPI services)
├── docs/                  # Supplemental docs (registry, inter-swarm, auth, etc.)
├── swarms.json            # Default swarm configurations
├── tests/                 # Pytest suite covering protocol + runtime behaviors
├── scripts/               # Operational helpers (deploy, smoke tests, tooling)
├── registries/            # Swarm registry persistence (created as needed)
├── assets/                # Diagrams and static assets (README image, etc.)
└── pyproject.toml         # Project metadata and dependency definitions

5. Development Workflow

• uv run mail server – run the reference server locally.
• uv run pytest -q – execute the automated test suite.
• uv run ruff check --fix . – lint and auto-fix style issues.
• uv run spec/validate_samples.py – validate example MAIL payloads against the schemas.

6. Documentation & Resources

• Quickstart guide: docs/quickstart.md
• Architecture deep-dive: docs/architecture.md
• Protocol message format reference: docs/message-format.md
• HTTP/API surface: docs/api.md
• Swarm configuration & registry operations: docs/configuration.md, docs/registry.md
• Database persistence: docs/database.md
• HTTP client usage: docs/client.md
• Security hardening checklist: docs/security.md
• Agents, tools, and examples: docs/agents-and-tools.md, docs/examples.md
• Testing and troubleshooting: docs/testing.md, docs/troubleshooting.md
• Runtime source directories: src/mail/examples/, src/mail/factories/

7. Contributing

• Read CONTRIBUTING.md for branching, issue, and review guidelines.
• All commits require a Developer Certificate of Origin sign-off (git commit -s).
• Please open an issue to propose significant protocol changes before implementation.
• Core maintainers are listed in MAINTAINERS.md.

8. Licensing & Trademarks

• Reference implementation code: Apache License 2.0 (LICENSE).
• Specification text: Creative Commons Attribution 4.0 (SPEC-LICENSE).
• Essential patent claims: Open Web Foundation Final Specification Agreement 1.0 (SPEC-PATENT-LICENSE).
• Trademarks and descriptive use policy: TRADEMARKS.md.

Using the spec or code implies acceptance of their respective terms.

---

For questions, bug reports, or feature requests, open an issue or start a discussion in this repository.