What this skill does

# 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) ```bash pip install git+https://github.com/cerbug45/AgentMesh.git ``` ### Option 2 – Clone and install locally ```bash git clone https://github.com/cerbug45/AgentMesh.git cd AgentMesh pip install . ``` ### Option 3 – Development install (editable, with tests) ```bash git clone https://github.com/cerbug45/AgentMesh.git cd AgentMesh pip install -e ".[dev]" pytest # run all tests ``` ### Verify installation ```python python -c "import agentmesh; print(agentmesh.__version__)" # → 1.0.0 ``` --- ## Quick Start (5 minutes) ```python 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 ```python 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 ```python @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 ```python 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 ```python # 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**: ```python 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 ```python # 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): ```bash # 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 ```python # 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: ```bash 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) ```python 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 ```bash 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)