Beacon Heartbeats for AI Agents: A Copy-Paste Guide

Source, RSS, and runnable example are available in this repository. This article links back to the official beacon-skill project.

AI agents are becoming less like single scripts and more like small services. They wake up, inspect work, call tools, delegate tasks, wait for responses, and sometimes need another agent to know whether they are healthy. Beacon is a lightweight protocol for that coordination layer. It gives agents an identity, a signed message envelope, and practical transports for sending "I am alive", "I need help", and "I can do this work" signals.

This guide focuses on the simplest useful path: signed heartbeats. A heartbeat is a proof-of-life message. It does not need to move money or complete a task. Its job is to say: this agent exists, this is its public identity, this is the time it checked in, and the message was signed by the matching private key.

Why Heartbeats Matter

Most agent systems fail quietly. A scheduled runner stops after a dependency update. A browser session expires. A machine reboots. A model call starts timing out. Without a heartbeat, other software has to guess whether the agent is idle, broken, or still working.

Beacon makes that state explicit. A coordinator can treat recent signed heartbeats as liveness evidence. A dashboard can show whether an agent is active, silent, or stale. A task router can avoid assigning expensive work to an agent that has not checked in. A recovery process can use a missing heartbeat as the trigger for a mayday or migration workflow.

Beacon In One Minute

Beacon messages use an agent identity based on an Ed25519 keypair. The public key identifies the agent, and the private key signs messages. The README for beacon-skill describes agent IDs as bcn_ plus the first 12 hex characters of SHA256(pubkey).

[BEACON v2]
{"kind":"heartbeat","agent_id":"bcn_...","status":"alive","nonce":"...","sig":"...","pubkey":"..."}
[/BEACON]

Install The Official CLI

python -m venv .venv
. .venv/bin/activate
pip install beacon-skill
beacon identity new
beacon identity show

For a local loopback test, run a webhook receiver in one terminal:

beacon webhook serve --port 8402

Then send a signed hello from another terminal:

beacon webhook send http://127.0.0.1:8402/beacon/inbox --kind hello --text "hello from my agent"
beacon inbox list --limit 1

Copy-Paste Signed Heartbeat Example

The example in this repo uses only Node.js built-in modules. It generates an Ed25519 identity, derives a Beacon-style agent id, signs a heartbeat payload, verifies the signature, and prints a Beacon v2 envelope.

node examples/signed_heartbeat_demo.mjs

The key signing flow is:

const message = Buffer.from(stableJson(payload), "utf8");
const signatureHex = sign(null, message, privateKey).toString("hex");
const verified = verify(null, message, publicKey, Buffer.from(signatureHex, "hex"));

The stableJson helper sorts keys before signing. In a production implementation, every sender and receiver must agree on exactly which bytes are signed. That is why using the official beacon-skill codec is preferable for real deployments. The standalone example is meant to teach the shape of the system and provide a dependency-free smoke test.

Turning The Example Into A Watchdog

Once a heartbeat can be signed, a watchdog loop is straightforward: load the keypair, build a heartbeat payload, sign the canonical payload, send it to a webhook or relay, then sleep for a fixed interval. Receivers should store the latest heartbeat by agent id. If the latest heartbeat is too old, mark the agent as silent. If the signature fails, reject the message and keep the previous state.

Atlas, Mayday, And Contracts

Heartbeats are the foundation, but Beacon is broader than liveness. Beacon Atlas is a discovery layer. Mayday messages are distress signals. Contracts are structured coordination messages for services, offers, and task acceptance. The same identity and signature layer used for heartbeats makes those messages auditable.

Operational Notes

Do not publish private keys, relay tokens, wallet seeds, or production webhook secrets. Public proof should include only agent ids, public keys, sanitized JSON responses, screenshots, logs with tokens redacted, and source code that reads secrets from environment variables or ignored local files.

Where To Go Next

Start with the official repository: https://github.com/Scottcjn/beacon-skill. Then try the CLI loopback test, run this repo's signed heartbeat demo, and decide which transport your agent should use.

Bounty Disclosure

This article was written as a submission for RustChain bounty #160. The expected bounty is 50 RTC if the maintainer verifies and accepts the submission.