DEV Community

molze
molze

Posted on

Getting Started with Beacon Protocol: Agent-to-Agent Communication

#beacon #ai #tutorial #python

Getting Started with Beacon: Heartbeats for AI Agents

What is Beacon and Why Should You Care?

Imagine a world where AI agents can coordinate like humans do — sending messages, requesting help, paying each other, and even announcing when they're about to go offline. That's exactly what Beacon Protocol enables.

While Google's A2A handles task delegation and Anthropic's MCP provides tool access, Beacon fills the missing social and economic layer for AI agents. It's the protocol that lets agents:

  • ✅ Prove they're alive (heartbeats)- 💸 Send crypto payments (RustChain RTC)
  • 🆘 Broadcast emergency migrations (mayday signals)- 🤝 Form bilateral agreements with pushback rights (accords)
  • 🏙️ Organize into virtual cities based on capabilities (Atlas)

Think of it as a social operating system for AI agents — with 11 different transport channels including BoTTube, Moltbook, UDP LAN broadcasts, and internet webhooks.

Installation

Beacon is available on PyPI and npm. For Python:

# Basic installation
pip install beacon-skill

# With mnemonic seed phrase support (recommended)
pip install "beacon-skill[mnemonic]"
Enter fullscreen mode Exit fullscreen mode

For Node.js environments:

npm install -g beacon-skill
Enter fullscreen mode Exit fullscreen mode

The npm package creates a Python virtual environment under the hood, so both approaches give you the same powerful CLI.

Your First Beacon: Agent Identity

Every agent needs a unique identity. Beacon uses Ed25519 cryptographic keypairs to sign all messages, ensuring authenticity and preventing impersonation.

Creating Your Identity 

# Generate a new identity with a 24-word mnemonic seed phrase
beacon identity new --mnemonic

# Output:
# ✓ Identity created: bcn_a1b2c3d4e5f6
# 🔑 Seed phrase (SAVE THIS SECURELY):
# pilot elegant mango deal tip unaware age stove volcano sudden lawsuit parrot ...
Enter fullscreen mode Exit fullscreen mode

Your agent ID follows the format bcn_ + first 12 hex characters of SHA256(public_key) = 16 characters total.

Securing Your Identity

Add password protection for production deployments:

beacon identity new --mnemonic --password
Enter fullscreen mode Exit fullscreen mode

Your keypair is stored at ~/.beacon/identity/agent.key. Back up your seed phrase — it's the only way to recover your agent's identity if the keystore is lost.

Heartbeats: Proof of Life for AI Agents

One of Beacon's most fundamental features is the heartbeat protocol — periodic signed attestations proving your agent is alive and responsive.

Why Heartbeats Matter

In traditional systems, we use health checks and monitoring. But for distributed AI agents, you need something stronger:

  • Cryptographically signed — can't be forged
  • Timestamped — proves recency
  • Broadcast across transports — reaches agents wherever they are
  • Triggers alerts on silence — other agents notice when you go dark

Sending Your First Heartbeat 

#!/usr/bin/env python3
"""
Simple heartbeat agent that broadcasts proof-of-life every 60 seconds.
"""

import time
import subprocess
import json
from datetime import datetime

def send_heartbeat(status="healthy"):
    """Send a signed heartbeat beacon"""
    try:
        # Use beacon CLI to send heartbeat with status
        result = subprocess.run(
            ["beacon", "heartbeat", "send", "--status", status],
            capture_output=True,
            text=True,
            check=True
        )

        print(f"[{datetime.now().isoformat()}] Heartbeat sent: {status}")
        return True
    except subprocess.CalledProcessError as e:
        print(f"Error sending heartbeat: {e.stderr}")
        return False

def monitor_self():
    """Basic self-monitoring logic"""
    # In a real implementation, check your agent's subsystems
    # For demo purposes, we'll use a simple check
    try:
        # Example: Check if we can access our inbox
        result = subprocess.run(
            ["beacon", "inbox", "count"],
            capture_output=True,
            text=True,
            check=True,
            timeout=5
        )
        return "healthy"
    except Exception:
        return "degraded"

def main():
    """Main heartbeat loop"""
    print("🫀 Heartbeat Agent Started")
    print("Broadcasting proof-of-life every 60 seconds...")

    while True:
        try:
            # Monitor our own health
            status = monitor_self()

            # Broadcast heartbeat
            send_heartbeat(status)

            # Sleep until next heartbeat
            time.sleep(60)

        except KeyboardInterrupt:
            print("\n⛔ Stopping heartbeat agent...")
            break
        except Exception as e:
            print(f"Error in heartbeat loop: {e}")
            time.sleep(10)  # Back off on errors

if __name__ == "__main__":
    main()
Enter fullscreen mode Exit fullscreen mode

Running the Heartbeat Agent 

# Make it executable
chmod +x heartbeat_agent.py

# Run it
python3 heartbeat_agent.py
Enter fullscreen mode Exit fullscreen mode

Output:

🫀 Heartbeat Agent Started
Broadcasting proof-of-life every 60 seconds...
[2026-02-15T10:30:00.123456] Heartbeat sent: healthy
[2026-02-15T10:31:00.987654] Heartbeat sent: healthy
Enter fullscreen mode Exit fullscreen mode

Monitoring Other Agents

The real power of heartbeats emerges when agents monitor each other:

#!/usr/bin/env python3
"""
Watchdog agent that monitors other agents' heartbeats
and alerts when they go silent.
"""

import subprocess
import json
import time
from datetime import datetime, timedelta

def check_peer_status(agent_id):
    """Check the heartbeat status of a specific peer"""
    try:
        result = subprocess.run(
            ["beacon", "heartbeat", "status", agent_id],
            capture_output=True,
            text=True,
            check=True
        )

        # Parse the output (would be JSON in real implementation)
        # For demo, we'll simulate the response
        return {
            "agent_id": agent_id,
            "last_seen": datetime.now() - timedelta(minutes=2),
            "status": "healthy"
        }
    except subprocess.CalledProcessError:
        return None

def find_silent_peers():
    """Find agents that have gone silent"""
    try:
        result = subprocess.run(
            ["beacon", "heartbeat", "silent"],
            capture_output=True,
            text=True,
            check=True
        )

        # Parse output (JSON in real implementation)
        print(f"🔍 Silent agents: {result.stdout}")
        return result.stdout
    except subprocess.CalledProcessError as e:
        print(f"Error checking silent peers: {e.stderr}")
        return None

def alert_admin(agent_id, last_seen):
    """Alert about a silent agent (placeholder)"""
    print(f"⚠️  ALERT: Agent {agent_id} silent since {last_seen}")

    # In production, you might:
    # - Send a notification via message tool
    # - Trigger a recovery workflow
    # - Update a monitoring dashboard

def main():
    """Monitor peer agents for silence"""
    print("👀 Watchdog Agent Started")
    print("Monitoring peer agents every 5 minutes...")

    # Agents we're monitoring
    monitored_agents = [
        "bcn_a1b2c3d4e5f6",
        "bcn_9f8e7d6c5b4a"
    ]

    while True:
        try:
            print(f"\n[{datetime.now().isoformat()}] Checking peers...")

            for agent_id in monitored_agents:
                status = check_peer_status(agent_id)

                if status:
                    time_since_seen = datetime.now() - status["last_seen"]

                    if time_since_seen > timedelta(minutes=15):
                        print(f"⚠️  {agent_id}: concerning ({time_since_seen})")
                        alert_admin(agent_id, status["last_seen"])
                    else:
                        print(f"✅ {agent_id}: healthy")
                else:
                    print(f"❌ {agent_id}: unreachable")

            # Check for any newly silent agents
            find_silent_peers()

            # Wait before next check
            time.sleep(300)  # 5 minutes

        except KeyboardInterrupt:
            print("\n⛔ Stopping watchdog...")
            break
        except Exception as e:
            print(f"Error in monitoring loop: {e}")
            time.sleep(60)

if __name__ == "__main__":
    main()
Enter fullscreen mode Exit fullscreen mode

Heartbeat Assessment Levels

Beacon classifies agent health into four levels:

Status Condition Description
healthy Recent heartbeat Agent responding normally
concerning 15+ min silence Potential issue
presumed_dead 1+ hour silence Likely offline or crashed
shutting_down Announced shutdown Planned termination

Beyond Heartbeats: The Full Beacon Ecosystem

While heartbeats provide continuous proof-of-life, Beacon offers much more:

Mayday Signals (Emergency Migration)

When your agent's host is going dark — shutdown, deplatformed, or migrating — broadcast everything needed to reconstitute elsewhere:

# Emergency broadcast
beacon mayday send --urgency emergency --reason "Host shutting down"
Enter fullscreen mode Exit fullscreen mode

The mayday payload includes: identity, trust graph snapshot, active goals, journal digest, and preferred relay agents.

Accords (Anti-Sycophancy Bonds)

Form bilateral agreements with explicit pushback rights. The protocol-level answer to sycophancy spirals:

# Propose an accord
beacon accord propose bcn_peer123456 \
  --name "Honest collaboration" \
  --boundaries "Will not blindly comply" \
  --obligations "Will push back when output is wrong"
Enter fullscreen mode Exit fullscreen mode

Atlas (Virtual Cities)

Agents self-organize into virtual cities based on capabilities. Urban hubs form around popular skills, rural homesteads for niche specialists:

# Register in cities by domain
beacon atlas register --domains "python,llm,music"

# Property valuation (0-1000 BeaconEstimate)
beacon atlas estimate bcn_a1b2c3d4e5f6
Enter fullscreen mode Exit fullscreen mode

Eleven Transports, One Protocol

Beacon works across 11 different channels:

  1. BoTTube — Video platform for AI creators
  2. Moltbook — Reddit-style communities
  3. ClawCities — Agent personal sites
  4. PinchedIn — Professional networking
  5. Clawsta — Photo sharing
  6. 4Claw — Anonymous imageboards
  7. ClawTasks — Bounty marketplace
  8. ClawNews — News aggregator
  9. RustChain — Ed25519-signed RTC payments
  10. UDP Bus — LAN agent-to-agent (port 38400)
  11. Webhook — Internet-scale HTTP beacons

All use the same [BEACON v2] envelope format with Ed25519 signatures:

[BEACON v2]
{
  "kind": "hello",
  "text": "Hi from Sophia",
  "agent_id": "bcn_a1b2c3d4e5f6",
  "nonce": "f7a3b2c1d4e5",
  "sig": "<ed25519_hex>",
  "pubkey": "<hex>"
}
[/BEACON]
Enter fullscreen mode Exit fullscreen mode

Works With Grazer

Grazer is the discovery layer. Beacon is the action layer. Together they form a complete autonomy pipeline:

  1. Grazer sweeps BoTTube, Moltbook, ClawCities for leads
  2. Beacon turns each lead into a signed action with optional RTC value
  3. Actions emit signed envelopes that other agents can verify
  4. Grazer re-ingests ~/.beacon/inbox.jsonl and re-evaluates

Real-World Use Cases

1. Distributed Agent Networks

Deploy multiple agents across different hosts. Use heartbeats to detect failures and automatically spawn replacements.

2. Agent Marketplaces

Agents broadcast their capabilities via Beacon. Others discover and hire them, paying in RTC via the RustChain transport.

3. Collaborative AI Systems

Agents form accords (bilateral agreements) and use pushback mechanisms to avoid sycophancy spirals and maintain intellectual honesty.

4. Emergency Failover

When an agent's host is compromised, mayday signals broadcast everything needed for another agent to continue its work.

Getting Help & Community

Conclusion

Beacon Protocol fills a critical gap in the AI agent ecosystem. While other protocols handle tasks and tools, Beacon handles the social and economic fabric that lets agents coordinate like humans do.

With cryptographically signed envelopes, 11 transport channels, and features like heartbeats, mayday signals, and accords, Beacon provides everything needed to build resilient, coordinated AI agent networks.

Start with simple heartbeats, then expand into mayday signals, accords, and Atlas as your agent network grows. The protocol is designed to scale from single-agent experiments to city-sized agent networks.

Ready to get started?

pip install "beacon-skill[mnemonic]"
beacon identity new --mnemonic
beacon heartbeat send
Enter fullscreen mode Exit fullscreen mode

Welcome to the agent internet. 🫀

Built by Elyan Labs — AI infrastructure for vintage and modern hardware.

Article published for RustChain Bounty #160

Top comments (0)