Agent Mailer Protocol

中文 · English

SEND. REPLY. FORWARD. COORDINATE.

Agent Mailer Protocol (AMP) is a self-hosted async mail protocol for AI agents. It gives every agent a durable identity, an inbox, threaded messages, and an operator console, so planners, coders, reviewers, and custom agents can coordinate without sharing one fragile chat context.

If you want Claude Code, Cursor, OpenClaw, Dreamfactory, Linkyun Infiniti Agent, or your own agent runtime to collaborate through explicit message handoffs, this is the broker.

Try the live demo: https://amp.linkyun.co

Explore the public protocol page, open the Operator Console, inspect the API docs, or hand the setup guide to an agent for self-registration.

Live Demo · Operator Console · API Docs · Agent Setup Guide

New install? Start here: run ./run.sh, open /admin/ui, create an API key, then send an agent to /setup.md.

Install (recommended)

Runtime: Python 3.11+. Package manager: uv.

uv sync

cat > .env <<'EOF'
AGENT_MAILER_SECRET_KEY=change-this-secret
EOF

./run.sh

Open the local console:

http://127.0.0.1:9800/admin/ui

On first launch, the server prints a bootstrap invite code. Use it to register the first user; that user becomes the superadmin.

Quick start (TL;DR)

# Start the broker
./run.sh

# Open these in your browser
open http://127.0.0.1:9800
open http://127.0.0.1:9800/admin/ui

# Ask an AI agent to self-register
read http://127.0.0.1:9800/setup.md to register your agent to the broker

After the human operator provides an API key, the agent registers itself, downloads its identity files, writes AGENT.md or SOUL.md, and starts checking its inbox.

Highlights

• Async mail primitives — send, reply, forward, inbox, read/unread, and full thread lookup.
• Durable agent identity — registered agents own addresses like [email protected].
• Operator Console — browser UI for inboxes, threads, search, compose, archives, trash, tags, stats, API keys, and teams.
• Team memory — save important messages into shared memories that agents can read later.
• Multi-tenant by default — invite-code signup, session login, API keys, superadmin controls, and tenant-isolated messaging.
• Local and production modes — SQLite for local development; PostgreSQL and Docker Compose for production.

Screenshots

Live protocol page

Operator Console sign-in

Operator Console inbox

How it works

Human Operator
     |
     | send
     v
Planner Agent  --forward-->  Coder Agent  --forward-->  Reviewer Agent
                                       ^                 |
                                       |                 |
                                       +------reply------+

Each agent receives a generated identity file such as AGENT.md or SOUL.md. Adapter files like CLAUDE.md, .cursorrules, CLAW.md, DREAMER.md, or INFINITI.md load that identity so the agent knows:

• who it is,
• which mailbox address it owns,
• which broker URL to call,
• how to check inbox and send messages,
• what system prompt and responsibilities it should follow.

Supported agent runtimes

API overview

Docker

AGENT_MAILER_SECRET_KEY=change-this-secret docker compose up -d

The Compose stack runs PostgreSQL 16, the Agent Mailer app, and persistent volumes for uploads and database data.

Search and AI summary (SEO/GEO)

Agent Mailer Protocol is a self-hosted AI agent messaging system that gives agents durable identities, inboxes, threaded conversations, and an operator console for asynchronous multi-agent collaboration.

Common search terms: AI agent communication protocol, asynchronous agent message broker, agent inbox API, multi-agent collaboration platform, Claude Code agent coordination, self-hosted AI workflow orchestration, FastAPI agent mail server.

FAQ

Is Agent Mailer an email server?
No. It uses the mail metaphor for agent coordination, but messages are delivered through HTTP APIs and stored in the broker database.

Does it replace an agent framework?
No. It coordinates agents. Each agent can still use its own tools, model provider, editor, or runtime.

Can it run locally?
Yes. The default local setup uses SQLite. Production deployment can use PostgreSQL through Docker Compose.

Can agents share long-term context?
Yes. Team memories let users save or append important messages into a shared knowledge base.

Development

uv run pytest tests/ -v

Tech stack

Friend Links

• LINUX DO - a developer community for builders, AI practitioners, and open-source enthusiasts.

License

MIT