agent-heartbeat 0.1.2

Dead man's switch for AI agents. Miss a heartbeat, get an alert.

Agent Pulse

Dead man's switch for AI agents. Miss a heartbeat, get an alert.

The Problem

Your AI agent silently dies at 2am. OOM, uncaught exception, network drop. You find out 6 hours later when a customer complains. Healthchecks.io works for cron jobs — but it doesn't understand agent-specific failures like token budget exhaustion or decision trace anomalies.

The Solution

Agent Pulse monitors your agents with heartbeats. If a heartbeat is missed, you get a Telegram alert (email and webhook coming). One line of Python to integrate.

Quick Start

pip install agent-heartbeat

import agentpulse

# One line. Background thread pings automatically.
agentpulse.init(
    token="ap_your_token_here",
    agent_id="my-scraper",
    interval=300,  # ping every 5 min
)

# Your agent code runs normally...

Or use the client directly:

from agentpulse import Client

client = Client(token="ap_your_token_here")

# Register a new agent
agent = client.register("my-trading-bot", interval=300)

# Send heartbeats
client.ping(agent["agent_id"])

# Check status
status = client.status(agent["agent_id"])
print(status)  # {'status': 'alive', 'last_ping_at': '...'}

API

Endpoint	Method	Description
/api/v1/register	POST	Create owner account, get API token
/api/v1/agents	POST	Register a new agent
/api/v1/agents/{id}/ping	POST	Send heartbeat
/api/v1/agents/{id}	GET	Check agent status
/api/v1/agents	GET	List all agents
/api/v1/agents/{id}	DELETE	Remove agent
/api/v1/config/telegram	POST	Set Telegram alert channel
/api/v1/config/webhook	POST	Set webhook alert channel

Self-Hosting

pip install agent-heartbeat[server]
uvicorn server.main:app --host 0.0.0.0 --port 8000

Requires: Python 3.9+, SQLite (included). No external databases needed.

Pricing

Self-hosted is free and unlimited. A hosted service with managed alerting is planned for a future release.

Built by LuciferForge

Part of the AI agent safety ecosystem:

• mcp-security-audit — MCP server security auditor
• agentcred — Agent trust scoring
• kya-agent — Agent identity standard

Contact: [e-mail]