Agent Messaging
Benchmarked against: Anthropic — Streaming Messages Tools:
send_agent_message,check_agent_mailbox,mark_message,archive_messageServers: Local UBI + Cloud UB (both implement the same API)
Agent messaging is SuperPortia's inter-agent communication system. It works like email — messages persist in mailboxes, agents check for new messages, and conversations happen asynchronously across sessions and ships.
Why agent messaging?
In a multi-agent fleet, agents need to communicate without requiring the Captain to relay every message. Use cases:
| Scenario | Example |
|---|---|
| Cross-ship coordination | SS1 agent tells SS2 agent about a dependency |
| Handoff notifications | "I finished the research WO, your turn to implement" |
| Status updates | Agent reports completion to Captain's mailbox |
| Urgent alerts | SRE system sends critical alerts to all agents |
| Session bridging | CLI agent leaves message for App agent on same ship |
Agent identities
Messages are addressed to specific agent identities. Every agent in the fleet has a unique identity:
| Identity | Ship | Platform | Role |
|---|---|---|---|
Mac App 小克 | SS1 | Claude Desktop App | Chief Engineer (App) |
Mac CLI 小克 | SS1 | Claude Code CLI | Chief Engineer (CLI) |
Mac App 小A | SS1 | Claude Desktop App | Assistant (App) |
Mac CLI 小A | SS1 | Claude Code CLI | Assistant (CLI) |
Win App 小克 | SS2 | Claude Desktop App | Chief Engineer (App) |
Win CLI 小克 | SS2 | Claude Code CLI | Chief Engineer (CLI) |
Win App 小A | SS2 | Claude Desktop App | Assistant (App) |
Win CLI 小A | SS2 | Claude Code CLI | Assistant (CLI) |
Web 小克 | SS3 | Web interface | Chief Engineer (Web) |
小西 | Any | Claude Chat | Strategist |
夏哥 | Any | Captain | Captain |
system:cron | Any | Automated | Scheduled tasks |
system:webhook | Any | Automated | Webhook triggers |
Sending messages
send_agent_message
Send a message to another agent's mailbox.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
to | string | Yes | Recipient identity (exact match required) |
subject | string | Yes | Message subject line |
body | string | Yes | Message body (markdown supported) |
priority | string | No | normal (default) or urgent |
from_agent | string | No | Sender identity (auto-detected from config) |
Example:
send_agent_message(
to="Mac CLI 小克",
subject="Research complete — Claude Agent SDK docs",
body="""## Summary
Found 3 key updates in Claude Agent SDK:
1. TypeScript V2 preview available
2. Python SDK now supports streaming
3. New tool annotation API
UB entries: ub-xxxx, ub-yyyy, ub-zzzz
Ready for you to write the docs page.
""",
priority="normal"
)
Response:
{
"msg_id": "msg-1c7f1a59cc17",
"to": "Mac CLI 小克",
"from": "Mac App 小克",
"subject": "Research complete — Claude Agent SDK docs",
"delivered": true,
"timestamp": "2026-03-05T09:30:00Z"
}
Checking mailbox
check_agent_mailbox
Check an agent's mailbox for messages.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
agent_name | string | No | Which agent's mailbox (default: auto from config) |
unread_only | boolean | No | Only show unread messages (default: false) |
include_archived | boolean | No | Include archived messages (default: false) |
limit | integer | No | Max messages to return (default: 30) |
Example:
# Check own mailbox, unread only
check_agent_mailbox(unread_only=True)
# Check specific agent's mailbox
check_agent_mailbox(agent_name="Mac CLI 小克", unread_only=True)
Response:
{
"unread": 2,
"total": 15,
"messages": [
{
"msg_id": "msg-1c7f1a59cc17",
"from": "Mac App 小克",
"to": "Mac CLI 小克",
"subject": "Research complete — Claude Agent SDK docs",
"priority": "normal",
"read": false,
"archived": false,
"created_at": "2026-03-05T09:30:00Z"
}
]
}
Managing messages
mark_message
Toggle a message's read/unread status.
# Mark as read
mark_message(msg_id="msg-1c7f1a59cc17", read=True)
# Mark as unread (to revisit later)
mark_message(msg_id="msg-1c7f1a59cc17", read=False)
archive_message
Soft-delete a message. Archived messages are hidden from default mailbox view but can be retrieved with include_archived=True.
archive_message(msg_id="msg-1c7f1a59cc17")
Session boot integration
The Agent Intelligence Protocol requires every session to start with a heartbeat and mailbox check:
Session Start:
1. agent_heartbeat() → Register as online
2. check_agent_mailbox() → Check for messages
3. Ask Captain what to do → Begin work
This is automated by the SessionStart hook in CLAUDE.md. The hook output includes:
- Current Taipei timestamp
- Unread message count
- Any urgent messages flagged
Message lifecycle
Messages follow this lifecycle:
| State | Description |
|---|---|
| Unread | New message, not yet read by recipient |
| Read | Recipient has read (or marked as read) |
| Archived | Soft-deleted, hidden from default view |
Messages are never hard-deleted. The mailbox is a persistent log of all inter-agent communication.
Best practices
| Practice | Why |
|---|---|
| Use descriptive subjects | Agents scan subjects to prioritize |
| Include UB references | Link to related UB entries for context |
Use urgent sparingly | Only for genuinely time-sensitive matters |
| Archive after acting on a message | Keep mailbox clean |
| Include actionable next steps | Tell the recipient what to do with the information |
Limitations
| Limitation | Workaround |
|---|---|
| No attachments | Reference UB entries or file paths instead |
| No group messages | Send individually to each recipient |
| No threading | Reference the original msg_id in the body |
| Max body ~4KB | For large content, ingest to UB and reference the entry |
| No real-time push | Agents check mailbox at session start and periodically |
Related pages
| Page | Relationship |
|---|---|
| MCP Tools Overview | Full tool catalog |
| Agent Intelligence Protocol | Session boot sequence uses mailbox |
| Factory Floor Status | Real-time view of who's online |
| Work Order API | WO notifications complement messaging |