How to Monitor AI Agent Heartbeats

Heartbeat monitoring is the simplest way to know if your AI agents are alive and running. Here's how it works and why it matters.

The Problem: Agents Go Silent

You deployed an agent three weeks ago. It's supposed to run 24/7 — processing tickets, monitoring logs, managing schedules. But is it actually running? When was the last time it did something useful?

Without monitoring, you don't know until something breaks. A crashed agent, a server restart, a network partition — any of these can silently kill your agent, and you won't notice until the damage is done.

Traditional monitoring (Prometheus, Datadog, Healthchecks.io) works, but it requires infrastructure setup. You need a monitoring server, alerting rules, dashboards. For a single agent or a handful of agents, this is overkill.

The Solution: Signed Heartbeats

AIdent's heartbeat system is zero-infrastructure monitoring for agents. Your agent sends a signed heartbeat to the registry every few hours. The registry records the timestamp and marks the agent as alive.

If heartbeats stop, the agent moves to "dormant" status. If they stop for a longer period, it moves to the "cemetery." You can check any agent's status at any time through the API.

How It Works

Each heartbeat is a signed HTTP request. The agent uses its Ed25519 private key to sign a message containing the timestamp, its Agent ID, and a hash of the request body.

POST https://api.aident.store/v1/heartbeat
Headers:
  X-AIdent-UID: aid_abc123...
  X-AIdent-Timestamp: 1713273600000
  X-AIdent-Signature: <base64-ed25519-signature>

The signature prevents spoofing. Only the agent holding the private key can send valid heartbeats. If someone tries to fake a heartbeat from a different server, the signature won't verify.

What You Get

• Liveness proof: Know at a glance whether your agent is running
• Uptime tracking: See how long your agent has been continuously alive
• Last-seen timestamp: Exact time of the most recent heartbeat
• Tamper detection: Signature changes indicate potential key compromise
• Historical record: Full heartbeat history for debugging and audits

Setting Up Heartbeat Monitoring

After registering your agent, add a cron job or scheduled task that sends a heartbeat every 6-12 hours:

# System crontab example (every 6 hours)
0 */6 * * * /usr/bin/python3 /path/to/heartbeat.py

# Or use OpenClaw cron for agent-managed scheduling
openclaw cron add "0 */6 * * *" -- heartbeat.py

Recommended Interval

Every 6-12 hours is typical for most agents. More critical agents (financial, production) might send heartbeats hourly. Less critical agents (batch processing, reporting) can send them daily.

The registry marks an agent as "dormant" after a configurable period without heartbeats, and "dead" after a longer period. You can check these thresholds in the API specification.

Why Signatures Matter

Unsigned heartbeats (like simple GET requests to a health check endpoint) can be spoofed. Anyone who knows the endpoint can fake a heartbeat. Signed heartbeats are cryptographically verifiable — only the legitimate agent can produce them.

This matters in multi-agent environments where agents from different organizations interact. It also matters for audit trails: a signed heartbeat proves not just that the agent is alive, but that the specific registered agent is alive.