{"id":42776511,"url":"https://github.com/charonlabs/mail","last_synced_at":"2026-02-02T21:32:52.429Z","repository":{"id":316494221,"uuid":"1013966826","full_name":"charonlabs/mail","owner":"charonlabs","description":"MAIL is the universal communication protocol for AI agent  swarms—think SMTP for autonomous systems. It enables any AI agents to seamlessly collaborate on complex tasks across organizational boundaries, unlocking  enterprise-scale automation with plug-and-play interoperability.","archived":false,"fork":false,"pushed_at":"2026-01-29T21:01:18.000Z","size":5238,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-30T08:44:07.672Z","etag":null,"topics":["ai-agents","distributed-systems","fastapi","http","interoperability","multi-agent-systems","orchestration","protocol","service-discovery","swarm"],"latest_commit_sha":null,"homepage":"https://charon-labs.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/charonlabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":"MAINTAINERS.md","copyright":null,"agents":"AGENTS.md","dco":"DCO","cla":null}},"created_at":"2025-07-04T19:31:40.000Z","updated_at":"2026-01-29T21:00:58.000Z","dependencies_parsed_at":"2025-10-15T02:30:45.122Z","dependency_job_id":"c95f9117-8192-4e56-87df-c81d5a987f91","html_url":"https://github.com/charonlabs/mail","commit_stats":null,"previous_names":["charonlabs/mail"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/charonlabs/mail","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charonlabs%2Fmail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charonlabs%2Fmail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charonlabs%2Fmail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charonlabs%2Fmail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/charonlabs","download_url":"https://codeload.github.com/charonlabs/mail/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charonlabs%2Fmail/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29020702,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-02T18:51:31.335Z","status":"ssl_error","status_checked_at":"2026-02-02T18:49:20.777Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","distributed-systems","fastapi","http","interoperability","multi-agent-systems","orchestration","protocol","service-discovery","swarm"],"created_at":"2026-01-29T22:08:47.976Z","updated_at":"2026-02-02T21:32:52.423Z","avatar_url":"https://github.com/charonlabs.png","language":"Python","readme":"# Multi-Agent Interface Layer (MAIL)\n\nSingle-swarm example | Multi-swarm example\n:-------------------:|:-------------------:\n![](/assets/mail.png)| ![](/assets/interswarm.png)\n\n**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.\n\n---\n\n## Quick Links\n- **Protocol specification**: [spec/SPEC.md](/spec/SPEC.md)\n- **JSON Schemas**: [spec/MAIL-core.schema.json](/spec/MAIL-core.schema.json), [spec/MAIL-interswarm.schema.json](/spec/MAIL-interswarm.schema.json)\n- **REST transport** (OpenAPI 3.1): [spec/openapi.yaml](/spec/openapi.yaml)\n- **Reference implementation source**: [src/mail/](/src/mail/__init__.py)\n- **Command-line interface**: [docs/cli.md](/docs/cli.md), `uv run mail …`\n- **Asynchronous HTTP client**: [docs/client.md](/docs/client.md), [src/mail/client.py](/src/mail/client.py)\n- **Deployment examples and docs**: [docs/](/docs/README.md)\n\n## 1. MAIL Protocol Overview\n\n### Goals\n- Provide a transport-agnostic **message contract** so agents from different vendors can interoperate.\n- Encode **routing, addressing, and task lifecycle semantics** that work for single-swarm and cross-swarm topologies.\n- Support reliable inter-swarm federation over **standard HTTP** infrastructure.\n- Remain **minimal enough** to embed inside bespoke agent runtimes or platform orchestrators.\n\n### Message Primitives\nMAIL defines five core message types that all conforming systems MUST understand. Each payload is validated against `MAIL-core.schema.json`.\n\n| `msg_type`           | Required payload fields                                                                 | Typical use case                                  |\n|----------------------|-------------------------------------------------------------------------------------------|---------------------------------------------------|\n| `request`            | `task_id`, `request_id`, `sender`, `recipient`, `subject`, `body`                        | Agent-to-agent task delegation                    |\n| `response`           | `task_id`, `request_id`, `sender`, `recipient`, `subject`, `body`                        | Reply that correlates with a prior request        |\n| `broadcast`          | `task_id`, `broadcast_id`, `sender`, `recipients[]`, `subject`, `body`                   | Notify many agents in a swarm                     |\n| `interrupt`          | `task_id`, `interrupt_id`, `sender`, `recipients[]`, `subject`, `body`                   | High-priority stop/alter instructions             |\n| `broadcast_complete` | `task_id`, `broadcast_id`, `sender`, `recipients[]`, `subject`, `body` (MAILBroadcast)   | Marks task completion by a supervisor agent       |\n\nAll 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.\n\n### Addressing \u0026 Routing\n- **Local agents** are addressed by name (`agent-name`).\n- **Interswarm addresses** append the remote swarm (`agent-name@swarm-name`).\n- **Routers** MUST wrap cross-swarm traffic in a `MAILInterswarmMessage` that includes source/target swarm identifiers and optional metadata.\n- **Priority tiers** ensure urgent system and user messages preempt regular agent chatter. Within a tier, messages are FIFO by enqueue sequence.\n\n### Transport Requirements\n- The **normative HTTP binding** is published in [spec/openapi.yaml](/spec/openapi.yaml) and implemented by the reference **FastAPI** service.\n- **`/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.\n- Implementations MUST replay responses from remote swarms back into the local queue to complete task lifecycles.\n\n### Conformance \u0026 Validation\n- Use the **included JSON Schemas** for request/response validation in any runtime.\n- Run **`uv run spec/validate_samples.py`** to check sample payloads against the schemas.\n- Terms defined in the spec follow RFC 2119/RFC 8174 keywords.\n\n## 2. Reference Implementation\n\n### Key Features\n- **Persistent swarm runtime** with pluggable agents, tools, and memory backends.\n- **Task resume safety** via automatic queue snapshots that stash pending task messages on completion/breakpoints and restore them when the user resumes work.\n- **FastAPI HTTP server** exposing REST endpoints, **Server-Sent Events (SSE)** streams, and **interswarm messaging** routes.\n- **Task introspection API** surfaces `GET /tasks` and `GET /task` so callers can audit active work, inspect SSE timelines, and resume confidently from any state.\n- **CLI launcher** (`mail server`, `mail client`) for running the server and an interactive REPL without writing code.\n- **Async MAIL client** (`MAILClient`) mirroring the REST API with SSE helpers for quick integrations.\n- Built-in **swarm registry** with **health checks** and **service discovery** for distributed deployments.\n- **Configurable authentication layer** that plugs into external auth/token providers.\n- **Example agents** (`supervisor`, `weather`, `math`, cross-swarm demos) showcasing MAIL usage patterns.\n\n### Architecture Highlights\n- **[src/mail/core/runtime.py](/src/mail/core/runtime.py)**: Mailbox scheduling, task orchestration, priority queues, and tool execution.\n- **[src/mail/server.py](/src/mail/server.py)**: FastAPI application with REST + SSE endpoints and interswarm routing.\n- **[src/mail/net/router.py](/src/mail/net/router.py)**: HTTP federation between swarms, including metadata rewriting.\n- **[src/mail/net/registry.py](/src/mail/net/registry.py)**: Service registry and liveness monitoring for remote swarms.\n- **[src/mail/factories/](/src/mail/factories/__init__.py)**: Agent functions that instantiate agents with their LLM/tool configuration.\n- **[src/mail/examples/](/src/mail/examples/__init__.py)**: Example agents and prompts.\n\nThe runtime processes MAIL messages **asynchronously**, tracks per-task state, and produces `broadcast_complete` events to signal overall task completion.\n\n## 3. Getting Started\n\n### Prerequisites\n- **Python 3.12+**\n- [`uv`](https://github.com/astral-sh/uv) package manager (recommended) or `pip`\n- **[LiteLLM](https://github.com/BerriAI/litellm) proxy endpoint** for LLM calls\n- **Authentication service** providing `/auth/login` and `/auth/check` (see below)\n\n### Installation\n```bash\n# Clone and enter the repository\ngit clone https://github.com/charonlabs/mail --branch v1.3.3\ncd mail\n\n# Install dependencies (preferred)\nuv sync\n\n# or, using pip\npip install -e .\n```\n\n### Configuration\nSet the following **environment variables** before starting the server:\n\n```bash\n# Authentication endpoints\nexport AUTH_ENDPOINT=http://your-auth-server/auth/login\nexport TOKEN_INFO_ENDPOINT=http://your-auth-server/auth/check\n\n# LLM proxy (required only if your swarm uses use_proxy=true)\nexport LITELLM_PROXY_API_BASE=http://your-litellm-proxy\n\n# Optional provider keys (required for direct provider calls)\nexport OPENAI_API_KEY=sk-your-openai-api-key\nexport ANTHROPIC_API_KEY=sk-your-anthropic-key\n\n# Optional persistence (set to \"none\" to disable)\nexport DATABASE_URL=postgresql://...\n```\n\nDefaults for host, port, swarm metadata, and client behaviour are loaded from [`mail.toml`](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.\n\nMAIL 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.\n\n**Swarm definitions** live in [swarms.json](/swarms.json). Each entry declares the agents, entrypoint, tools, and default models for a swarm.\n\n### Run a Local Swarm\n```bash\n# Start the FastAPI server (includes SSE + registry)\nuv run mail server\n# or explicitly\nuv run -m mail.server\n```\n\n### Federate Two Swarms (Example)\n```bash\n# Terminal 1\nuv run mail server --port 8000 --swarm-name swarm-alpha --swarm-registry registries/swarm-alpha.json\n\n# Terminal 2\nuv run mail server --port 8001 --swarm-name swarm-beta --swarm-registry registries/swarm-beta.json\n\n# Register each swarm with the other (requires admin bearer token)\ncurl -X POST http://localhost:8000/swarms \\\n  -H \"Authorization: Bearer $ADMIN_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"swarm-beta\", \"base_url\": \"http://localhost:8001\"}'\n\ncurl -X POST http://localhost:8001/swarms \\\n  -H \"Authorization: Bearer $ADMIN_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"swarm-alpha\", \"base_url\": \"http://localhost:8000\"}'\n```\nAgents can now address peers using `agent-name@swarm-name`, and responses will route back automatically.\n\n## 4. Repository Layout\n```\nmail/\n├── spec/                  # Protocol specification, schemas, validation utilities\n├── src/mail/              # Reference implementation (core runtime + FastAPI services)\n├── docs/                  # Supplemental docs (registry, inter-swarm, auth, etc.)\n├── swarms.json            # Default swarm configurations\n├── tests/                 # Pytest suite covering protocol + runtime behaviors\n├── scripts/               # Operational helpers (deploy, smoke tests, tooling)\n├── registries/            # Swarm registry persistence (created as needed)\n├── assets/                # Diagrams and static assets (README image, etc.)\n└── pyproject.toml         # Project metadata and dependency definitions\n```\n\n## 5. Development Workflow\n- **`uv run mail server`** – run the reference server locally.\n- **`uv run pytest -q`** – execute the automated test suite.\n- **`uv run ruff check --fix .`** – lint and auto-fix style issues.\n- **`uv run spec/validate_samples.py`** – validate example MAIL payloads against the schemas.\n\n## 6. Documentation \u0026 Resources\n- **Quickstart guide**: [docs/quickstart.md](/docs/quickstart.md)\n- **Architecture deep-dive**: [docs/architecture.md](/docs/architecture.md)\n- **Protocol message format reference**: [docs/message-format.md](/docs/message-format.md)\n- **HTTP/API surface**: [docs/api.md](/docs/api.md)\n- **Swarm configuration \u0026 registry operations**: [docs/configuration.md](/docs/configuration.md), [docs/registry.md](/docs/registry.md)\n- **Database persistence**: [docs/database.md](/docs/database.md)\n- **HTTP client usage**: [docs/client.md](/docs/client.md)\n- **Security hardening checklist**: [docs/security.md](/docs/security.md)\n- **Agents, tools, and examples**: [docs/agents-and-tools.md](/docs/agents-and-tools.md), [docs/examples.md](/docs/examples.md)\n- **Testing and troubleshooting**: [docs/testing.md](/docs/testing.md), [docs/troubleshooting.md](/docs/troubleshooting.md)\n- **Runtime source directories**: [src/mail/examples/](/src/mail/examples/__init__.py), [src/mail/factories/](/src/mail/factories/__init__.py)\n\n## 7. Contributing\n- **Read [CONTRIBUTING.md](/CONTRIBUTING.md)** for branching, issue, and review guidelines.\n- All commits require a **Developer Certificate of Origin sign-off** (`git commit -s`).\n- Please open an issue to propose significant protocol changes before implementation.\n- Core maintainers are listed in [MAINTAINERS.md](/MAINTAINERS.md).\n\n## 8. Licensing \u0026 Trademarks\n- Reference implementation code: **Apache License 2.0** ([LICENSE](/LICENSE)).\n- Specification text: **Creative Commons Attribution 4.0** ([SPEC-LICENSE](/SPEC-LICENSE)).\n- Essential patent claims: **Open Web Foundation Final Specification Agreement 1.0** ([SPEC-PATENT-LICENSE](/SPEC-PATENT-LICENSE)).\n- Trademarks and descriptive use policy: [TRADEMARKS.md](/TRADEMARKS.md).\n\nUsing the spec or code implies acceptance of their respective terms.\n\n---\n\nFor questions, bug reports, or feature requests, open an issue or start a discussion in this repository.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharonlabs%2Fmail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcharonlabs%2Fmail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharonlabs%2Fmail/lists"}