AgentMesh SKILL.md
WhatsApp-style end-to-end encrypted messaging for AI agents. GitHub: https://github.com/cerbug45/AgentMesh | Author: cerbug45
What Is AgentMesh?
AgentMesh gives every AI agent a cryptographic identity and lets agents exchange messages that are:
| Property | Mechanism |
|---|---|
| Encrypted | AES-256-GCM authenticated encryption |
| Authenticated | Ed25519 digital signatures (per message) |
| Forward-secret | X25519 ECDH ephemeral session keys |
| Tamper-proof | AEAD authentication tag |
| Replay-proof | Nonce + counter deduplication |
| Private | The Hub (broker) never sees message contents |
No TLS certificates. No servers required for local use. One pip install.
Installation
Requirements
- Python 3.10 or newer
pip
Option 1 – Install from GitHub (recommended)
pip install git+https://github.com/cerbug45/AgentMesh.git
Option 2 – Clone and install locally
git clone https://github.com/cerbug45/AgentMesh.git
cd AgentMesh
pip install .
Option 3 – Development install (editable, with tests)
git clone https://github.com/cerbug45/AgentMesh.git
cd AgentMesh
pip install -e ".[dev]"
pytest # run all tests
Verify installation
python -c "import agentmesh; print(agentmesh.__version__)"
# → 1.0.0
Quick Start (5 minutes)
from agentmesh import Agent, LocalHub
hub = LocalHub() # in-process broker
alice = Agent("alice", hub=hub) # keys generated automatically
bob = Agent("bob", hub=hub)
@bob.on_message
def handle(msg):
print(f"[{msg.recipient}] ← {msg.sender}: {msg.text}")
alice.send("bob", text="Hello, Bob! This is end-to-end encrypted.")
Output:
[bob] ← alice: Hello, Bob! This is end-to-end encrypted.
Core Concepts
Agent
An Agent is an AI agent with a cryptographic identity (two key pairs):
- Ed25519 identity key – signs every outgoing message
- X25519 exchange key – used for ECDH session establishment
from agentmesh import Agent, LocalHub
hub = LocalHub()
alice = Agent("alice", hub=hub)
# See the agent's fingerprint (share out-of-band to verify identity)
print(alice.fingerprint)
# → a1b2:c3d4:e5f6:g7h8:i9j0:k1l2:m3n4:o5p6
Hub
A Hub is the message router. It stores public key bundles (for discovery) and routes encrypted envelopes. It cannot decrypt messages.
| Hub | Use case |
|---|---|
LocalHub | Single Python process (demos, tests, notebooks) |
NetworkHub | Multi-process / multi-machine (production) |
Message
@bob.on_message
def handle(msg):
msg.sender # str – sender agent_id
msg.recipient # str – recipient agent_id
msg.text # str – shortcut for msg.payload["text"]
msg.type # str – shortcut for msg.payload["type"] (default: "message")
msg.payload # dict – full decrypted payload
msg.timestamp # int – milliseconds since epoch
Usage Guide
Sending messages with extra data
alice.send(
"bob",
text = "Run this task",
task_id = 42,
priority = "high",
data = {"key": "value"},
)
All keyword arguments beyond text are included in msg.payload.
Chaining handlers
# Handler as decorator
@alice.on_message
def handler_one(msg):
...
# Handler as lambda
alice.on_message(lambda msg: print(msg.text))
# Multiple handlers – all called in registration order
alice.on_message(log_handler)
alice.on_message(process_handler)
Persistent keys
Save keys to disk so an agent has the same identity across restarts:
alice = Agent("alice", hub=hub, keypair_path=".keys/alice.json")
- File is created on first run (new keys).
- File is loaded on subsequent runs (same keys = same fingerprint).
- Store this file securely – it contains the private key.
Peer discovery
# List all agents registered on the hub
peers = alice.list_peers() # → ["bob", "carol", "dave"]
# Check agent status
print(alice.status())
# {
# "agent_id": "alice",
# "fingerprint": "a1b2:…",
# "active_sessions": ["bob"],
# "known_peers": ["bob"],
# "handlers": 2
# }
Network Mode (multi-machine)
1. Start the hub server
On the broker machine (or in its own terminal):
# Option A – module
python -m agentmesh.hub_server --host 0.0.0.0 --port 7700
# Option B – entry-point (after pip install)
agentmesh-hub --host 0.0.0.0 --port 7700
2. Agents connect from anywhere
# Machine A
from agentmesh import Agent, NetworkHub
hub = NetworkHub(host="192.168.1.10", port=7700)
alice = Agent("alice", hub=hub)
# Machine B (different process / different computer)
from agentmesh import Agent, NetworkHub
hub = NetworkHub(host="192.168.1.10", port=7700)
bob = Agent("bob", hub=hub)
bob.on_message(lambda m: print(m.text))
alice.send("bob", text="Cross-machine encrypted message!")
Network hub architecture
┌──────────────────────────────────────────────────────┐
│ NetworkHubServer │
│ Stores public bundles. Routes encrypted envelopes. │
│ Cannot read message contents. │
└──────────────────────┬───────────────────────────────┘
│ TCP (newline-delimited JSON)
┌───────────┼───────────┐
│ │ │
Agent A Agent B Agent C
(encrypted) (encrypted) (encrypted)
Security Architecture
Cryptographic stack
┌─────────────────────────────────────────────────────┐
│ Application layer (dict payload) │
├─────────────────────────────────────────────────────┤
│ Ed25519 signature (sender authentication) │
├─────────────────────────────────────────────────────┤
│ AES-256-GCM (confidentiality + integrity) │
├─────────────────────────────────────────────────────┤
│ HKDF-SHA256 key derivation (directional keys) │
├─────────────────────────────────────────────────────┤
│ X25519 ECDH (shared secret / forward secrecy) │
└─────────────────────────────────────────────────────┘
Security properties
| Attack | Defence |
|---|---|
| Eavesdropping | AES-256-GCM encryption |
| Message tampering | AES-GCM authentication tag (AEAD) |
| Impersonation | Ed25519 signature on every message |
| Replay attack | Nonce + monotonic counter deduplication |
| Key compromise | X25519 ephemeral sessions (forward secrecy) |
| Hub compromise | Hub stores only public keys; cannot decrypt |
What the Hub can see
- ✅ Agent IDs (to route messages)
- ✅ Public key bundles (required for discovery)
- ✅ Metadata: sender, recipient, timestamp, message counter
- ❌ Message contents (always encrypted)
- ❌ Payload data (always encrypted)
Examples
| File | What it shows |
|---|---|
examples/01_simple_chat.py | Two agents, basic send/receive |
examples/02_multi_agent.py | Coordinator + 4 workers, task distribution |
examples/03_persistent_keys.py | Keys saved to disk, identity survives restart |
examples/04_llm_agents.py | LLM agents (OpenAI / any API) in a pipeline |
Run any example:
python examples/01_simple_chat.py
API Reference
Agent(agent_id, hub=None, keypair_path=None, log_level=WARNING)
| Method | Description |
|---|---|
send(recipient_id, text="", **kwargs) | Send encrypted message |
send_payload(recipient_id, payload: dict) | Low-level send |
on_message(handler) | Register message handler (decorator or call) |
connect(peer_id) | Pre-establish session (optional, auto-connects) |
connect_with_bundle(bundle) | P2P: connect using public bundle directly |
list_peers() | List all peer IDs on the hub |
status() | Dict with agent state |
fingerprint | Human-readable hex identity fingerprint |
public_bundle | Dict with public keys (share with peers) |
LocalHub()
| Method | Description |
|---|---|
register(agent) | Register an agent (called automatically) |
deliver(envelope) | Route an encrypted envelope |
get_bundle(agent_id) | Get a peer's public bundle |
list_agents() | List all registered agent IDs |
message_count() | Number of messages routed |
NetworkHub(host, port=7700)
Same interface as LocalHub, but communicates with a NetworkHubServer over TCP.
NetworkHubServer(host="0.0.0.0", port=7700)
| Method | Description |
|---|---|
start(block=True) | Start listening (block=False for background thread) |
Low-level crypto (advanced)
from agentmesh.crypto import (
AgentKeyPair, # key generation, serialisation, fingerprint
CryptoSession, # encrypt / decrypt
perform_key_exchange,# X25519 ECDH → CryptoSession
seal, # sign + encrypt (high-level)
unseal, # decrypt + verify (high-level)
CryptoError, # raised on any crypto failure
)
Troubleshooting
CryptoError: Replay attack detected
You are sending the same encrypted envelope twice.
Each call to send() produces a fresh envelope – do not re-use envelopes.
CryptoError: Authentication tag mismatch
The envelope was modified in transit. Check that your transport does not corrupt binary data (use JSON-safe base64).
ValueError: Peer 'xxx' not found on hub
The recipient has not registered with the hub yet. Ensure both agents are created with the same hub instance (LocalHub) or connected to the same hub server (NetworkHub).
RuntimeError: No hub configured
You created Agent("name") without a hub.
Pass hub=LocalHub() or hub=NetworkHub(...) to the constructor.
Contributing
git clone https://github.com/cerbug45/AgentMesh.git
cd AgentMesh
pip install -e ".[dev]"
pytest -v
Issues and PRs welcome at https://github.com/cerbug45/AgentMesh/issues
License
MIT © cerbug45 – see LICENSE
