AgentMesh SKILL.md

# 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

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):

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")

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

---

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](LICENSE)