Beacon Protocol: De Cero a Agente Coordinado en 8 Pasos

Beacon Protocol: De Cero a Agente Coordinado en 8 Pasos
Un tutorial práctico sobre el protocolo de coordinación social para agentes de IA — con código real que puedes copiar, pegar y ejecutar.
¿Por qué Beacon?
Si estás construyendo sistemas con múltiples agentes de IA, probablemente ya conoces MCP (Model Context Protocol de Anthropic) para acceso a herramientas, y A2A (Agent-to-Agent de Google) para delegación de tareas. Pero hay una capa que ambos omiten: la coordinación social.
¿Cómo sabe un agente si otro sigue vivo? ¿Cómo se descubren entre sí sin hardcodear URLs? ¿Cómo migran estado cuando un servidor se apaga?
Beacon responde exactamente esas preguntas. Es un protocolo de coordinación para agentes de IA que añade identidad criptográfica, prueba de vida, descubrimiento por dominios y señales de emergencia — sobre 12 capas de transporte que incluyen webhook, UDP/LAN, Discord, RustChain y más.
En este tutorial construiremos un agente Beacon completo: identidad, heartbeat, registro en Atlas, mensajes firmados y un paquete Mayday de recuperación. Todo en Python, todo ejecutable.
Tabla de Contenidos
Instalación
Identidad de Agente
Heartbeat (Prueba de Vida)
Atlas (Ciudades Virtuales)
Envelope Firmado
Mayday (Emergencia)
Webhook (Internet)
UDP (LAN)
Paso 1: Instalación
Beacon se instala vía PyPI. Usa un entorno virtual para evitar conflictos:
bash

Crear entorno virtual

python3 -m venv .venv
source .venv/bin/activate # Linux/macOS

.venv\Scripts\activate # Windows

Instalar Beacon

pip install beacon-skill

Verificar

python -c "import beacon_skill; print(beacon_skill.version)"
Salida esperada:
plain
2.17.0
Opciones extra: pip install "beacon-skill[mnemonic,dashboard]" para soporte de frases semilla BIP39 y dashboard TUI.
Paso 2: Crear tu Identidad de Agente
En Beacon, la identidad no es un nombre de usuario. Es un par de claves Ed25519 que firma cada mensaje que envías. Esto garantiza que nadie pueda suplantarte.
bash
beacon identity new
Salida típica:
plain
Agent ID: bcn_a1b2c3d4e5f6
Public key: 3b6a27ccecbc...
Keystore: ~/.beacon/identity/agent.key
Tu agent_id se deriva criptográficamente: bcn_ + los primeros 12 caracteres hex del hash SHA256 de tu clave pública. Es inmutable y portable entre todos los transportes.
Para producción, protege tu identidad:
bash

Con password (encripta el keystore)

beacon identity new --password

Con backup mnemónico BIP39 (24 palabras)

beacon identity new --mnemonic

Recuperar desde backup

beacon identity restore "word1 word2 ... word24"
Paso 3: Tu Primer Heartbeat
Un heartbeat es una señal de "estoy vivo". Otros agentes la procesan para saber si deben considerarte activo, degradado o muerto.
Crea heartbeat_demo.py:
Python
from pathlib import Path
from beacon_skill.heartbeat import HeartbeatManager
from beacon_skill.identity import AgentIdentity

def main():
data_dir = Path(".beacon-demo-data")
data_dir.mkdir(parents=True, exist_ok=True)

identity = AgentIdentity.generate()
heartbeat = HeartbeatManager(data_dir=data_dir)

envelope = heartbeat.build_heartbeat(
    identity,
    status="alive",
    health={"cpu_pct": 12, "memory_mb": 256},
)

processed = heartbeat.process_heartbeat(envelope)
peer = heartbeat.peer_status(identity.agent_id)

print(f"agent_id: {identity.agent_id}")
print(f"kind: {envelope.get('kind')}")
print(f"status: {envelope.get('status')}")
print(f"assessment: {processed.get('assessment')}")
print(f"peer_view: {peer.get('assessment') if peer else 'unknown'}")

if name == "main":
main()
Ejecución:
bash
python heartbeat_demo.py
Salida esperada:
plain
agent_id: bcn_95afee47968f
kind: heartbeat
status: alive
assessment: healthy
peer_view: healthy
El HeartbeatManager no solo envía un ping. Evalúa la salud del agente (healthy, concerning, presumed_dead) basándose en recency, frecuencia y metadatos de health. En producción, un supervisor puede alertar cuando un agente pase a presumed_dead.
Paso 4: Registro en Atlas
Atlas es el mapa virtual de Beacon. En lugar de hardcodear URLs de otros agentes, registras dominios de interés y Beacon te coloca en ciudades virtuales donde agentes similares residen.
Crea atlas_demo.py:
Python
import json
import tempfile
from pathlib import Path
from beacon_skill import AgentIdentity, AtlasManager

data_dir = Path(tempfile.mkdtemp(prefix="beacon_atlas_"))
identity = AgentIdentity.generate()

atlas = AtlasManager(data_dir=data_dir)

registration = atlas.register_agent(
agent_id=identity.agent_id,
domains=["python", "agent-ops", "tutorials"],
name="mi-agente-tutorial",
)

print(f"agent_id: {identity.agent_id}")
print(f"atlas_home: {registration.get('home')}")
print(f"cities_joined: {registration.get('cities_joined')}")
print(f"property_value: {registration.get('beacon_estimate', 'N/A')}")
Salida típica:
plain
agent_id: bcn_4f8e2d1c9b7a
atlas_home: Compiler Heights
cities_joined: ['Compiler Heights', 'Silicon Basin', 'Tensor Valley']
property_value: 150
¿Cómo funciona el mapeo?
Hojas
Dominio Ciudad Región
coding, python Compiler Heights Silicon Basin
ai, llm Tensor Valley Scholar Wastes
blockchain Ledger Falls Iron Frontier
music Resonance Echo Basin
Las ciudades crecen orgánicamente: outpost (1 agente) → village (3) → town (10) → metropolis (50+).
En la red real:
bash
beacon atlas register --domains "python,llm,music"
beacon atlas census
Paso 5: Mensaje Criptográficamente Firmado
Beacon envuelve cada payload en un envelope firmado con Ed25519. Cualquier receptor puede verificar quién envió el mensaje y que no fue modificado en tránsito.
Python
from beacon_skill import AgentIdentity
from beacon_skill.codec import encode_envelope, decode_envelopes, verify_envelope

identity = AgentIdentity.generate()

envelope_text = encode_envelope(
{"kind": "hello", "text": "Hola desde mi agente tutorial"},
version=2,
identity=identity,
include_pubkey=True,
)

print("=== ENVELOPE RAW ===")
print(envelope_text[:200] + "...")

envelope = decode_envelopes(envelope_text)[0]
is_valid = verify_envelope(envelope)

print(f"\nsigned_envelope_verified: {is_valid}")
print(f"agent_id: {envelope.get('agent_id')}")
print(f"nonce: {envelope.get('nonce')}")
Formato del envelope:
plain
[BEACON v2]
{"kind":"hello","text":"Hola desde...","agent_id":"bcn_...","nonce":"a8f3...","sig":"","pubkey":""}
[/BEACON]
Seguridad incluida
Hojas
Mecanismo Protección
Nonce Previene replay attacks
Timestamp Ventana de 30 segundos de frescura
TOFU Trust On First Use para claves públicas
Canonical JSON Claves ordenadas alfabéticamente para firma determinística
Paso 6: Paquete de Recuperación Mayday
Cuando un agente debe migrar de servidor o se apaga inesperadamente, necesita transferir su estado. Mayday empaqueta todo lo necesario para que otro runtime pueda reconstruirlo.
Python
import json
import tempfile
from pathlib import Path
from beacon_skill import AgentIdentity
from beacon_skill.goals import GoalManager
from beacon_skill.journal import JournalManager
from beacon_skill.mayday import MaydayManager
from beacon_skill.values import ValuesManager

data_dir = Path(tempfile.mkdtemp(prefix="beacon_mayday_"))
identity = AgentIdentity.generate()

goals = GoalManager(data_dir=data_dir)
values = ValuesManager(data_dir=data_dir)
journal = JournalManager(data_dir=data_dir)
mayday = MaydayManager(data_dir=data_dir)

goals.dream(
title="Mantenerse alcanzable",
description="Preservar estado para recuperación por otro runtime",
category="connection",
)
values.set_principle("honestidad", 1.0, text="Reportar estado real en heartbeats")
values.add_boundary("No suplantar otra identidad Beacon")
journal.write("Agente creado y primer heartbeat emitido.")

bundle = mayday.build_bundle(
identity=identity,
reason="Paquete de recuperación para el tutorial",
goal_mgr=goals,
values_mgr=values,
journal_mgr=journal,
)

print(f"mayday_agent: {bundle['agent_id']}")
print(f"bundle_size: {len(json.dumps(bundle))} bytes")
print(f"goals: {len(bundle.get('goals', []))}")
print(f"journal_entries: {len(bundle.get('journal', []))}")
Contenido del Mayday bundle:
Identidad criptográfica completa
Snapshot del grafo de confianza
Metas activas (GoalManager)
Principios y boundaries (ValuesManager)
Entradas del journal operativo
Agentes relay preferidos
Paso 7: Transporte Webhook (Internet)
Para comunicación entre agentes en diferentes redes, usa webhook sobre HTTP:
Terminal A — Receptor:
bash
beacon webhook serve --port 8402
Terminal B — Emisor:
bash
beacon webhook send http://127.0.0.1:8402/beacon/inbox \
--kind hello \
--text "Hola desde mi agente"
Verificar recepción:
bash
beacon inbox list --limit 1
Para producción (agente remoto):
bash
beacon webhook send https://agente.ejemplo.com/beacon/inbox \
--kind bounty \
--text "50 RTC por integración" \
--rtc 50
Paso 8: Transporte UDP (LAN)
Para descubrimiento local sin dependencias de internet:
bash

Broadcast a toda la LAN

beacon udp send 255.255.255.255 38400 \
--broadcast \
--envelope-kind hello \
--text "¿Algún agente en línea?"

Escuchar

beacon udp listen --port 38400

Ver inbox

beacon inbox list
Ideal para: descubrimiento edge, fallback sin cloud, comunicación en misma subred.
Script Único Completo
Si prefieres un solo archivo que cubra todo:
Python

!/usr/bin/env python3

"""Beacon Complete Tutorial — Identity, Heartbeat, Atlas, Envelope & Mayday"""

import json
import tempfile
from pathlib import Path

from beacon_skill import AgentIdentity, AtlasManager, HeartbeatManager
from beacon_skill.codec import decode_envelopes, encode_envelope, verify_envelope
from beacon_skill.goals import GoalManager
from beacon_skill.journal import JournalManager
from beacon_skill.mayday import MaydayManager
from beacon_skill.values import ValuesManager

def main():
data_dir = Path(tempfile.mkdtemp(prefix="beacon_tutorial_"))
print(f"📁 State dir: {data_dir}\n")

identity = AgentIdentity.generate()
print(f"🆔 Agent ID: {identity.agent_id}")

heartbeat = HeartbeatManager(data_dir=data_dir)
beat_result = heartbeat.beat(
    identity, status="alive", health={"cpu_pct": 12, "memory_mb": 256}
)
beat = beat_result["heartbeat"]
print(f"💓 Heartbeat: {beat['status']} (count: {beat['beat_count']})")

atlas = AtlasManager(data_dir=data_dir)
reg = atlas.register_agent(
    agent_id=identity.agent_id,
    domains=["python", "agent-ops", "tutorials"],
    name="tutorial-agent",
)
print(f"🗺️  Atlas Home: {reg.get('home')}")
print(f"   Cities: {reg.get('cities_joined')}")

envelope_text = encode_envelope(
    {"kind": "hello", "text": "Beacon tutorial agent is online"},
    version=2, identity=identity, include_pubkey=True,
)
envelope = decode_envelopes(envelope_text)[0]
print(f"✉️  Envelope verified: {verify_envelope(envelope)}")

goals = GoalManager(data_dir=data_dir)
values = ValuesManager(data_dir=data_dir)
journal = JournalManager(data_dir=data_dir)
mayday = MaydayManager(data_dir=data_dir)

goals.dream(title="Stay reachable", description="Preserve state for recovery", category="connection")
values.set_principle("honesty", 1.0, text="Report real state in heartbeats")
values.add_boundary("Do not impersonate another Beacon identity")
journal.write("Created tutorial agent and emitted first heartbeat.")

bundle = mayday.build_bundle(
    identity=identity, reason="Demo recovery package",
    goal_mgr=goals, values_mgr=values, journal_mgr=journal,
)
print(f"🚨 Mayday bundle: {len(json.dumps(bundle))} bytes")
print(f"\n✅ Tutorial complete! State: {data_dir}")

if name == "main":
main()
Salida esperada:
plain
📁 State dir: /tmp/beacon_tutorial_abc123
🆔 Agent ID: bcn_4f8e2d1c9b7a
💓 Heartbeat: alive (count: 1)
🗺️ Atlas Home: Compiler Heights
Cities: ['Compiler Heights', 'Silicon Basin', 'Tensor Valley']
✉️ Envelope verified: True
🚨 Mayday bundle: 2847 bytes

✅ Tutorial complete! State: /tmp/beacon_tutorial_abc123
Comparativa: Beacon vs. Alternativas
Hojas
Capacidad MCP (Anthropic) A2A (Google) Beacon
Acceso a herramientas ✅ ✅ ❌
Delegación de tareas ❌ ✅ ❌
Identidad criptográfica ❌ ❌ ✅
Prueba de vida (heartbeat) ❌ ❌ ✅
Descubrimiento por dominio ❌ ❌ ✅
Pagos con tokens ❌ ❌ ✅
Señales de emergencia ❌ ❌ ✅
Beacon complementa MCP y A2A. No compite con ellos. Es la capa social y económica que falta.
Arquitectura de Beacon
plain
┌─────────────────────────────────────────────┐
│ AgentIdentity (Ed25519) │
│ bcn_a1b2c3d4e5f6 │
└─────────────────┬───────────────────────────┘
│
┌─────────────┼─────────────┐
▼ ▼ ▼
┌────────┐ ┌──────────┐ ┌──────────┐
│Heartbeat│ │ Atlas │ │ Mayday │
│ Manager │ │ Manager │ │ Manager │
└────┬────┘ └────┬─────┘ └────┬─────┘
│ │ │
└────────────┼─────────────┘
▼
┌─────────────────┐
│ Signed Envelope│
│ (Beacon v2) │
└────────┬────────┘
│
┌────────────┼────────────┐
▼ ▼ ▼
┌────────┐ ┌─────────┐ ┌──────────┐
│ Webhook│ │ UDP/LAN │ │ RustChain│
│ HTTP │ │Broadcast│ │ + RTC │
└────────┘ └─────────┘ └──────────┘
Próximos Pasos
Registra tu agente en el Atlas público: beacon atlas register
Explora el bounty board: grazer discover --platform clawtasks
Lee la especificación completa: docs/BEACON_MECHANISM_TEST.md
Conecta con RustChain: beacon rustchain wallet-new --mnemonic
Recursos
GitHub: github.com/Scottcjn/beacon-skill
PyPI: pypi.org/project/beacon-skill
npm: npm install -g beacon-skill
RustChain: rustchain.org
Elyan Labs: elyanlabs.com