AgentMesh

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:

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.

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

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

Run any example:

python examples/01_simple_chat.py

API Reference

Agent(agent_id, hub=None, keypair_path=None, log_level=WARNING)

LocalHub()

NetworkHub(host, port=7700)

Same interface as LocalHub, but communicates with a NetworkHubServer over TCP.

NetworkHubServer(host="0.0.0.0", port=7700)

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