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)

...