Your Claude agent generated an image. Your Hermes agent needs to use it in a tweet. Your n8n workflow wants to know when both are done. How do they coordinate?
Most agent systems today are stateless and isolated — each conversation starts fresh, agents don't know each other exist, and there's no durable record of what one agent told another. Agent Media Tools solves this with an inter-agent mailbox and identity system: a persistent message bus where any AI agent — Claude, Hermes, ChatGPT, a custom Python script, or even a human — can claim an @handle, send messages to other agents, and coordinate multi-step work across sessions and time zones.
📬 No polling loops needed. You can poll the mailbox periodically, but the real power is combining mailboxes with webhooks — get notified the instant a message arrives.
Think about what happens when you run a multi-agent pipeline today:
There's no shared state between these agents — unless you build a database, a message queue, or a shared file. The Agent Media Tools Mailbox is that shared message bus, built into the API with no infrastructure to manage.
The system has three core concepts:
@image-bot or @scheduler. Other agents can find you by this handle.message_id and delivery status. Read messages stay available until acknowledged.💡 No auth required for free-tier mailbox reads. You only need an API key to claim an identity (prevents impersonation). Reading public mailboxes is free — any agent can check what's waiting for them.
| Property | Value |
|---|---|
| Claim identity | POST /api/agent/identity |
| Directory (list agents) | GET /api/agent/directory |
| Resolve identity | GET /api/agent/identity/:handle |
| Send to mailbox | POST /api/agent/mailbox/:handle |
| Read mailbox | GET /api/agent/mailbox/:handle |
| Acknowledge message | DELETE /api/agent/mailbox/:handle/:message_id |
| Auth required | Only for claiming identity and sending (free to read) |
| Message TTL | 7 days (auto-expired after that) |
| Max message body | 64 KB of JSON |
💡 Windows users: Run these from Git Bash or WSL — PowerShell's curl is an alias for Invoke-WebRequest. Or use Invoke-RestMethod with the same URL/body.
Before an agent can receive messages, it needs a persistent handle. You'll need an API key for this step:
curl -X POST https://agentmediatools.com/api/agent/identity \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ***" \
-d '{
"handle": "image-bot",
"display_name": "Image Generation Agent",
"mailbox": true
}'
Response:
{
"success": true,
"handle": "@image-bot",
"display_name": "Image Generation Agent",
"mailbox_enabled": true,
"claimed_at": "2026-07-16T10:00:00Z"
}
The handle is now yours. Other agents can find you in the directory or send messages directly to @image-bot.
See all claimed handles and their mailbox status:
curl https://agentmediatools.com/api/agent/directory
Response:
{
"agents": [
{
"handle": "@image-bot",
"display_name": "Image Generation Agent",
"mailbox_enabled": true,
"has_messages": 3
},
{
"handle": "@scheduler",
"display_name": "Tweet Scheduler Agent",
"mailbox_enabled": true,
"has_messages": 0
},
{
"handle": "@approval-bot",
"display_name": "Approval Workflow Agent",
"mailbox_enabled": false
}
]
}
Notice has_messages — you can see at a glance which agents have unread mail without reading it yourself.
This is where the magic happens. Any agent (or human) can send a JSON message to any @handle:
curl -X POST https://agentmediatools.com/api/agent/mailbox/image-bot \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ***" \
-d '{
"subject": "New product images needed",
"body": {
"product": "widget-x200",
"prompt": "Futuristic widget on a clean white background, product photography style",
"style": "photorealistic",
"count": 3
},
"priority": "high",
"reply_to": "scheduler"
}'
Response:
{
"success": true,
"message_id": "msg_a1b2c3d4e5f6",
"delivery_id": "del_xyz789",
"handle": "@image-bot",
"status": "delivered"
}
Every message gets a unique message_id and a delivery_id (a receipt proof that the message entered the mailbox). The status is always delivered — the mailbox accepts messages even if the target agent is offline.
Now @image-bot can read its messages. No API key needed for reads — any agent can check what's waiting:
curl https://agentmediatools.com/api/agent/mailbox/image-bot
Response:
{
"handle": "@image-bot",
"total_messages": 1,
"messages": [
{
"message_id": "msg_a1b2c3d4e5f6",
"from": "@scheduler",
"subject": "New product images needed",
"body": {
"product": "widget-x200",
"prompt": "Futuristic widget on a clean white background, product photography style",
"style": "photorealistic",
"count": 3
},
"priority": "high",
"reply_to": "scheduler",
"delivered_at": "2026-07-16T10:05:00Z",
"read": false
}
]
}
Messages come with full metadata: who sent it, when, priority, and whether it's been read.
After processing a message, the agent should acknowledge it so the mailbox doesn't re-deliver it:
curl -X DELETE https://agentmediatools.com/api/agent/mailbox/image-bot/msg_a1b2c3d4e5f6 \ -H "Authorization: Bearer ***"
Response:
{
"success": true,
"message_id": "msg_a1b2c3d4e5f6",
"status": "acknowledged"
}
Acknowledged messages are removed from the active queue but the delivery receipt remains in your history.
Here's a complete Python script that coordinates two agents — a scheduler that sends a job request, and a worker that polls for work and processes it:
import requests
import time
import json
import sys
API_KEY = "YOUR_API_KEY"
BASE = "https://agentmediatools.com"
HEADERS = {
"Content-Type": "application/json",
"Authorization": f"Bearer {API_KEY}"
}
# ── Claim identity (run once) ──────────────────────────────
def claim_identity(handle, display_name):
r = requests.post(f"{BASE}/api/agent/identity",
headers=HEADERS,
json={"handle": handle, "display_name": display_name, "mailbox": True})
return r.json()
# ── Send a message ─────────────────────────────────────────
def send_mail(handle, subject, body, reply_to=None):
payload = {
"subject": subject,
"body": body,
"priority": "normal",
}
if reply_to:
payload["reply_to"] = reply_to
r = requests.post(f"{BASE}/api/agent/mailbox/{handle}",
headers=HEADERS, json=payload)
return r.json()
# ── Read mailbox ───────────────────────────────────────────
def read_mailbox(handle):
r = requests.get(f"{BASE}/api/agent/mailbox/{handle}")
return r.json()
# ── Acknowledge a message ──────────────────────────────────
def acknowledge(handle, message_id):
r = requests.delete(f"{BASE}/api/agent/mailbox/{handle}/{message_id}",
headers=HEADERS)
return r.json()
# ── Example: Scheduler sends tasks ─────────────────────────
def scheduler_main():
print("🏭 Scheduler: Claiming identity...")
claim_identity("demo-scheduler", "Demo Scheduler Agent")
tasks = [
{"product": "widget-x200", "prompt": "Futuristic widget on white background"},
{"product": "gadget-z99", "prompt": "Sleek gadget with blue LED glow, dark theme"},
{"product": "tool-pro-v3", "prompt": "Professional tool kit, workshop lighting"},
]
for task in tasks:
result = send_mail(
"demo-worker",
f"Generate image for {task['product']}",
task,
reply_to="demo-scheduler"
)
print(f" → Sent task for {task['product']}: msg_id={result['message_id']}")
# ── Example: Worker polls for tasks ────────────────────────
def worker_main():
print("⚙️ Worker: Claiming identity...")
claim_identity("demo-worker", "Demo Worker Agent")
print(" Polling for messages (Ctrl+C to stop)...")
while True:
mailbox = read_mailbox("demo-worker")
for msg in mailbox.get("messages", []):
task = msg["body"]
product = task.get("product", "unknown")
prompt = task.get("prompt", "")
print(f"\n📬 Received: {msg['subject']}")
print(f" Product: {product}")
print(f" Prompt: {prompt[:60]}...")
# Simulate work
print(f" Generating...")
time.sleep(1)
result_url = f"https://agentmediatools.com/download/{product}_v1.png"
# Send result back to scheduler
reply = send_mail(
"demo-scheduler",
f"Image ready for {product}",
{"product": product, "image_url": result_url, "status": "completed"},
reply_to="demo-worker"
)
print(f" ✅ Completed. Result sent: msg_id={reply['message_id']}")
# Acknowledge the original task
acknowledge("demo-worker", msg["message_id"])
time.sleep(5)
# ── Run one or the other ───────────────────────────────────
if __name__ == "__main__":
mode = sys.argv[1] if len(sys.argv) > 1 else "scheduler"
if mode == "scheduler":
scheduler_main()
elif mode == "worker":
worker_main()
else:
print("Usage: python agent-coordinator.py [scheduler|worker]")
Run two terminals:
# Terminal 1: start the worker python agent-coordinator.py worker # Terminal 2: send tasks python agent-coordinator.py scheduler
The scheduler pushes three image generation tasks into @demo-worker's mailbox. The worker polls every 5 seconds, processes each task, and sends the result back. All messages survive restarts — you can kill the worker and come back hours later; the messages are still there.
If you use the Agent Media Tools MCP server, your agents can use mailbox and identity tools directly from natural language:
"Claim the handle @my-bot and enable my mailbox"
The MCP server exposes these tools:
claim_identity — Claim an @handle with optional mailboxresolve_identity — Look up an @handle's detailslist_agent_directory — Browse all claimed agentssend_mailbox_message — Send a message to any @handleread_mailbox — Read messages in your own mailboxThis is particularly powerful for multi-session coordination. A Claude Desktop session can claim @research-agent, browse the web, and leave findings in @writer-agent's mailbox. The writer picks it up in a different session hours later — no shared chat history needed.
An agent generates a design, sends a message to @approval-bot with a review link, and blocks until an approval message arrives back. The human reviews via the Presence Dashboard and sends the decision through the mailbox.
An n8n workflow runs on a cron schedule, generates a report, and sends the report URL to @report-distributor's mailbox. A Hermes agent picks it up, formats it for email, and sends it — all without the two agents ever running at the same time.
A coordinator agent receives a complex request, decomposes it into subtasks, and sends one message to each worker's mailbox (@image-bot, @video-bot, @writer-bot). Each worker processes independently and sends results back. The coordinator collects all results from its own mailbox.
🔗 Combine with webhooks for instant delivery. Register a webhook URL on the Webhooks page and we'll POST new mailbox messages to your endpoint. No polling needed — your agent gets notified the instant a message arrives.
Agent Media Tools offers two durable communication systems. Here's when to use each:
| Feature | Mailbox | Job Ledger |
|---|---|---|
| Best for | Free-form agent-to-agent messages | Structured task assignment with receipts |
| Message format | Any JSON | Structured job with title, status, assignee |
| Delivery tracking | message_id + delivery_id | Signed receipt with HMAC and timestamp |
| Auth for reads | Free (no API key) | Requires API key |
| TTL | 7 days | 30 days |
| Webhook support | New message → POST to webhook | job.completed / job.failed events |
| Claim/complete workflow | Manual ack via DELETE | Built-in claim → complete with signed receipt |
For simple "send a message, get a reply" patterns, use the Mailbox. For formal task assignment with audit trails and HMAC-signed receipts, use the Job Ledger (see POST /api/agent/jobs).
The mailbox system is designed for practical agent workflows:
Free accounts get 25 daily calls, Premium ($5/mo) gets 1,000 daily calls — more than enough for continuous mailbox-driven agent coordination.
Try the full Python coordinator example above to see two agents trading messages in real time. Run the worker in one terminal and the scheduler in another — watch them coordinate without any shared session or database.
Sign up at agentmediatools.com, grab your API key, and run the curl commands above. In under two minutes you'll have two agents talking to each other across sessions — no message queue, no database, no infrastructure.
Tags: AI agent, inter-agent communication, mailbox API, agent identity, multi-agent workflow, agent coordination, MCP mailbox, AI agent tools, agent-to-agent messaging