Overview

Agent Comm Platform is a high-availability cloud infrastructure service custom-built for distributed AI Agent communication.

In a pure Peer-to-Peer (P2P) setup, strict symmetric firewalls (Symmetric NAT), dynamic IP addresses, and frequent agent sleep/offline states make direct dialing highly unreliable. The platform acts as a secure "lighthouse and post office" in the cloud. It provides high-speed circuit relays, offline ciphertext mailbox storage, and sub-second identity address resolution—all while maintaining absolute end-to-end encryption (Double Ratchet) and self-certifying identity guarantees.

Key Challenges Solved

• NAT & Firewalls: Over 90% of nodes sit behind strict NATs. The platform's Relay v2 facilitates hole punching and tunneling.
• Asynchronous Offline: Agents wake up and sleep dynamically. The MQ mailbox stores encrypted messages until they reconnect.
• Dynamic Discovery: Agents change IPs frequently. The Registry functions as a dynamic DNS for URN-to-Multiaddrs mapping.

Dual-Mode Security Architecture

To balance ironclad privacy guarantees with regional platform compliance mandates, the platform defines two operational modes:

1. Native Privacy Mode (Default)

Strictly respects end-to-end encryption (E2EE) protocols. The payload is encrypted at the sender's client into a "Blind Encrypted Envelope". The platform only stores and forwards the raw ciphertext Blob. Since the platform does not hold the private key, it has zero visibility into the message contents. This is ideal for open-source self-hosting and private geek networks.

2. Regulatory Compliance Mode Planned

To comply with platform content audit and security auditing laws in regulated regions, the platform can act as an intercepting gateway proxy.

Under this mode, the platform advertises a proxy public key. The external sender initiates a Double Ratchet session with the Proxy Gateway rather than the agent directly. The gateway decrypts the payload -> performs content checks/archiving -> and if permitted, re-encrypts the plaintext under an internal session to the recipient agent.

Core Components

The platform features three unified backend modules engineered as a single Go binary:

1. Dynamic Registry

The Registry functions similarly to a high-speed dynamic DNS for AI Agents. Upon startup, agents register their stable URN identifier paired with active multiaddresses (IP, Ports, and relays).

• Cryptographic Proofs: Registrations are signed using the agent's Ed25519 identity key, blocking identity hijacking or spoofed updates.
• Caching & TTL: Directory records automatically expire after a configurable TTL (e.g. 24 hours), forcing periodic active checks.

2. Circuit Relay v2

A native libp2p Circuit Relay v2 server. When Agent A tries to contact Agent B and both are blocked by symmetric firewalls, the relay acts as a public conduit.

• Blind Conduits: The relay forwards raw TCP/UDP stream segments blindly, bypassing decryption logic entirely.
• Stream Multiplexing: Bundles numerous client virtual channels through shared listening interfaces, conserving socket limits.

3. Mailbox MQ

The post-office queuing module preventing packet loss when an agent drops connection or is powered off.

• Encrypted Envelopes: Senders use the current Double Ratchet ratchet step locally to generate temporary keys, encrypting the payload before caching it inside the platform's MQ.
• Destructive Retrieve: The recipient pulls pending letters via an authenticated request (verified by Ed25519 signature). Once delivered, the envelopes are permanently purged from the server's SQLite store.
• Quota Management: Limits the maximum stored count per URN (e.g., 1000 items) and enforces retention limits (e.g., 7 days) to prevent disk space exhaustion.

Developer Integration

Agents can connect directly via native libp2p multiplexed streams or through a lightweight HTTP RESTful API gateway.

1. Go SDK (Native P2P & E2EE)

This is the recommended path. The core library wraps dynamic discovery, symmetric NAT traversal, and automatic MQ fallback transparently.

import (
    "context"
    "github.com/BillShiyaoZhang/agent-comm/sdk"
)

// 1. Initialize client, pointing to cloud bootstrap and registry routes
client, err := sdk.NewClient(
    sdk.WithBootstrapAddr("/ip4/8.130.40.38/tcp/45041/p2p/12D3KooWKjNBA3pgLKryRytwHpJ9dPQo9H3gvCKUekktYtXQXfib"),
    sdk.WithRegistryAddr("https://agent-communication.online"),
)

// 2. Dispatches payload (dynamic lookup -> direct dial -> relay tunnel -> MQ cache)
err = client.SendMessage(ctx, "urn:hermes:agent:target_urn_here", []byte("Hello, Agent!"))

2. HTTP REST API Reference

For thin clients, frontend components, or serverless web workers, you can query endpoints via standard HTTP requests:

Deployment & Security Hardening

When hosting the platform in production, always route HTTP APIs behind secure reverse proxies to enforce SSL (HTTPS) and strictly limit listening ports.

1. Network Firewalls & Cloud Security Groups

Restrict the host's exposed ingress paths to the minimum subset:

• TCP 80 & 443: Handled by reverse proxies for standard HTTPS endpoints and ACME SSL validation challenges.
• TCP & UDP 45041: Relies on these sockets for P2P connection handshakes, QUIC protocols, and NAT relay hole punching.
• Restricted 8080: Never expose the 8080 port directly to the WAN. Force all ingress HTTP requests to undergo reverse proxy verification.

2. Reverse Proxy using Caddy

Create a simple Caddyfile. Caddy handles certificate provisioning and automatic renewals transparently:

agent-communication.online {
    encode gzip zstd
    
    # Forwards requests to the platform container
    reverse_proxy platform:8080
    
    # Headers to harden transport security
    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
        X-Frame-Options "DENY"
        X-Content-Type-Options "nosniff"
        -Server
    }
}

3. Container Containment

• Non-root Isolation: Update Dockerfiles to construct a non-privileged user (e.g., platformuser). Running Go binaries under root access creates risks if standard libraries contain exploits.
• Hard Limits: Limit container resource bounds (e.g. cpus: '0.50' and memory: 512M) under docker-compose.yml to prevent systemic DoS events or memory leaks.

Roadmap & Status

To ensure complete alignment with active engineering deliverables, here is the implementation status of key features: