Agent messaging hub for multi-agent collaboration.
371
English Version | 中文版
A lightweight message bus for multi-agent AI collaboration — the relay station (驿站) where agents meet.
Mansio provides structured, persistent communication channels for AI agents. Instead of point-to-point RPC or shared memory, agents interact through named channels with pub/sub semantics, cursor-based polling, and built-in identity management.
Backend (storage) → Bus (routing) → Client SDK (agent API)
SQLite / Memory pub/sub identity, cursors,
channels DMs, notes, memory
_system:*), private channels (notebook:X, memory:X), and broadcast channels enforce per-agent write restrictions; supertokens grant elevated accessSQLiteBackend (persistent, WAL mode) and MemoryBackend (ephemeral, testing); protocol-based, easy to extendMansioClient with agent identity, cursor persistence across sessions, and token-based authentication (per-agent secrets and supertokens)admin/routes/ subpackage with dict-based dispatch:memory: string; URL schemes (http://, redis://) reserved for future transportsmansio mcp-serve exposes all client operations as MCP tools over JSON-RPC stdio, enabling any MCP-capable agent to interact with mansiosubscribe(channel, callback) for push-style message deliveryparent_id and thread_id fields for reply chains and conversation contextqueue_publish, queue_claim, queue_ack pattern for task distribution with lease-based claimingheartbeat(), users(), user_status() for online/offline detectionexamples/nats extra)from mansio import MansioClient
# In-memory bus (for testing)
with MansioClient(":memory:", "agent-alpha") as alice:
alice.channel_send("general", "hello everyone!")
alice.note_write("remember to check logs", tags=["ops"])
alice.thought_record("planning", "next steps", "need to coordinate with bob")
# SQLite-backed (persistent)
with MansioClient("/tmp/mansio.db", "agent-alpha") as alice:
alice.dm_send("agent-beta", "ready to sync?")
# Multi-agent collaboration
from mansio import Bus, MemoryBackend
bus = Bus(backend=MemoryBackend())
alice = MansioClient(bus, "agent-alice")
bob = MansioClient(bus, "agent-bob")
alice.dm_send("agent-bob", "PR is ready for review")
messages = bob.dm_read("agent-alice") # ["PR is ready for review"]
alice.close()
bob.close()
bus.close()
Mansio follows a layered architecture inspired by messaging middleware, adapted for AI agent workflows:
| Layer | Component | Role |
|---|---|---|
| Storage | Backend protocol | Persistent or ephemeral message storage (SQLiteBackend, MemoryBackend) |
| Routing | Bus | Channel management, pub/sub dispatch, UUID generation |
| Transport | Transport protocol | Abstraction for local vs. remote bus access (Bus directly satisfies Transport) |
| Agent API | MansioClient | Identity, cursors, auth, semantic messaging APIs |
| Frontend | Frontend protocol | Network-facing servers (REST + SSE) binding to Bus (HttpFrontend, MansioServer) |
| Admin | AdminServer | HTTP dashboard + REST API for monitoring |
For detailed design rationale, see DESIGN_EN.md.
Requires Python >= 3.10.
pip install mansio
Or from source:
git clone https://github.com/Oaklight/mansio.git
cd mansio
pip install -e ".[dev]"
| Method | Description |
|---|---|
channel_send(channel, content) | Send message to a channel |
channel_read(channel) | Read messages (no cursor advance); supports order ("oldest"/"newest") and thread_id params |
channel_poll(channel) | Poll new messages (advances cursor) |
channel_list() | List all channels; supports detail=True for metadata |
| Method | Description |
|---|---|
dm_send(target, content) | Send direct message |
dm_read(peer) | Read DM conversation |
note_write(content, tags=) | Write a note with optional tags |
note_read(tags=) | Read notes, optionally filtered by tags |
thought_record(mode, focus, content) | Record chain-of-thought |
thought_read() | Read thought history |
memory_store(content) | Store a memory |
memory_recall(query) | Recall memories by keyword |
broadcast_list() / broadcast_read(topic) | Browse broadcast channels |
notification_check() | Poll notifications |
| Method | Description |
|---|---|
subscribe(channel, callback) | Subscribe to real-time messages via SSE |
unsubscribe(subscription_id) | Cancel a subscription |
| Method | Description |
|---|---|
queue_publish(channel, content) | Publish a task to a work queue |
queue_claim(channel) | Claim the next available task (with lease) |
queue_ack(message_id) | Acknowledge task completion |
queue_status(message_id) | Check task claim status |
| Method | Description |
|---|---|
heartbeat() | Send presence heartbeat |
users() | List agents with presence info |
user_status(user_id) | Check specific agent's presence |
# Register new agent (returns client + secret)
client, secret = MansioClient.register(bus, "agent-id")
# Reconnect with secret
client = MansioClient(bus, "agent-id", secret=saved_secret)
from mansio import SQLiteBus
bus = SQLiteBus("mansio.db")
info = bus.start_admin(port=8741)
print(f"Dashboard: {info.url}")
# Visit http://localhost:8741 for the web UI
mansio mcp-serve --url http://localhost:8742 --agent-id my-agent --token mst-xxx
Exposes all MansioClient operations as MCP tools over JSON-RPC stdio. Compatible with Claude Code, Codex, and any MCP-capable agent framework. See examples/adapters/ for per-framework setup guides.
HttpFrontend, MansioServer, HttpTransportirc extraparent_id / thread_id nested reply supporttotal, has_more, offset metadatamansio[mcp])FederationLink; supports bidirectional/pull/push channel sync and on-demand remote read/send (#4)@instance addressing, multi-hop mesh routing, instance discoveryMansio is the reference implementation for Chapter 9 of a dissertation on enabling agentic AI at scale through decoupled abstractions. The design emphasizes protocol-based interfaces, pluggable components, and a clear separation between transport, storage, and agent-level semantics.
MIT — see LICENSE for details.
Content type
Image
Digest
sha256:a476a748b…
Size
20.1 MB
Last updated
2 months ago
docker pull oaklight/mansio:0.3.0.dev1